Jenkins Master and Agent Architecture

When Jenkins grows beyond a single machine running a few jobs, you need a distributed architecture. The master-agent model lets Jenkins coordinate work across many machines, running multiple builds simultaneously and using specialized environments for different jobs.

Think of this as a kitchen in a restaurant. The head chef (master) takes orders, assigns tasks, and tracks progress. The kitchen stations (agents) do the actual cooking — frying, baking, grilling. The head chef does not cook — they manage.

The Controller (Master)

The Jenkins controller (formerly called master) is the central server. It runs the Jenkins web interface, stores configuration, manages job schedules, and coordinates which agent runs each job. The controller does not run build steps itself in a well-configured production setup.

What the Controller Does

Jenkins Controller responsibilities:
  ✓ Hosts the Jenkins web UI
  ✓ Reads Jenkinsfiles and pipeline definitions
  ✓ Manages the build queue
  ✓ Assigns builds to agents
  ✓ Collects and stores build results and logs
  ✓ Manages credentials, plugins, and user accounts
  ✓ Tracks build history and artifacts

Jenkins Controller does NOT do:
  ✗ Run shell commands (in production setup)
  ✗ Check out code
  ✗ Execute build tools (Maven, npm, Docker, etc.)

Agents

An agent (also called a node) is a machine connected to the controller that runs actual build jobs. Agents can run on physical servers, virtual machines, Docker containers, or cloud instances.

What an Agent Does

Agent responsibilities:
  ✓ Runs build steps (sh, bat, Maven, Docker, etc.)
  ✓ Checks out code from Git
  ✓ Runs tests
  ✓ Builds Docker images
  ✓ Deploys applications

Each agent has:
  - A label (e.g., "linux", "docker", "windows", "large-memory")
  - A number of executors (parallel build slots)
  - Its own workspace directory

Architecture Diagram

                   INTERNET / INTERNAL NETWORK
                              |
                              |
              +---------------+---------------+
              |         JENKINS CONTROLLER    |
              |         (port 8080)           |
              |  - Web UI                     |
              |  - Job scheduling             |
              |  - Build queue                |
              |  - Plugin management          |
              +-------+-------+-------+-------+
                      |       |       |
               JNLP/SSH  JNLP/SSH  JNLP/SSH
                      |       |       |
           +----------+ +-----+  +---+--------+
           | AGENT 1  | |AGENT2|  |  AGENT 3  |
           | linux    | |docker|  |  windows  |
           | 4 exec.  | |2 ex. |  |  2 exec.  |
           |Java/Maven| |Docker|  |  .NET/IIS |
           +----------+ +------+  +-----------+

  Job A → runs on Agent 1 (needs Linux + Maven)
  Job B → runs on Agent 2 (needs Docker)
  Job C → runs on Agent 3 (needs Windows)
  Job D → queued, waiting for Agent 1 (busy)

Agent Connection Methods

Agents connect to the controller using different protocols depending on the environment.

Adding a Permanent Agent via SSH

Step 1: Prepare the agent machine
  - Install Java (same version as controller)
  - Create a "jenkins" user on the agent machine
  - Add controller's SSH public key to ~/.ssh/authorized_keys on agent

Step 2: In Jenkins (Manage Jenkins → Nodes → New Node)
  - Node name: build-agent-01
  - Type: Permanent Agent
  - Number of executors: 4
  - Remote root directory: /var/lib/jenkins/agent
  - Labels: linux java maven
  - Usage: Use this node as much as possible
  - Launch method: Launch agents via SSH
    Host: 192.168.1.50
    Credentials: ssh-key-for-agents
    Host Key Verification: Known Hosts or Non-verifying (for testing)

Step 3: Click Save → Jenkins connects and starts the agent

Node Labels and Job Routing

Labels are tags you assign to agents. In your pipeline, you route jobs to the right agent by specifying a label. This ensures the right tools are available for each job.

Agents and their labels:
  build-agent-01:  labels = "linux java maven docker"
  build-agent-02:  labels = "linux nodejs npm docker"
  build-agent-03:  labels = "windows dotnet msbuild"
  build-agent-04:  labels = "linux large-memory"

Pipeline routing jobs to correct agent:

  pipeline {
      agent { label 'java maven' }   // Runs on build-agent-01
      ...
  }

  pipeline {
      agent { label 'nodejs' }       // Runs on build-agent-02
      ...
  }

  pipeline {
      agent { label 'windows' }      // Runs on build-agent-03
      ...
  }

Number of Executors

Each agent has a number of executors — the number of jobs it can run simultaneously. A machine with 4 executors runs 4 jobs at the same time.

Executor planning guide:

  Small agent (2 CPU, 4 GB RAM):
    2-3 executors (light build jobs)

  Medium agent (4 CPU, 8 GB RAM):
    3-4 executors (typical Java/Node builds)

  Large agent (8 CPU, 16 GB RAM):
    6-8 executors (multiple concurrent builds)
    or
    2-3 executors (heavy builds like Android or large Docker images)

Rule of thumb:
  Executors ≤ CPU cores × 1.5
  Never set more executors than the machine can handle.

Dynamic Agents with Kubernetes

Kubernetes agents are created on demand when a build starts and destroyed when it finishes. This removes the need to maintain permanent build machines.

Kubernetes agent flow:

  Job queued in Jenkins
          |
          v
  Kubernetes plugin creates a pod
  (pod = temporary agent)
          |
          v
  Pod starts, connects to Jenkins controller
          |
          v
  Build runs inside the pod
          |
          v
  Build finishes → Pod is deleted automatically

Benefits:
  - No idle build machines sitting unused
  - Each build gets a fresh environment
  - Scale up automatically during peak hours
  - Scale down to zero when idle (no cost)

Offline and Disconnected Agents

If an agent goes offline (machine shutdown, network issue), Jenkins moves jobs back to the queue. Jobs waiting for that specific agent remain queued until the agent reconnects. Jobs that can run on other agents continue normally.

Key Points

• The controller manages Jenkins — it does not run build steps in production setups.
• Agents are the machines that run actual build jobs; each has labels and a set number of executors.
• Use labels to route specific jobs to agents with the right tools installed.
• Connect agents via SSH (Linux), JNLP (any platform), Docker (containers), or Kubernetes (dynamic pods).
• Kubernetes agents create and destroy build pods on demand — the most scalable approach.