Topic 3.1
Jenkins Architecture: Controller & Agents
In one line
A Jenkins CONTROLLER is the brain coordinating everything; AGENTS are the actual machines that run jobs — directly mirroring Kubernetes' own control-plane-versus-worker-node split, just for a CI system instead of a container orchestrator.
Key ideas
- 01
The JENKINS CONTROLLER (historically called the 'master,' a term still seen in older documentation) is the central server running Jenkins itself — it hosts the web UI, stores all job configurations and build history, and DISPATCHES work to agents, but critically, in any real production setup, does NOT run your actual build/test jobs directly itself.
- 02
An AGENT (historically 'slave,' also a term you may still encounter) is a separate machine that CONNECTS to the controller and actually EXECUTES jobs — this is directly analogous to Kubernetes' own control-plane-versus-worker-node split (that course's Phase 0.2): the controller makes decisions and coordinates, agents do the actual work.
- 03
Keeping the controller from running jobs directly is a genuinely important operational practice, not just a nice-to-have — a job that consumes excessive resources or hangs indefinitely on the CONTROLLER itself could destabilize the entire Jenkins system for every single team relying on it; isolating actual job execution to separate agents contains that risk to just the one affected agent.
- 04
Agents can be STATIC (long-running, always-connected machines) or DYNAMIC (provisioned on-demand, often as Docker containers or Kubernetes pods specifically for the duration of one job, then destroyed — directly echoing GitHub Actions' own hosted-runner model, just self-managed rather than provided by a platform).
- 05
A LABEL identifies which specific agent(s) a job can run on —
agent { label 'linux && docker' }in a Jenkinsfile requests an agent matching BOTH criteria, directly analogous to GitHub Actions' own custom labels for self-hosted runners (Phase 2.4) — the exact same underlying concept, different platform's specific syntax. - 06
Jenkins' EXECUTOR count on a given agent determines how many jobs that agent can run SIMULTANEOUSLY — an agent with 4 executors can run up to 4 jobs (or job stages) in parallel; genuinely important capacity planning, since an agent pool with too few total executors becomes a real bottleneck once enough jobs are queued waiting for a free executor to become available.
Code & diagrams
The same control-plane-versus-worker split as Kubernetes, applied to a CI system instead.
Requesting an agent by label, directly mirroring GitHub Actions' self-hosted runner labels.
pipeline {
agent { label 'linux && docker' } // must match BOTH labels
stages {
stage('Build') {
steps {
sh 'mvn clean package'
}
}
}
}Explain it without notes
Why is it a genuinely important operational practice to keep the Jenkins controller from running build/test jobs directly?
How does Jenkins' controller/agent split relate to Kubernetes' own control-plane/worker-node split from that course's Phase 0.2?
Practice
If you have access to a Jenkins instance, check its 'Manage Nodes' page and identify the controller versus any configured agents, along with each agent's executor count.
Write a Jenkinsfile snippet (even hypothetically) requesting an agent with two specific labels, and explain in one sentence what would happen if no currently-connected agent matched both.
Trade-offs
- ↔
Static, always-connected agents are simple to reason about and guarantee capacity is genuinely available immediately, but they sit idle (and cost money, if they're real provisioned infrastructure) between actual job runs — dynamic, on-demand agents (provisioned as containers or cloud instances only when a job needs them) are more cost-efficient at scale but add real startup latency to each job and genuine additional infrastructure complexity to provision and tear them down correctly.
Done when you can
I can explain the roles of a Jenkins controller versus an agent.
I understand why the controller shouldn't run build/test jobs directly.
I can use labels to target a job at a specific kind of agent.