Chapter 27: Jenkins Agents

27.1 Labels

By Ravindra Bagale · Last updated: 25 October 2026

Why: the problem

Think of Swiggy. It has one Jenkins controller and more than a hundred build jobs. Some jobs need Node.js 20. Some need Java 17 and Maven. Some need Docker. Some need a GPU for model tests. If every job runs on the controller, three bad things happen. First, the controller CPU hits 100 percent and the Jenkins web page becomes slow for everyone. Second, one job installs a tool that breaks another job. Third, a build script can read the controller disk, where all secrets and job configs live. So Jenkins splits the work. The controller only plans and shows results. Agents are separate machines that run the builds. A label is a simple tag on an agent, like node20 or maven or docker. The Jenkinsfile asks for a label, and Jenkins sends the build to any online agent with that label. In this lesson you will add labels, use them in a Jenkinsfile, combine labels with and, or and not, and set the controller to run zero builds.

What we will build

You will run a lab Jenkins controller in Docker. You will add two agents, one with labels linux node20 and one with labels linux maven docker. You will write three Jenkinsfiles that pick agents by label, by label expression, and per stage. Finally you will set the built-in node to 0 executors and prove that builds still run, but only on agents.

What: every term in plain English

• Controller — The main Jenkins server. It stores jobs, shows the web page and schedules builds. It should not run builds.
• Agent — A separate machine or container that runs build steps for the controller. Old name: slave or node.
• Node — Jenkins word for any machine that can run builds, including the controller itself, called the built-in node.
• Executor — One build slot on a node. An agent with 2 executors can run 2 builds at the same time.
• Label — A tag on an agent, like linux, node20 or docker. Jobs ask for labels, not machine names.
• Label expression — A small rule like linux and docker, or maven || gradle, or !windows.
• Usage mode — Agent setting. Use this node as much as possible, or Only build jobs with label expressions matching this node.
• Remote root directory — The folder on the agent where Jenkins keeps workspaces, like /home/jenkins/agent.

How: step by step

1. Start a lab controller

   docker network create jenkins
   docker run -d --name jenkins --network jenkins -p 8080:8080 -p 50000:50000 -v jenkins_home:/var/jenkins_home jenkins/jenkins:lts-jdk17
   

   What it does: Starts Jenkins with the web port 8080 and agent port 50000.

   Output

   3f9a1c... (container ID)
   

2. Get the first admin password

   docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
   

   What it does: Prints the one-time unlock password.

   Output

   5b2e8c0d4f... (32 characters)
   

3. Open the Nodes page

   Manage Jenkins > Nodes > New Node > name agent-node20 > Permanent Agent
   

   What it does: Creates the agent entry on the controller.

   Output

   Page shows agent-node20 (offline)
   

4. Give labels

   Labels: linux node20   Executors: 2   Remote root: /home/jenkins/agent   Usage: Only build jobs with label expressions matching this node
   

   What it does: Space separated labels. The strict usage mode stops random jobs landing here.

   Output

   Saved
   

5. Check labels from the script console

   Manage Jenkins > Script Console > Jenkins.instance.nodes.each { println it.nodeName + " -> " + it.labelString }
   

   What it does: Lists every agent and its labels.

   Output

   agent-node20 -> linux node20
   agent-maven -> linux maven docker
   

6. Use the label in a Jenkinsfile

   agent { label 'node20' }
   

   What it does: The whole pipeline runs on an agent with node20.

   Output

   Running on agent-node20 in /home/jenkins/agent/workspace/badge-node
   

7. Set built-in executors to 0

   Manage Jenkins > Nodes > Built-In Node > Configure > Number of executors: 0
   

   What it does: The controller now runs no builds at all.

   Output

   Built-In Node: 0 executors
   

Example 1: Pick one agent by label for the whole pipeline

Stack. Jenkins LTS, permanent Linux agent, Node.js 20

Goal. Pick one agent by label for the whole pipeline.

Jenkinsfile

pipeline {
  agent { label 'node20' }
  options { timestamps() }
  stages {
    stage('Where am I') {
      steps {
        sh 'hostname'
        echo "Node name: ${env.NODE_NAME}"
        echo "Labels: ${env.NODE_LABELS}"
        sh 'node --version && npm --version'
      }
    }
    stage('Test') {
      steps {
        sh 'npm ci'
        sh 'npm test'
      }
    }
  }
}

What each line does

• agent { label 'node20' } — Send the whole build to any online agent that has the node20 label.
• options { timestamps() } — Adds a clock time to every console line. Needs the Timestamper plugin.
• env.NODE_NAME — Built-in variable with the name of the agent that runs the build.
• env.NODE_LABELS — All labels of that agent, space separated.
• sh 'node --version' — Proves the right tool is installed on this agent.
• sh 'npm ci' — Clean install of packages from package-lock.json.

Green output

Running on agent-node20 in /home/jenkins/agent/workspace/badge-node
[Pipeline] stage (Where am I)
+ hostname
ip-10-0-1-25
Node name: agent-node20
Labels: agent-node20 linux node20
+ node --version
v20.15.1
10.7.0
[Pipeline] stage (Test)
+ npm ci
added 212 packages in 6s
+ npm test
Tests: 14 passed, 14 total
Finished: SUCCESS

Expected result. The build ran on agent-node20, not on the controller. Node and npm came from the agent.

Example 2: Use label expressions with and, or and not

Stack. Jenkins, two permanent agents

Goal. Use label expressions with and, or and not.

Jenkinsfile

