UrbanCode Deploy

UrbanCode Deploy 10 Minute Tip: Reconfiguring Agent to Relay Mappings

Changing the mappings of Agents to Relays can be a time-consuming business,  until now….

Re-configuring IBM UrbanCode Deploy (UCD) agents to either put them behind a relay or to change the relays they work with used be time-consuming.  You either had to write a UCD process to run on the agent to reconfigure itself or you had to manually go and edit the agents installed.properties file.  In large environments, there can be many 100’s or even 1000’s of agents so this could be an onerous task.

Since release 7.0.1 of UCD a new feature called Agent Configuration Templates was introduced that will allow users to define reusable sets of configurations that can be used to easily migrate existing JMS agents to WEB agents.  What is doesn’t explicitly say is that you can also use it to specify/change the relays an agent should use.  This is the part we’re interested in.

All customers should note that with the UrbanCode Deploy release, we are officially announcing end of support for JMS Communication on June 11th, 2021. All users are strongly encouraged to upgrade to UrbanCode Deploy 7.x, and migrate to the new WebSocket communication.

– UCD release notes

So if we need to change agent relay assignments, if we’ve not already converted to WebSockets we can cover both things off at the same time.

So how do we do this?  First, create an Agent Configuration Template by navigating to Resources > Agent Configuration Templates then click the Create Agent Configuration Template Button.  You should see a dialogue like this:



Give the template a name perhaps related to the firewall region the agent lives in or maybe data center.

In the Server URLs box make an entry for each of your servers URLs.

In the Relay URLs box enter a list of the relays you want a group of agents to connect through and then click Save.

Note: I found that if you try to specify https then you get this error:

Please correct the following errors before submitting this form:

Invalid hostname: https://myrelay:20080

The problem is not the hostname, but the protocol.  You can only specify http.  The agent communications using web sockets have their own end-to-end encryption with the server so the relay can’t read the traffic, they just forward it on.  So this isn’t a reduction in security it also removed the need for the mutual authentication setup for JMS.

Now go to the Resources > Agents screen and find an agent you want to change the relays for.

Click on the … icon in the agent name columns of the agent you want to change and select Set Configuration Template.



Then select the name of the template you want applied to this agent.

Alternatively, you can bulk add agents to the template on the templates screen by clicking the … option next to the template name and selecting Add Agents.

You can filter the list of agents by typing a partial name then the drop-down list is reduced.


After you’ve added an agent to a template you will see an icon appear against the value in the type column for the agent.

Click on the icon and a dialogue box will appear asking you to confirm you want to upgrade to web communications.

The agent will now be upgraded to web communications (if it’s not already configured this way) and also amend the agent relay configuration.

It is worth taking some time to plan the Agent Configuration Templates that you need for the various combinations of relays you would use.  Then you have something that should be re-usable in the future.  For example, perhaps agents need to be moved from one firewall region to another and hence use different relays.  or perhaps you need to balance load by moving agents between relays.

Alan Murphy is an IBM services consultant who has worked with clients to help them adopt new tools and processes for the last 20 years. UrbanCode Deploy and DevOps has been his focus for the last 5 years. He also develops tools to assist clients in tool adoption and blogs on an occasional basis.