Jenkins Lesson 4 – Master and Agent Model | Dataplexa

Jenkins Course

I. Jenkins Fundamentals
1. What is Jenkins 2. Why Jenkins is Used 3. Jenkins Architecture 4. Master and Agent Model 5. Jenkins Installation Overview 6. Initial Setup and UI 7. Jenkins Jobs Overview 8. Freestyle Jobs 9. Build Lifecycle 10. Beginner Best Practices
II. Jenkins Pipelines
11. What is Jenkins Pipeline 12. Declarative vs Scripted 13. Jenkinsfile Introduction 14. Pipeline Syntax 15. Stages and Steps 16. Environment Variables 17. Job Parameters 18. Credentials Management 19. Pipeline Triggers 20. Pipeline Notifications 21. Pipeline with Git 22. Pipeline with Docker 23. Pipeline with Kubernetes 24. Handling Pipeline Failures 25. Pipeline Best Practices
III. Security, Plugins & Scaling
26. Plugins Overview 27. Plugin Management 28. Jenkins Security Model 29. Users, Roles and Permissions 30. Securing Credentials 31. Backup and Restore 32. Logging and Monitoring 33. Performance Tuning 34. Distributed Builds 35. Scaling Jenkins
IV. Advanced Jenkins & Real-World
36. Jenkins as Code 37. Configuration as Code 38. Jenkins in Cloud Environments 39. Jenkins on Kubernetes 40. Jenkins and Infrastructure as Code 41. Jenkins for Microservices 42. Migration Strategies 43. Troubleshooting 44. Jenkins Anti-Patterns 45. Mini Project
Section I · Lesson 4

Master and Agent Model

You saw the architecture on paper in Lesson 3. Now let's go deep — how does the master actually talk to an agent, what happens when an agent goes down, and why this model is the reason Jenkins can scale to hundreds of builds a day.

Most beginners run Jenkins with everything on one machine — the master is also the only agent. That works fine for learning. But the moment your team grows, or your builds start taking too long, or you need to build on both Linux and Windows, you hit a wall. The master/agent model is the answer to that wall.

The Restaurant Kitchen — Again, But Deeper

In Lesson 1 we said Jenkins is the expeditor in a restaurant kitchen. Let's push that analogy further, because it explains everything about this model.

The head chef (master) stands at the pass. Tickets come in — orders from the dining room. The head chef reads each ticket, decides which cook handles it, and calls it out. Cook A is on the grill (Linux agent, handles backend builds). Cook B is on the fryer (Windows agent, handles .NET builds). Cook C is a temp who only comes in on busy nights (a cloud agent that spins up on demand).

The head chef never cooks. If the head chef is sick, no tickets get called — even if every cook is standing there ready. If Cook A goes down mid-service, the head chef routes that ticket to Cook B. The kitchen keeps running.

That's the master/agent model. The master is irreplaceable for coordination. The agents are interchangeable for execution.

Key Concept

An executor is a single build slot on an agent. If an agent has 4 executors, it can run 4 jobs at the same time. The master has its own executor count too — but best practice is to set that to zero so no builds ever run on the master itself.

How the Master Finds and Uses Agents

When a job is ready to run, the master doesn't just pick a random agent. It uses a matching system based on labels. Every agent has one or more labels — short tags that describe what that machine can do. A job declares which label it needs. The master finds an agent with that label that has a free executor.

Here's that matching system as a diagram:

Jobs Waiting

payment-service-build
needs label: linux
dotnet-api-build
needs label: windows
frontend-test
needs label: linux docker
Master
matches labels → assigns

Available Agents

agent-linux-01
labels: linux docker · 4 executors
agent-windows-01
labels: windows dotnet · 2 executors
agent-linux-02
labels: linux · 0 free executors (busy)

The master reads each job's label requirement and routes it to the right agent. frontend-test needs both linux and docker — only agent-linux-01 qualifies.

Two Ways an Agent Connects to the Master

There are two directions a connection can be established between master and agent. Which one you use depends on your network setup:

SSH — Master connects OUT to Agent

  • Master initiates the SSH connection
  • Agent machine must be reachable from master
  • Best for agents on the same network or VPC
  • Most common setup for on-premise teams

JNLP — Agent connects IN to Master

  • Agent initiates connection to master's URL
  • Works when agent is behind a firewall
  • Best for cloud agents, Docker, Kubernetes
  • Agent just needs outbound internet access

What Happens When an Agent Goes Offline

This is the question every new Jenkins admin gets asked eventually. An agent drops off — disk full, network blip, machine rebooted. What happens to the jobs?

