Distributed builds

The most popular ways agents are configured are via connections that are initiated from the controller. This allows agents to be minimally configured and the control lives with the controller. This does require that the controller have network access (ingress) to the agent (typically this is via ssh). In some cases this is not desirable due to security network rules, in which case you can use Agent to controller connections via an inbound agent.

In some cases the agent will not be visible to the controller, so the controller can not initiate the agent process. You can use a different type of agent configuration in this case called an "inbound agent". This means that the controller does not need network "ingress" to the agent (but the agent will need to be able to connect back to the controller). Handy for if the agents are behind a firewall, or perhaps in some more secure environment to do trusted deploys (as an example). See the sections below to choose the type of agent that is most appropriate for your needs.

As you will see below, agents can be labelled. This means different parts of your build, or pipeline, can be allocated to run on specific agents (based on their label). This can be useful for tools, operating systems or perhaps for security purposes (it is possible to set quite detailed access rules of what can run where, based on agent configurations). A server that runs an agent is often referred to as a "node" in Jenkins.

Jenkins has a built-in SSH client implementation that it can use to talk to remote sshd and start an agent. This is the most convenient and preferred method for Unix agents, which normally has sshd out-of-the-box. Click Manage Jenkins, then Manage Nodes, then click New Node. In this set up, you’ll supply the connection information (the agent host name, user name, and ssh credential). Note that the agent will need the controller’s public ssh key copied to the ~/.ssh/authorized_keys file of the account that will run the agent. (This is a decent howto if you need ssh help). Jenkins will do the rest of the work by itself, including copying the binary needed for an agent, and starting/stopping agents. If your project has external dependencies (like a special ~/.m2/settings.xml, or a special version of java), you’ll need to set that up yourself, though. The configuration file provider plugin and the agent setup plugin may help with agent configuration.

This is the most convenient set up on Unix. Windows users may install OpenSSH for Windows. They may also use the SSH installation from Git for Windows or cygwin. However, if you are on Windows and you don’t have ssh commands with cygwin for example, you can Windows specific tools like PuTTY and PuTTYgen can also be used generate your private and public key pairs.

See the configuration guide of the SSH Build Agents for more agent configuration details, including:

For Windows agents, the WMI windows agents plugin can use the remote management facility (WMI and DCOM, to be more specific). In this configuration, you’ll supply the username and the password of the user who has the administrative access to the system, and Jenkins will use that remotely create a Windows service and remotely start/stop them.

Configuring agents with DCOM is complicated by dependencies on specific configurations related to Windows kernel version and system version. In many cases, Windows OpenSSH or cygwin will provide a better experience for the Jenkins administrator and for Jenkins users.

Note: Unlike other Node’s configuration type, the Node’s name is very important as it is taken as the node’s address where to create the service

If the above turn-key solutions do not provide flexibility necessary, you can write your own script to start an agent. You place this script on the controller, and tell Jenkins to run this script whenever it needs to connect to an agent.

Typically, your script uses a remote program execution mechanism like SSH, or other similar means (on Windows, this could be done by the same protocols through cygwin or tools like psexec), but Jenkins doesn’t really assume any specific method of connectivity.

What Jenkins expects from your script is that, in the end, it has to execute the agent program like java -jar agent.jar, on the right computer, and have its stdin/stdout connect to your script’s stdin/stdout. For example, a script that does “ssh` mynode `java -jar ~/bin/agent.jar” would satisfy this.
(The point is that you let Jenkins run this command, as Jenkins uses this stdin/stdout as the communication channel to the agent.).

A copy of agent.jar can be downloaded from http://yourserver:port/jnlpJars/agent.jar . Many people write scripts in such a way that this 160K jar is downloaded during the running of said script, to ensure that a consistent version of agent.jar is always used. Such an approach eliminates the agent.jar updating issue discussed below. Note that the SSH build agents plugin plugin does this automatically, so agents configured using this plugin always use the correct agent.jar.

Another way of doing this is to start an agent by downloading agent.jar through a web browser and running a batch file, PowerShell script, or shell script to start the agent.

It requires the server to be configured to appear in first place. Enable inbound agent communication from Manage_Jenkins → Configure Global Security → TCP port for inbound agents.

In this approach, you’ll interactively logon to the agent node, open a browser, and open the agent page. You’ll be then presented with the line to be inserted into the launch script.

Refer to the Jenkins agent instructions for step by step configuration instructions.

This mode is convenient when the controller cannot initiate a connection to agents, such as when it runs outside a firewall while the rest of the agents are in the firewall. On the other hand, if the machine with an agent goes down, the controller has no way of re-launching it on its own.

If you need display interaction (e.g. for GUI tests) on Windows and you have a dedicated (virtual) test machine, this is a suitable option. Create a jenkins user account, enable auto-login, and put a shortcut to the script in the Startup items. This allows one to run tests as a restricted user as well.

Also note that the agents are a kind of a cluster, and operating a cluster (especially a large one or heterogeneous one) is always a non-trivial task. For example, you need to make sure that all agents have JDKs, Ant, Git, and/or any other tools you need for builds. You need to make sure that agents are up and running, etc. Jenkins is not a clustering middleware, and therefore it doesn’t make this any easier. Nevertheless, one can use a server provisioning tool and configuration management software to facilitate both aspects.

Labels are defined in the settings of static agents and for agent clouds. They must be space separated words which define that agent. Sticking to standard ASCII characters is recommended. Here’s a few label suggestions one can use for agent agents:

The Platform Labeler plugin can be used to add operating system, operating system version, and architecture labels automatically.

Jobs and pipelines can be pinned to specific agents or groups of agents if multiple agents have similar sets of labels. In jobs, visit advanced settings and choose restrict where the job can run. In pipelines, you would restrict it with the node block. You can restrict jobs by specifying a single label or use a label expression. Here are two examples:

The above label expression means that a given agent must have all of those labels.

If a newer version of the Jenkins windows service wrapper (jenkins-slave.exe) is available it will be replaced and used on the next start of the service. On very rare occasions the service wrapper may change its behaviour that would require a change in configuration of the service. This can not be done automatically as the service configuration may not be the default and as such could break an installation.

A quick fix of this is to uninstall the jenkins service then verify the service xml is up-to-date (and contains any site configuration such as the user credentials) and then re-install the service.