Demo Create and Configure Node

This tutorial shows how to offload build execution from your Jenkins controller to a dedicated agent (node), improving scalability and performance. We’ll provision an Ubuntu VM (ubuntu-docker-jdk17-node20) and connect it as a Jenkins agent using JNLP.

Prerequisites

A running Jenkins controller (installation guide)
A VM with a matching JDK installed
Network connectivity between controller and agent

1. Add a New Node in Jenkins

On the Jenkins controller, go to Manage Jenkins → Manage Nodes and Clouds.
Click New Node, enter a name (e.g., Ubuntu-Agent), select Permanent Agent, and OK.

The image shows a Jenkins dashboard displaying node information, including architecture, clock difference, and disk space details. The interface is dark-themed with options to manage nodes and configure monitors.

Fill in the node configuration:

Field	Purpose	Example
Description	Brief summary of this agent’s role	`Ubuntu build executor`
# of Executors	Max concurrent builds this agent can run	`2`
Remote Root Directory	Directory on the agent for workspaces, logs, and artifacts	`/home/jenkins-agent`
Labels	Tags for targeting in jobs or pipelines	`docker jdk17 ubuntu`
Usage	Restrict builds to labels matching this node	`Only build jobs with label expressions matching this node`
Launch method	How the agent connects (e.g., JNLP)	`Launch agent by connecting from the controller`
Availability	Agent online policy	`Keep this agent online as much as possible`

The image shows a Jenkins configuration page for creating a new node, with fields for description, number of executors, remote root directory, and labels.

Note

Under Node Properties, you can add environment variables or enable disk space monitoring to maintain agent health.

The image shows a Jenkins dashboard interface with node properties settings, including disk space monitoring thresholds and environment variables. There are options to add variables and save changes.

Click Save. The agent remains offline until it connects to the controller.

2. Enable TCP Inbound Agent Port

Navigate to Manage Jenkins → Configure Global Security.
Under Agents → TCP port for inbound agents, select Fixed or Random.
Click Save.

3. Connect the Agent from the Command Line

On the agent VM (ubuntu-docker-jdk17-node20):

# Go to a working directory
cd /home

# Download the Jenkins agent JAR
curl -sO http://<JENKINS_HOST>:8080/jnlpJars/agent.jar

# (Optional) Store the agent secret securely
echo <SECRET_TOKEN> > secret-file
chmod 600 secret-file

# Launch the agent with JNLP
java -jar agent.jar \
  -url http://<JENKINS_HOST>:8080/ \
  -secret @secret-file \
  -name "ubuntu-agent" \
  -workDir "/home/jenkins-agent"

Warning

Keep the secret-file secure. Exposing the JNLP secret allows unauthorized agents to connect.

A successful connection shows:

INFO: Connected
Inbound agent connected from 165.233.191.207:55522
This is a Unix agent
Agent successfully connected and online

4. Verify the Agent in Jenkins

Return to Manage Nodes and Clouds and confirm Ubuntu-Agent is online:

The image shows a Jenkins interface displaying system information for an "ubuntu-agent," with options to view system properties, environment variables, and other details. The sidebar includes various menu options like status, configure, and log.

Use JavaMelody Monitoring for system reports:

The image shows a Jenkins dashboard with JavaMelody Monitoring options for system reports and actions on an "ubuntu-agent" node. It includes options like viewing threads, OS processes, memory histograms, and executing system actions.

5. Inspect the Agent Workspace

On the agent VM:

root@ubuntu-docker-jdk17-node20:/home# ls
agent.jar  jenkins-agent

root@ubuntu-docker-jdk17-node20:/home# cd jenkins-agent
root@ubuntu-docker-jdk17-node20:/home/jenkins-agent# ls
remoting

As builds run, Jenkins creates workspaces, logs, and artifacts directories under /home/jenkins-agent.

Next, we’ll run a sample job on this agent to demonstrate distributed execution.

Links and References

Watch Video

Watch video content