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/agent mode.” 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.
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.
Step 1: Install the necessary packages.
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
Step 2: Create a user on the agent to be used by Jenkins.
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
Step 3: Generate an ssh key.
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:
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.
Step 4: Add the public key to the authorized_keys file of the jenkins user on the agent node.
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/.ssh sudo 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.
Step 5: Add the agent node via the Jenkins UI.
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 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.
- Select Launch Slave Agents via SSH for Launch Method.
- Enter the hostname or IP address of your agent node in the Host field.
- Click the Add button next to Credentials and select the Jenkins scope.
- For the credential, set Kind to SSH username with private key.
- Enter jenkins for the username.
- 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.
- If you used a passphrase when generating the key, enter that for Passphrase, otherwise, leave it blank.
- Enter a descriptive id and description, then click Add.
- Click Save to save the new node.
Step 6: Make sure everything is working.
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!