pipeline {
  agent none
  stages {
    stage('Java build') {
      agent { label 'linux && maven' }
      steps {
        sh 'mvn -v | head -1'
        sh 'mvn -B -q package -DskipTests'
      }
    }
    stage('Image build') {
      agent { label 'docker && !windows' }
      steps { sh 'docker version --format "{{.Server.Version}}"' }
    }
    stage('Any JVM tool') {
      agent { label 'maven || gradle' }
      steps { echo "Picked ${env.NODE_NAME}" }
    }
  }
}

What each line does

• agent none — No agent for the whole pipeline. Each stage picks its own.
• label 'linux && maven' — Both labels must be on the agent.
• label 'docker && !windows' — Has docker and does not have windows.
• label 'maven || gradle' — Either label is fine.
• mvn -B -q package — Batch mode, quiet output, build the jar.
• Per stage agent — Each stage can go to a different machine. Files do not move by themselves; use stash for that (chapter 21).

Green output

[Pipeline] stage (Java build)
Running on agent-maven in /home/jenkins/agent/workspace/badge-java
+ mvn -v
Apache Maven 3.9.8
[Pipeline] stage (Image build)
Running on agent-maven in /home/jenkins/agent/workspace/badge-java
+ docker version --format {{.Server.Version}}
26.1.4
[Pipeline] stage (Any JVM tool)
Picked agent-maven
Finished: SUCCESS

Expected result. Each stage found a matching agent. Change maven to gradle in one agent and watch the third stage still pass.

Example 3: Prove the controller runs zero builds

Stack. Jenkins Script Console

Goal. Prove the controller runs zero builds.

check-executors.groovy

// Manage Jenkins > Script Console
def j = Jenkins.instance
println "Built-in executors: " + j.numExecutors
j.computers.each { c ->
  println c.name.padRight(16) + " online=" + !c.offline + " executors=" + c.numExecutors + " labels=" + c.node.labelString
}

Jenkinsfile (bad on purpose)

pipeline {
  agent { label 'built-in' }
  stages { stage('x') { steps { echo 'never runs' } } }
}

What each line does

• j.numExecutors — Number of executors on the built-in node. Should be 0.
• j.computers — Every node Jenkins knows, with live status.
• c.offline — True when the agent is not connected.
• label 'built-in' — The label of the controller itself. With 0 executors this build waits forever.
• Abort it — Cancel the stuck build from the queue. This proves the controller is protected.

Green output

Built-in executors: 0
                 online=true executors=0 labels=
agent-node20     online=true executors=2 labels=linux node20
agent-maven      online=true executors=2 labels=linux maven docker

(bad Jenkinsfile)
Still waiting to schedule task
Waiting for next available executor on 'built-in'

Expected result. The controller has 0 executors. Any job that asks for it waits. Real jobs go to agents only.

Verify: did it work?

1. Count builds per agent

   Manage Jenkins > Nodes > agent-node20 > Build History
   

   What it does: Shows only builds that ran on this agent.

   Output

   badge-node #12  agent-node20  SUCCESS
   

2. Label page

   http://localhost:8080/label/node20/
   

   What it does: Shows all agents with this label and how busy they are.

   Output

   Nodes: agent-node20 (idle)
   

When it is red 1

Waiting for next available executor on 'node20'
There are no nodes with the label 'node20'

Cause. No agent has this label, or the label is misspelled, like node-20.

Fix, step by step

1. Open Manage Jenkins > Nodes and read the labels.
2. Fix the spelling in the agent or the Jenkinsfile.
3. Open /label/node20/ to confirm one agent appears.

When it is red 2

Waiting for next available executor on 'agent-node20'
agent-node20 is offline

Cause. The agent has the label but is not connected.

Fix, step by step

1. Open the agent page and read the log.
2. Restart the agent service (lesson 27.2).
3. Check port 50000 or SSH port 22 is open.

When it is red 3

npm: command not found

Cause. The build landed on an agent without Node, because the label was too loose, like linux.

Fix, step by step

1. Use a specific label, like node20.
2. Put tool labels only on agents that really have the tool.
3. Print node --version as the first step.

Cleanup

1. Remove a lab agent

   Manage Jenkins > Nodes > agent-node20 > Delete Agent
   

   What it does: Removes the agent entry. Workspaces on the machine stay.

   Output

   agent-node20 deleted
   

2. Stop the lab controller

   docker rm -f jenkins && docker volume rm jenkins_home && docker network rm jenkins
   

   What it does: Deletes the lab completely.

   Output

   jenkins
   jenkins_home
   jenkins
   

Practice tasks

Homework: try at home

Recap

• The controller schedules; agents build.
• Labels are tags; Jenkinsfiles ask for labels.
• Label expressions use &&, || and !.
• Use strict usage mode on special agents.
• Set the built-in node to 0 executors.

FAQ

Can one agent have many labels?

Yes. Separate them with spaces, like linux node20 docker.

Is the agent name also a label?

Yes. Every agent has its own name as a label, but use tool labels instead.

How many executors per agent?

Usually one per CPU core for light builds, fewer for heavy Java or Docker builds.

Do agents need Jenkins installed?

No. They need Java and the small agent.jar, or SSH with Java.

What happens if two agents share a label?

Jenkins picks any free one. That gives you simple load balancing.

Interview questions

1. Why should the controller have zero executors?

   Builds on the controller can read its home folder with secrets and job configs, and heavy builds slow the UI. Agents isolate the work.

2. What is a Jenkins label?

   A tag on an agent that jobs use to pick the kind of machine they need, for example node20 or docker.

3. How do you send one stage to a different machine?

   Use agent none at the pipeline level and an agent block with a label inside each stage.

4. A build waits forever with no nodes with the label. What do you check?

   Label spelling, whether any agent has that label, and whether that agent is online.

5. What is an executor?

   A build slot on a node. Executors decide how many builds run at once on that machine.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards