Opscraft
Jenkins · Lesson 1 of 11 · 4 min read

Architecture: controller, agents, executors

Jenkins is the long-running open-source automation server, written in Java and extended through roughly 2,000 plugins. Many Indian enterprises and product companies still run large Jenkins estates, often alongside GitHub Actions or GitLab CI. Writing pipelines is the everyday part; a Senior DevOps interview focuses on running Jenkins itself as reliable, secure infrastructure — controller and agent architecture, scaling with ephemeral agents, configuration as code, credentials, upgrades, and how Jenkins fits a modern CI/CD and GitOps design.

The components

  • Controller (formerly "master") — a Java web application. It serves the UI and REST API (port 8080 by default), stores configuration, job definitions and build history in JENKINS_HOME, holds the build queue, schedules builds onto executors, and runs the Pipeline engine (the Groovy CPS interpreter for every running pipeline).
  • Agent (formerly "slave") — a machine, VM, container or pod that runs build steps. It runs a small Java process (agent.jar, the "remoting" library) that connects to the controller.
  • Node — any machine able to run builds; the controller itself is the "built-in node".
  • Executor — a slot on a node that runs one build (or one node {} block) at a time. A node with 4 executors runs 4 concurrent builds.
  • Label — a tag on agents (linux, docker, maven-jdk21, arm64) that jobs select with agent { label 'docker && linux' }.
  • Workspace — the directory on the agent where a build checks out code and works.
Enlarge diagramCONTROLLERweb UI + REST API :8080build queue + schedulerJENKINS_HOME: config, historyagent linux-1labels: linux docker · 4 executorsagent arm-1labels: linux arm64 · 2 executorspod per buildKubernetes plugin, label k8sexecutors on controller: 0
Figure 1. Jenkins architecture: one controller holds the configuration, queue and history; agents with labels and executors do the actual building.
Swipe sideways to see all of it, or tap to open it full screen.

How a build actually runs

  1. A trigger (webhook, cron, manual, upstream job) puts the job in the queue.
  2. The controller waits for an executor on a node matching the label expression ("Waiting for next available executor on 'docker'").
  3. For a Pipeline, the controller interprets the Jenkinsfile. Steps like sh are sent over the remoting channel to the agent and executed there; logs stream back to the controller.
  4. Results, logs, test reports and archived artifacts are stored under JENKINS_HOME on the controller.
Enlarge diagramTriggerwebhook, cron, manualQueuewaits for a matching executorControllerinterprets the JenkinsfileAgentruns sh, git, mvn stepsLogs stream backover the remoting channelStoredresults and artifacts inJENKINS_HOME123456
Figure 2. How a build runs, from trigger to stored result.
Swipe sideways to see all of it, or tap to open it full screen.

Important consequence: Pipeline Groovy logic runs on the controller, even inside node {}/agent blocks; only steps like sh, bat, git, junit file reading execute on the agent. Heavy Groovy processing (parsing huge JSON in Groovy, big loops) therefore loads the controller.

Enlarge diagramOn the controllerOn the agentif / for / def variablesreadJSON, string handlingEvery Groovy line, even inside agent { }sh, bat, powershellgit checkout, mvn, docker buildWorkspace files
Figure 3. Where pipeline code runs. Groovy logic always runs on the controller; only steps like sh run on the agent. Keep heavy work in shell steps.
Swipe sideways to see all of it, or tap to open it full screen.

JENKINS_HOME layout

$JENKINS_HOME/
├── config.xml                  # global configuration
├── credentials.xml             # encrypted credentials
├── secrets/                    # master.key, hudson.util.Secret — decrypts credentials
├── plugins/                    # installed plugins (.jpi + exploded dirs)
├── jobs/<job>/config.xml       # job definitions
├── jobs/<job>/builds/<n>/      # build logs, results, test reports, archived artifacts
├── workspace/                  # workspaces for builds on the built-in node
├── nodes/                      # agent definitions
└── users/

Backing up JENKINS_HOME without the secrets/ directory makes the credentials undecryptable; leaking it with secrets/ leaks every credential.

Executors on the controller: set to zero

Builds running on the controller can read JENKINS_HOME — including secrets/ and other jobs' data — and they compete with the controller for CPU, memory and disk. Best practice (and a Jenkins security recommendation): 0 executors on the built-in node, all builds on agents.