If the agent goes offline mid-build, that build fails immediately. Jenkins marks it red. Any post-build steps like notifications still fire so the team knows. The build is not retried automatically by default — a human or a retry plugin needs to intervene.

If the agent goes offline before a build starts, the jobs that need that agent sit in the queue. They wait. If another agent with the right label is available, Jenkins routes there instead. If no matching agent is available, the job just waits — it shows as pending in the dashboard with a note saying which label it needs.

Watch Out

If you have only one agent with a specific label and it goes offline, every job that needs that label will pile up in the queue silently. No alarm fires by default. This is why production Jenkins setups always have at least two agents per label — so there's always a fallback.

What the Jenkins Dashboard Shows You

Here's what the Nodes page looks like inside Jenkins — the place where you manage all your agents. This is under Manage Jenkins → Manage Nodes and Clouds:

Jenkins — Manage Nodes and Clouds
S Name Labels Executors Free
master — 0 0
agent-linux-01 linux docker 4 3
agent-windows-01 windows dotnet 2 2
agent-linux-02 linux 4 offline

Master has 0 executors — correct. agent-linux-02 is offline — someone needs to investigate.

Notice the master has 0 executors. That's intentional and correct. Also notice agent-linux-02 is red and offline — any job needing the linux label will now queue up waiting for either that agent to come back or agent-linux-01 to free up an executor.

The scenario:

You're a DevOps engineer at a fintech startup. Builds have been running slow all morning. Your team lead suspects one of the Linux agents is overloaded. You need to check how many executors each agent has and how many are currently free — right now, without opening a browser.

Tools used in this command:

  • java — the runtime that Jenkins and the CLI tool are built on. Must be installed on whatever machine you're running this from.
  • jenkins-cli.jar — Jenkins' own command-line tool. Download it once from your server at /jnlpJars/jenkins-cli.jar.
  • get-node — fetches the configuration XML for a named agent. Passing a specific name (like agent-linux-01) returns just that agent's details.
# Fetch the full configuration of a specific agent by name
# Replace 'agent-linux-01' with the actual name of your agent
java -jar jenkins-cli.jar \
  -s http://jenkins-master-01:8080 \
  -auth admin:your-api-token \
  get-node agent-linux-01

Where to practice this: You need a live Jenkins server with at least one agent configured. The fastest free option is Katacoda Jenkins Playground — it spins up a full Jenkins environment in your browser in under a minute. For a more hands-on setup, follow the official Jenkins Docker install guide to run a master and agent locally on your own machine using Docker.

<slave>
  <name>agent-linux-01</name>
  <description>Primary Linux build agent — 4 CPU, 16GB RAM</description>
  <numExecutors>4</numExecutors>
  <mode>NORMAL</mode>
  <label>linux docker</label>
  <launcher class="hudson.plugins.sshslaves.SSHLauncher">
    <host>10.0.1.45</host>
    <port>22</port>
    <credentialsId>agent-linux-01-ssh-key</credentialsId>
  </launcher>
  <retentionStrategy class="hudson.slaves.RetentionStrategy$Always"/>
  <offline>false</offline>
</slave>

What just happened?

  • <numExecutors>4</numExecutors> — this agent can handle 4 simultaneous builds. If all 4 slots are busy, job number 5 queues up and waits. This is the number to tune when builds are backing up.
  • <mode>NORMAL</mode> — means this agent accepts any job. The alternative is EXCLUSIVE, which means the agent only runs jobs that specifically request it by name — useful for dedicated agents running sensitive deploys.
  • <label>linux docker</label> — two labels separated by a space. A job can request either linux OR docker and this agent will match. Labels are how jobs find the right machine without hard-coding a server name.
  • <credentialsId>agent-linux-01-ssh-key</credentialsId> — instead of storing the actual SSH private key in plain text here, Jenkins stores a reference to a credential ID. The real key lives in Jenkins' encrypted credential store. This is the secure way to handle secrets.
  • <offline>false</offline> — agent is up and reachable. If this were true, your next step would be to SSH directly into 10.0.1.45 and check whether the Jenkins agent process is still running.

Teacher's Note

Set the master's executor count to zero on day one. It takes 30 seconds and prevents an entire category of security and stability problems later.

Practice Questions

1. What is a single build slot on a Jenkins agent called?



2. What does a Jenkins job use to tell the master which type of agent it needs to run on?



3. What should the executor count on the Jenkins master be set to in a production setup?



Quiz

1. What happens to a job if no agent with the required label has a free executor?


2. Which agent mode setting restricts it to only running jobs that request it by name?


3. When would you use a JNLP connection instead of SSH for an agent?


Up Next · Lesson 5

Installation Overview

Three ways to install Jenkins — and which one to pick depending on where you're running it.

← Previous Course Index Next →