Controller and Agent Architecture
Jenkins uses a controller to coordinate work and agents to run it, allowing you to scale builds across many machines.
Jenkins follows a controller / agent architecture (formerly called master / slave).
The controller
The controller is the main Jenkins server. It stores configuration, schedules builds, serves the web UI, and decides which agent should run each job. In small setups the controller can also run builds itself.
The agents
An agent (also called a node) is a separate machine or container that actually executes the build steps. Agents connect to the controller and wait for work.
Why split them?
- Scale — run many builds at once across many agents.
- Isolation — keep the controller stable; risky build work runs elsewhere.
- Different environments — a Windows agent, a Linux agent, a macOS agent, all controlled from one place.
Example
# The controller assigns each build to an agent.
# In a pipeline you choose the agent with a label:
# pipeline {
# agent { label 'linux' } <-- run on an agent tagged 'linux'
# ...
# }When to use it
- A company runs Windows builds on a dedicated Windows agent while Linux tests run in parallel on separate Linux agents.
- A controller is kept on a small VM while beefy build agents handle compilation to keep the controller load low.
- A team labels agents as 'docker' and 'android' so each pipeline targets only agents with the required tools installed.
More examples
Route pipeline to labeled agent
Assigns the entire pipeline to an agent that has both the 'linux' and 'docker' labels.
pipeline {
agent { label 'linux && docker' }
stages {
stage('Build') {
steps { sh 'docker build -t myapp .' }
}
}
}Add SSH agent in Manage Jenkins
Shows the key configuration values when adding an SSH-connected build agent to the controller.
# Manage Jenkins > Nodes > New Node
# Name: build-agent-1
# Host: 192.168.1.50
# Credentials: SSH private key (jenkins user)
# Launch method: Launch agents via SSHPer-stage agent assignment
Uses agent none at the top level and assigns different labeled agents to individual stages.
pipeline {
agent none
stages {
stage('Build') {
agent { label 'maven' }
steps { sh 'mvn package' }
}
stage('Deploy') {
agent { label 'kubernetes' }
steps { sh 'helm upgrade myapp ./chart' }
}
}
}
Discussion