Jenkins Architecture Basics
Jenkins is a self-hosted automation server built around a controller/agent (historically 'master/slave') architecture that lets a single logical Jenkins installation distribute build work across many machines. Understanding this architecture is foundational because almost every operational Jenkins concern — scaling, security, plugin behavior, pipeline syntax — is shaped by the split between the controller process that orchestrates everything and the agents that actually execute build steps. Unlike hosted CI platforms where infrastructure is abstracted away, Jenkins puts infrastructure topology front and center, which is both its greatest flexibility and its steepest operational cost.
Cricket analogy: Like a domestic cricket board that owns and manages its own regional practice grounds directly, deciding pitch prep and staffing itself, rather than renting time at a neutral, fully-serviced venue — more control, but the board bears the full operational burden.
The controller
The Jenkins controller (the process started when you run java -jar jenkins.war or deploy the Jenkins Docker image) hosts the web UI, stores all job and pipeline configuration, manages the plugin ecosystem, schedules builds onto agents, and persists build history and artifacts. Critically, the controller is a single point of coordination: if it goes down, no new builds can be scheduled and the web UI is unavailable, even though agents that are mid-build may continue running independently for a period. Because the controller holds credentials, plugin code, and configuration state, it is also the highest-value security target in a Jenkins deployment and is generally kept off the public internet and behind authentication.
Cricket analogy: Like a team's head office that holds all the playing contracts, selection records, and match archives — if it shuts down, no new team announcements can be made even though a match already underway continues, which is why the head office is kept tightly secured.
Agents and executors
An agent (formerly called a 'slave') is a machine — physical, virtual, or a dynamically-provisioned container/cloud instance — that connects to the controller and offers one or more executors, where an executor is a slot capable of running exactly one build step sequence at a time. A single agent with four executors can run up to four builds (or build stages) concurrently. Agents connect to the controller over several possible channels: JNLP/inbound TCP, SSH (the controller connects out to the agent), or ephemeral cloud agents provisioned on demand by plugins like the Kubernetes plugin, which spin up a pod as an agent for the duration of a single build and then tear it down. The controller itself can also run builds directly on its own built-in node, but doing so is discouraged in production because it competes for resources with the controller's coordination duties and increases the security blast radius.
Cricket analogy: Like a net-bowling facility with four bowling lanes (executors), where each lane can only have one bowler working through a spell at a time, so four lanes let four bowlers train simultaneously — some lanes are permanent nets, others pop-up nets assembled for one camp and dismantled after (ephemeral cloud agents).
// Jenkinsfile snippet showing agent/label targeting in a declarative pipeline
pipeline {
agent none
stages {
stage('Build') {
agent { label 'linux && docker' }
steps {
sh 'make build'
}
}
stage('Test on Windows') {
agent { label 'windows' }
steps {
bat 'run-tests.bat'
}
}
stage('Deploy') {
agent { label 'linux && docker' }
steps {
sh './deploy.sh'
}
}
}
}A helpful analogy: the Jenkins controller is an air traffic control tower — it never flies a plane itself, it decides which runway (agent) a flight (build) uses and when — while agents are the actual aircraft doing the work, and executors are the number of gates each aircraft can service simultaneously.
When a build is triggered, it enters the Jenkins build queue, and the controller's scheduler matches it to an available executor on an agent whose labels satisfy the job's requirements — for example a pipeline stage requesting agent { label 'linux && docker' } will only be scheduled onto an agent tagged with both labels. If no matching agent has a free executor, the item waits in queue; this is why capacity planning (enough agents, enough executors per agent, autoscaling cloud agents) directly determines pipeline wait times, independent of how fast the actual build steps run.
Cricket analogy: Like a net-session waiting list where a coach only assigns a young fast bowler to a lane with both a proper run-up length and a bowling machine available — if none matches, he waits his turn, and how fast the queue moves depends entirely on how many suitable lanes the academy has built.
A frequent architecture mistake is running production builds directly on the controller's built-in node (label built-in or historically master). Besides the resource contention this causes, any build step running there has file-system-level access to the controller's home directory, including credentials store files, which turns a compromised build script into a controller compromise. Best practice is to disable executors on the built-in node entirely in any non-trivial deployment.
- Jenkins uses a controller/agent architecture: the controller orchestrates and stores config; agents execute build steps.
- An executor is a slot on an agent capable of running one build at a time; agents can offer multiple executors.
- Agents connect via inbound JNLP/TCP, controller-initiated SSH, or are provisioned dynamically by cloud plugins (e.g. Kubernetes).
- Labels let pipeline stages target specific agents by capability (OS, installed tools, hardware).
- Builds wait in a queue until an agent with matching labels and a free executor becomes available.
- Running builds on the controller's built-in node is a security and stability anti-pattern in production.
Practice what you learned
1. In Jenkins architecture, what is an executor?
2. Which of the following is a documented security concern with running builds on the controller's built-in node?
3. How does a declarative Jenkinsfile stage target a specific class of agent?
4. What happens to a triggered build if no agent currently has a free executor matching its required labels?
5. Which statement best describes cloud/dynamic agents provisioned by plugins like the Kubernetes plugin?
Was this page helpful?
You May Also Like
Jenkinsfile Fundamentals
Learn the core building blocks of a Jenkinsfile — agent, stages, steps, environment, parameters, and post — and how Pipeline as Code changed Jenkins pipeline management.
Declarative vs Scripted Pipelines
Compare Jenkins' two pipeline authoring styles — the structured, opinionated declarative syntax versus the fully programmable Groovy-based scripted syntax — and when to reach for each.
Jenkins Plugins and Agents
Explore how Jenkins' plugin ecosystem extends core functionality and how agents are provisioned, connected, and secured — including static, SSH, and dynamic cloud agents.
Least Privilege for CI/CD Service Accounts
CI/CD service accounts should hold only the exact permissions their pipeline needs, scoped narrowly and time-limited, so a compromised job can't cascade into a broader breach.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAnsible Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics