How to Setup an Agent Node in Jenkins: A Detailed Guide

Linux
1

In this guide, we’ll walk through setting up an agent node in Jenkins. Adding a Linux-based agent node to your Jenkins master server allows you to distribute the pipeline workload and execute jobs across diverse environments.

Table of Contents

Prerequisites

Before proceeding, ensure the following requirements are met:

  • A running Jenkins master server.

  • A Linux machine to serve as the agent.

  • SSH access to the agent machine.

  • sudo privileges on the agent machine.

Note: This guide uses Rocky Linux 9 for the agent machine.

Setup Agent Node in Jenkins

Let’s begin setting up the agent node.

Establishing Agent Connection via JNLP (Jenkins Node Protocol)

The most effective approach for connecting Jenkins agents involves utilizing the JNLP protocol. This method offers enhanced security and simplified configuration compared to SSH. Here’s how to set it up:

Step 1: Navigate to the Jenkins dashboard and click on Manage Jenkins.

Step 2: Click on Nodes then New Node.

Step 3: Enter a name for the node (e.g., jnlp-agent). Select Permanent Agent and click OK.

Step 4: Configure the node settings:

  • Description: Enter a description for the agent (e.g., “JNLP Agent”).

  • # of executors: Set the number of concurrent jobs this agent can run.

  • Remote root directory: Specify the directory on the agent where Jenkins will store temporary files (e.g., /home/jenkins/agent).

  • Labels: Add labels to categorize the agent (e.g., jnlp).

  • Usage: Choose Use this node as much as possible.

  • Launch method: Select Launch agent by connecting it to the controller.

  • Availability: Choose when the agent should be online.

Step 5: Save the node configuration. Jenkins will provide a JNLP agent secret and instructions for connecting the agent.

Step 6: On the agent machine, download the agent.jar file from the Jenkins master (URL provided on the agent’s page).

Step 7: Run the following command on the agent machine, replacing the <jenkins_url>, <agent_name>, and <agent_secret> with the appropriate values:

java -jar agent.jar -jnlpUrl <jenkins_url>/computer/<agent_name>/jenkins-agent.jnlp -secret <agent_secret>

Step 8: Verify that the agent node is connected and online in the Jenkins dashboard.

Alternative Method: Setting up Agent Node via SSH

1) Prepare the Agent Machine

Let’s prepare the agent machine. SSH into the agent node and install Java using the following command:

$ sudo dnf install java-21-openjdk -y

After installation, verify the Java version:

$ java --version

Next, create a Jenkins user, add it to the wheel group, and generate SSH keys for the Jenkins user.

Run the following commands:

$ sudo useradd -G wheel jenkins
$ sudo passwd jenkins
$ su - jenkins
$ ssh-keygen -t rsa
$ cd .ssh/
$ touch authorized_keys
$ cat id_rsa.pub > authorized_keys

View the content of Jenkins user’s private key using:

$ cat id_rsa

You’ll need this private key when creating credentials in the Jenkins UI.

2) Create Credentials for Agent Node

Navigate to Manage Jenkins → Under Security → Click on Credentials.

Follow these steps:

Step 1: Click Add Credentials.

Step 2: Select SSH Username with private key.

Step 3: Set scope to Global.

Step 4: Enter ID: jenkins-agent-ssh.

Step 5: Description: SSH key for Linux agent.

Step 6: Username: jenkins.

Step 7: Private Key: Select Enter directly.

Step 8: Paste the private key from the agent machine.

Step 9: Click Add.

3) Add the Agent Node

With the prerequisites completed, proceed to add the agent node.

Navigate to Manage Jenkins → Under System Configuration → Click on Nodes → Choose New Node.

Configure these settings:

Step 1: Name: linux-agent.

Step 2: Description: Linux agent.

Step 3: Number of executors: 2.

Step 4: Remote root directory: /home/jenkins/.

Step 5: Labels: linux.

Step 6: Usage: Use this node as much as possible.

Step 7: Launch method: Launch agents via SSH.

Step 8: Host: [Your Agent IP].

Step 9: Credentials: Choose jenkins.

Step 10: Host Key Verification Strategy: Non verifying.

This confirms that a Linux-based agent node has been added to your Jenkins master server.

To test the functionality of the newly added agent, let’s run a sample job on it.

4) Create & Run Job on New Agent node

From the Jenkins GUI, create a freestyle project job and force the job to run on the newly added Linux-based agent node.

Console logs of the job will confirm that it has been executed on the new Linux-based agent node.

Following these steps, you can successfully set up an agent node in Jenkins, enabling distributed builds and tests across your infrastructure.