Using Jenkins agents

The Jenkins architecture is designed for distributed build environments. It allows us to use different environments for each build project balancing the workload among multiple agents running jobs in parallel.

The Jenkins controller is the original node in the Jenkins installation. The Jenkins controller administers the Jenkins agents and orchestrates their work, including scheduling jobs on agents and monitoring agents. Agents may be connected to the Jenkins controller using either local or cloud computers.

The agents require a Java installation and a network connection to the Jenkins controller. View the 3 minute video below for a brief explanation of Jenkins agents.

What is a Jenkins Agent

Configuring agents with Docker

Jenkins agents can be launched in physical machines, virtual machines, Kubernetes clusters, and with Docker images. This section connects Docker agents to Jenkins with SSH.

Environment

To run this guide you will need a machine with:

Java installation
Jenkins installation
Docker installation
SSH key pair

If you need help to install Java, Jenkins and Docker please visit the section Installing Jenkins.

Generating an SSH key pair

To generate the SSH key pair, you have to execute a command line tool named ssh-keygen on a machine you have access to. It could be:

the machine on which your Jenkins controller runs
the host (if using containers)
a machine on which you have an agent running
or even your developer machine

The SSH key pair generation can be done on any operating system:

On Windows, you can use any OpenSSH installation such as Windows OpenSSH, the ssh-keygen that is included with git for Windows, or Cygwin
On Unix (Linux, macOS, BSD, etc.) you can use any OpenSSH installation packaged with your system as well

Note that you will have to be able to copy the key value to your controller and agent afterwards, so check that you can copy a file content into the clipboard beforehand.

In a terminal window run the command: ssh-keygen -f ~/.ssh/jenkins_agent_key
Provide a passphrase to use with the key (it can be empty)

Confirm the output looks something like this:

ubuntu@desktop:~$ ssh-keygen -f ~/.ssh/jenkins_agent_key
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/ubuntu/.ssh/jenkins_agent_key
Your public key has been saved in /home/ubuntu/.ssh/jenkins_agent_key.pub
The key fingerprint is:
SHA256:XqxxjqsLlvDD0ZHm9Y2iR7zC6IbsUlMEHo3ffy8TzGs
The key's randomart image is:
+---[RSA 3072]----+
|  o+             |
| ...o  .         |
|  .o .+ .        |
|    o+.+ o o     |
|  ... o.So* .    |
|  o+ = +.X=      |
| o oO + *..+     |
|. oo.o o .E .    |
| o... oo.. o     |
+----[SHA256]-----+

Create a Jenkins SSH credential

From your Jenkins dashboard, navigate to Manage Jenkins.
In the Security section, select Credentials.
Under Stores scoped to Jenkins, select Add Credentials from the global option.
Fill in the following information, as shown in the example, substituting your information as needed:
- Kind: SSH username with private key
- ID: jenkins
- Description: The Jenkins SSH key
- Username: jenkins
- Private Key: Select Enter directly and then select Add to insert the content of your private key file (~/.ssh/jenkins_agent_key).
- Passphrase: Enter the passphrase used to generate the SSH key pair (or leave it empty if you didn’t use one in the previous step).
Select Create to complete your credential configuration.

Creating your Docker agent

On Linux

Here we will use the docker-ssh-agent image to create the agent containers.

run the command to start your first agent:

docker run -d --rm --name=agent1 -p 22:22 \
-e "JENKINS_AGENT_SSH_PUBKEY=<your_public_key>" \
jenkins/ssh-agent:alpine-jdk21

Remember to replace the tag <your_public_key> for your own SSH public key.
Your public key value in this example could be found by issuing : cat ~/.ssh/jenkins_agent_key.pub on the machine your created it. Do not add the square brackets [] around the key value
The value of [your-public-key] MUST include the full contents of your .pub file, including the ssh-XXXX prefix.
- Ex: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAQQCo9+BpMRYQ/dL3DS2CyJxRF+j6ctbT3/Qp84+KeFhnii7NT7fELilKUSnxS30WAvQCCo2yU1orfgqr41mM70MB
If your machine already has a ssh server running on the 22 port (if you logged onto this machine thanks to the ssh command, that’s the case), you should use another port for the docker command, such as -p 4444:22

Now the container agent1 is running.
Hint: the command docker ps can be used to check if the container is running as expected.

On Windows

Here we will use the docker-ssh-agent image to create the agent containers.

run the command to start your first agent:
```
docker run -d --rm --name=agent1 --network jenkins -p 22:22 `
  -e "JENKINS_AGENT_SSH_PUBKEY=<your_public_key>" `
  jenkins/ssh-agent:jdk21
```
Remember to replace the tag <your_public_key> for your own SSH public key.

Your public key in this example is: Get-Content $Env:USERPROFILE\.ssh\jenkins_agent_key.pub
Now the container agent1 is running.
Hint: the command docker ps can be used to check if the container is running as expected. Additionally, the command docker container inspect agent1 | Select-String -Pattern '"IPAddress": "\d+\.\d+\.\d+\.\d+"' can be used to see the Host to be set in Jenkins for the agent.

Set up `agent1` on Jenkins

From your Jenkins dashboard, navigate to Manage Jenkins.
Select Nodes.
Select New Node to create your agent.
Enter your Node name, select the Permanent Agent option, and select Create.
On the agent creation page fill in the fields:
- Remote root directory
- Labels
- Usage
- Launch method
  - Host
  - Credentials
  - Host Key verification Strategy
Select Save and agent1 will be registered, but offline for the time being. Select the agent1 node to view its status.
The status page should show the message: This node is being launched. If that’s not the case, select Relaunch agent and wait a few seconds.
After waiting, select the Log option to view the logs. At the bottom of the log, you should receive the message: Agent successfully connected and online.

If your Jenkins controller does not start the agent via ssh, please check the port you configured on your agent. Copy the port number and then select Advanced. Under Advanced, you can paste the port number into the Port field.

Delegating the first job to `agent1`

From your Jenkins dashboard select New Item.
Enter a name, for example, First job on agent1.
Select Freestyle project and select OK to create the job.
Select the option Restrict where this project can be run.
Enter the node label (agent1) in the Label Expression field.

Be careful with white spaces before or after the label.
Select the Execute shell option from the Build Steps dropdown;
Add the command: echo $NODE_NAME in the Command field and the name of the agent will be printed inside the log when this job is run.
Select Save and then select Build Now.
Wait a few seconds, and then go to Console Output page. You should receive output similar to:

Restarting a Jenkins agent

This video provides instructions on how to restart a Jenkins agent using various methods.

User Handbook

Tutorials

Resources

Using Jenkins agents

Configuring agents with Docker

Environment

Generating an SSH key pair

Create a Jenkins SSH credential

Creating your Docker agent

On Linux

On Windows

Set up `agent1` on Jenkins

Delegating the first job to `agent1`

Restarting a Jenkins agent

User Handbook

Tutorials

Resources

Using Jenkins agents

Configuring agents with Docker

Environment

Generating an SSH key pair

Create a Jenkins SSH credential

Creating your Docker agent

On Linux

On Windows

Set up agent1 on Jenkins

Delegating the first job to agent1

Restarting a Jenkins agent

Set up `agent1` on Jenkins

Delegating the first job to `agent1`