Jenkins Controller vs Agent Architecture

Jenkins Controller manages the CI/CD system (job scheduling, pipeline orchestration, credentials, plugins, user access). Jenkins Agents execute the actual build work (build, test, scan, deploy) on separate machines. Controller assigns work; Agents run it. Scales by adding more agents.

Overview

Controller and agent

Jenkins uses a Controller-Agent (formerly Master-Slave) architecture to distribute work across machines. The controller assigns, the agent runs. Understanding this split is foundational to designing scalable Jenkins deployments.

What each side does

Stores — All configuration, job definitions and build history — A workspace directory where source code is checked out
Does — Schedules jobs and assigns them to agents by label — Runs the build steps: compile, test, static analysis, Docker build, deploy
Also — Manages credentials, plugins and user access (RBAC); hosts the web UI and REST API; runs the Pipeline DSL logic (Groovy in Jenkinsfiles) — Carries labels for its capabilities (linux, docker, gpu, nodejs)
Form — One server — A separate JVM process, Docker container or Kubernetes pod
Lifetime — Always on — Permanent (always-on VM) or ephemeral (a pod or container per build)

> [!IMPORTANT] Modern Jenkins does not run build executors on the controller: set its executors to 0 as a security best practice.

Connection methods

Inbound ("JNLP") — Agent opens an outbound connection to the controller on port 50000 — Works through firewalls
Inbound over WebSocket (since 2.217) — Agent tunnels the same connection over the ordinary HTTPS port — No second port to open
SSH — Controller opens an SSH connection to the agent — Simpler, but the controller needs network access to the agent

Scaling model

Add agents — More parallelism
Executors per agent — Parallel build slots on one agent
Kubernetes plugin — A new pod per build, scaling horizontally with cluster capacity

> [!WARNING] Agents scale, the controller does not: it is a single point of failure, so very large installations shard into more controllers per team.

Key interview answer

> [!TIP] "Controller manages the CI/CD system: scheduling, credentials, plugins, UI. Agents execute the actual build work. You scale Jenkins by adding agents, not by upgrading the Controller."

Key concepts

Controller (formerly Master): The central Jenkins server. Schedules jobs, manages config and credentials, serves the UI, runs pipeline orchestration logic. Should have 0 executors in production — all build work goes to agents.
Agent (formerly Slave): A machine or container that connects to the Controller and runs build work. Has executors (parallel build slots), a workspace, and labels. Can be permanent or ephemeral.
Executor: A slot on an agent that runs one build at a time. An agent with 2 executors can run 2 builds in parallel. Executors = parallelism. Total capacity = sum of executors across all agents.
Agent label: A string tag on an agent (e.g., "linux", "docker", "aws"). Jenkinsfile uses agent { label "docker" } to require a specific capability. Controller only assigns the build to agents with matching labels.
Kubernetes plugin (ephemeral agents): Jenkins plugin that spins up a Kubernetes pod as an agent for each build, then destroys it. Provides: clean build environment per job, infinite scale (pods), no idle resource cost. Defined with podTemplate in Jenkinsfile.
JNLP port (50000): The TCP port the Controller listens on for agent connections. Agents initiate outbound connections to this port. Must be accessible from agent network to Controller. Configurable in Jenkins global security settings.

When to use it

Understanding Jenkins architecture for interviews and system design
Designing a new Jenkins deployment: how many agents, what labels, Controller sizing
Debugging Jenkins build failures that may be agent-related (missing tool, wrong OS, no disk space)
Scaling Jenkins to handle more concurrent builds
Migrating from monolithic Jenkins to Kubernetes-based ephemeral agents

Interview questions

Explain Jenkins Controller-Agent architecture and why it matters for scalability.
How do you set up Jenkins with Kubernetes for ephemeral agents?