Skip to main content
In this lesson we explain the Jenkins architecture and how its components interact to deliver scalable CI/CD automation. Understanding these roles helps you design resilient pipelines, distribute workloads, and scale build capacity as your projects grow. Jenkins uses a distributed architecture to run pipelines across multiple machines. This model provides:
  • Scalability — run builds and tests in parallel on many worker machines.
  • Resilience — isolate failures to worker nodes and protect controller state.
  • Centralized control — one controller coordinates jobs, plugins, and configuration.

​
Jenkins Controller (the coordination hub)

The central component is the Jenkins Controller (historically called the “master”). The controller is responsible for:
  • Authentication and authorization (user management and access control).
  • Defining, scheduling, and monitoring jobs and pipelines.
  • Hosting the web UI, managing plugins, and handling global configuration.
  • Persisting metadata such as credentials, job definitions, and job history.
A Jenkins architecture diagram showing a Jenkins Controller Node containing Plugins, Jobs, Nodes, Credentials, and Configurations, labeled as "the mastermind" coordinating the CI/CD process. Below it are three colored tiles for Management Tasks, Job Management, and Providing Web Interface.
For small or experimentation setups, a single Jenkins instance can act both as the controller and the build executor. This is convenient for getting started but is not recommended for production workloads.

​
Deployment topologies: single-node vs. distributed

Separating the controller from worker nodes is the recommended production practice. Benefits include:
  • Protecting controller configuration and state from job-side effects.
  • Improving throughput by distributing build workloads.
  • More predictable scaling—add more worker nodes when demand increases.
A Jenkins architecture diagram showing a Jenkins Controller Node containing Plugins, Jobs, Nodes, Credentials, and Configurations. Below it are two deployment options: Basic Deployment (controller and worker are the same) and Advanced Deployment (separate controller and worker nodes) with brief benefits.
Use the basic (single-node) setup for demos, POCs, or very small projects. Use the distributed topology for team environments, CI pipelines that run resource-heavy tasks, or when compliance and isolation are required.

​
Nodes, agents, and executors

Nodes (also called agents; legacy docs may use “slaves”) are the worker machines that perform builds, tests, and deployments. They can be physical or virtual machines, VMs, containers, or pods.
  • Connection protocols: Nodes connect to the controller via SSH or JNLP (Java Network Launching Protocol). See SSH and JNLP for details.
  • Executors: Each node exposes a configurable number of executors — each executor is a slot that can run one build at a time. The number of executors determines concurrency on that node.
    • Assign more executors for parallel builds if the node has sufficient CPU, memory, and I/O.
    • Limit executors to avoid resource contention and unstable builds.
Best practice: For isolation, assign one executor per node for critical or heavy tasks. On powerful machines, starting with one executor per CPU core is common—measure resource usage and tune executors accordingly.
An “agent” refers to the runtime/connection method enabling a node to accept work from the controller. Common agent approaches:
  • SSH agents — controller connects over SSH and launches the agent process on the node.
  • JNLP agents — the node initiates a connection to the controller using JNLP.
  • Docker agents — builds execute inside containers using a specified Docker image, ensuring reproducible environments.
  • Kubernetes agents — Jenkins provisions ephemeral pods in a Kubernetes cluster to run jobs on-demand and scale dynamically.
Tools and build dependencies must be available on the node or inside the container used by the agent. Container-based agents (Docker/Kubernetes) are especially useful when jobs need specific tool versions or isolated environments.
A Jenkins architecture diagram showing a central Jenkins Controller Node (with Plugins, Jobs, Nodes, Credentials, Configurations) connecting to multiple Jenkins Worker Nodes. The workers include Linux and Windows nodes running agents (Docker, Kubernetes or standard agents) with executors, connected via SSH or JNLP.

​
Quick comparison table

ComponentRoleWhen to use
ControllerCoordinates jobs, stores config, hosts UIMandatory—central control plane
Node / AgentRuns build/test/deploy tasksUse when you need isolation, platform-specific tools, or scaling
ExecutorConcurrency slot on a nodeTune per-node based on CPU/memory and job resource needs
Docker agentContainerized, reproducible buildsWhen you need specific toolsets per job or ephemeral environments
Kubernetes agentEphemeral pods, autoscalingFor large-scale dynamic workloads and auto-provisioning builds

​
How Jenkins schedules and runs work

  • Define jobs and pipelines on the controller using the web UI, CLI, or REST API.
  • The controller maintains the inventory of connected nodes and their free executors.
  • When a job is triggered, the controller selects an appropriate node and allocates an executor.
  • The agent on that node runs the build using available tools or inside a container, producing logs and artifacts.
  • On completion, the node returns build status, artifacts, and logs to the controller for display, storage, and downstream processing.
This distributed model enables Jenkins to handle more concurrent builds and complex pipelines while retaining centralized visibility and management.
Do not run resource-intensive builds directly on the controller in production. Keep the controller focused on coordination, and run builds on dedicated worker nodes or containerized agents to avoid impacting Jenkins availability.

​
References and further reading

This architecture—controller plus distributed agents—gives you flexibility to scale CI/CD pipelines, adopt container-based reproducibility, and maintain centralized administration of your Jenkins environment.

Watch Video