Adding a Jenkins Agent Node

The master/ controller is the central, coordinating process which stores configuration, loads plugins, and renders the various user interfaces for Jenkins.

An agent is typically a machine or container that connects to a Jenkins master and is designed to perform the tasks when directed by the master.

A single, monolithic Jenkins installation can work great for a small team with a relatively small number of projects. As your needs grow, however, it often becomes necessary to scale up. Jenkins provides a way to do this called "master to agent connection." Instead of serving the Jenkins UI and running build jobs all on a single system, you can provide Jenkins with agents to handle the execution of jobs while the master serves the Jenkins UI and acts as a control node.

Get started with ACG and transform your career with courses and real hands-on labs in AWS, Microsoft Azure, Google Cloud, and beyond.

In this post, I'd like to give you a brief walkthrough of how to set up a Jenkins agent. You can find additional information about Jenkins agent nodes here. You will need:

• A Jenkins installation to act as the master
• A server to act as an agent node

I based this guide upon Jenkins version 2.89.4 LTS. I'll provide some commands that can be used to do all of these steps on a CentOS 7 machine.

You will need to install some packages on the agent node, such as Java, as well as any tools that you may require to run your builds (Git, Maven, Ant, Gradle, etc.). I'll install Java and Git:

sudo yum -y install java-1.8.0-openjdk git

Now we need to create a user on the agent. The Jenkins master will log into the agent as this user, and all build jobs will execute as this user. It makes sense to call this user jenkins, and we'll give them a special home directory where the Jenkins agent's files will reside:

sudo useradd -d /var/lib/jenkins jenkins

Next, we need to generate an ssh key. Jenkins will use this key to authenticate with the agent node and log in as the jenkins user. This key can generate on practically any Linux machine, but you can also do it on the agent node itself:

ssh-keygen

This command will provide a series of prompts. Feel free to use the defaults. From a security perspective, it may be a good idea to enter a passphrase when prompted, and if you do so make sure you take note of the passphrase you used since you will need it later. This command will output two files: id_rsa and id_rsa.pub. If you're already familiar with the process of working with ssh keys in Linux, this will be very familiar to you, but if not, don't worry. I'll walk you through how to use these keys! By default, these files are located in ~/.ssh/. When you run ssh-keygen, you have the option of specifying another location.

Next, we need to add the public key (the contents of id_rsa.pub) to the authorized_keys file of the jenkins user that we created earlier. This will allow anyone who has the private key (in our case, the Jenkins master) to log in to the agent node as the jenkins user. First, we need to create the directory that the authorized_keys file belongs in, and then we can create the file itself:

sudo mkdir /var/lib/jenkins/.sshsudo vi /var/lib/jenkins/.ssh/authorized_keys

Copy the entire contents of the id_rsa.pub file that you generated earlier (~/.ssh/id_rsa.pub by default) and paste it into authorized_keys, then save it.

Now we're ready to finish setting up the node via the Jenkins UI. In Jenkins, go to Manage Jenkins, then Manage Nodes, then click New Node. Here you can give your agent node a name, then select Permanent Agent and click OK. There are a variety of options you can use here to customize your node. All we care about right now is the Launch Method.

1. Select Launch Slave Agents via SSH for Launch Method.
2. Enter the hostname or IP address of your agent node in the Host field.
3. Click the Add button next to Credentials and select the Jenkins scope.
4. For the credential, set Kind to SSH username with private key.
5. Enter jenkins for the username.
6. For the private key, select Enter directly. Then, copy the contents of your private key file (~/.ssh/id_rsa by default) and paste it into the Key box.
7. If you used a passphrase when generating the key, enter that for Passphrase, otherwise, leave it blank.
8. Enter a descriptive id and description, then click Add.
9. Click Save to save the new node.

Your new node should now appear in the list of nodes. You may notice a red X on the node's icon. This indicates that it is not connected, but that's because we just added it and it hasn't had a chance to connect yet. Wait a few seconds and refresh the page, and the red X will go away, indicating that the node is connected. Congratulations! You have successfully created a Jenkins agent node!

Interested in learning more about Jenkins? Check out our Jenkins Fundamentals course to build foundational knowledge. Or, try our Certified Jenkins Engineer course that prepares you for the Certified Jenkins Engineer exam.

A Cloud Guru makes it easy (and awesome) to level up your cloud career — whether you’re new to cloud or a seasoned pro. Check out ACG’s free courses or get started now with a free trial.