Jenkins - Distributed Builds

Jenkins - Distributed Builds (Agents)

Running all builds on the Jenkins controller (formerly master) can quickly become a bottleneck, especially with many jobs or resource-intensive tasks. Jenkins supports distributed builds, allowing you to offload build execution to multiple ‘agent’ machines (formerly slaves).

Why Use Agents?

• Scalability: Handle more concurrent builds than a single controller can manage.
• Performance: Distribute build load across multiple machines.
• Specialized Environments: Use agents with specific operating systems, tools (e.g., macOS for iOS builds, Windows for .NET builds), or hardware required for particular jobs.
• Isolation: Prevent builds from interfering with each other or the controller’s stability.
• Security: Run builds in restricted environments or networks.

Agent Architecture

An agent is a separate machine (physical, virtual, or container) running an agent program (agent.jar). It connects back to the Jenkins controller, which then orchestrates build execution. The controller and agent establish a communication channel (typically TCP/IP) to exchange commands and build logs.

Setting Up a Permanent Agent

These steps describe setting up a traditional, long-running agent machine.

Step 1: Go to Manage Jenkins → Nodes.

Step 2: Click ‘New Node’ (or ‘New Agent’ in newer versions).

Step 3: Enter an ‘Agent name’ (e.g., linux-build-agent). Select ‘Permanent Agent’. Click ‘Create’.

Step 4: Configure the agent details:

• Description: Optional description.
• Number of executors: How many concurrent builds this agent can run (e.g., based on CPU cores).
• Remote root directory: The directory on the agent machine where Jenkins will store workspaces and files (e.g., /var/jenkins_agent or C:\JenkinsAgent). Ensure the user running the agent process has permissions here.
• Labels: Crucial for targeting jobs. Assign one or more labels (space-separated, e.g., linux docker java11). Jobs can request agents with specific labels.
• Usage: ‘Use this node as much as possible’ (default) or ‘Only build jobs with label expressions matching this node’.
• Launch method: How the controller connects to and starts the agent process. Common methods:
• • Launch agents via SSH: (Recommended for Linux/macOS) Requires an SSH server on the agent and SSH credentials (username/password or private key) stored in Jenkins Credentials. Jenkins connects via SSH and starts the agent.
• • Launch agent via execution of command on the controller: You provide a script run on the controller to launch the agent (less common).
• • Launch agent via connection to the controller: (Formerly JNLP/Java Web Start) The agent initiates the connection to the controller. Requires port 50000 (or configured agent port) open on the controller. Less recommended now due to security and setup complexity.
• • Launch agents via Windows service: Installs and manages the agent as a service on Windows.
• Availability: Keep the agent online as much as possible, schedule availability, etc.

Step 5: Configure other options like Node Properties (Environment variables specific to this agent) as needed.

Step 6: Click ‘Save’.

Step 7: Follow the specific instructions based on your chosen launch method (e.g., run a command on the agent for SSH initial connection or JNLP launch).

Once configured and launched correctly, the agent will appear online in the ‘Nodes’ list.

Using Agents in Pipelines

In Jenkins Pipelines (Jenkinsfile), you specify which agent(s) a build or stage should run on using the agent directive:

pipeline {
    // Run the entire pipeline on any available agent with the 'linux' label
    agent { label 'linux' }
    stages {
        stage('Build') {
            steps {
                sh './build.sh'
            }
        }
        stage('Test on Windows') {
            // Run this specific stage on a Windows agent
            agent { label 'windows' }
            steps {
                bat 'mvn test'
            }
        }
    }
}

Dynamic Agents (Cloud, Docker, Kubernetes)

Instead of permanent agents, Jenkins can dynamically provision agents as needed, often using cloud provider plugins (AWS EC2, Azure VM Agents, Google Cloud) or container technologies:

• Docker Agents: Define agents using Docker images directly in your Pipeline. Jenkins can run builds inside containers, ensuring clean, reproducible environments. Requires Docker Pipeline plugin.
• Kubernetes Agents: Use the Kubernetes plugin to dynamically launch agent pods within a Kubernetes cluster for each build. Highly scalable and efficient.

Example Docker agent in Pipeline:

pipeline {
    agent {
        docker {
            image 'maven:3.8.5-openjdk-11'
            args '-v $HOME/.m2:/root/.m2' // Mount Maven cache
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean package'
            }
        }
    }
}

Distributed builds are fundamental to scaling Jenkins effectively. Choosing between permanent and dynamic agents depends on your workload patterns, infrastructure, and requirements for environment consistency.