Skip to main content

Working with Distributed Builds

1. Understanding Controller-Agent Architecture

Component Description Role
Controller The central Jenkins instance that manages jobs, schedules builds, and provides the web UI. Orchestrates and manages distributed builds
Agent Remote nodes that execute build tasks on behalf of the Controller. Executes jobs and reports results

Example: Agent Configuration

java -jar agent.jar -jnlpUrl http://jenkins.example.com/computer/agent1/slave-agent.jnlp -secret <secret>

Key Concepts

  • The Controller is responsible for job scheduling and UI.
  • Agents execute builds in isolated environments.
  • Agents communicate with the Controller via JNLP (Java Network Launch Protocol).

2. Adding Build Agents

Property Description Default Value Notes
Name Unique identifier for the agent None Required field
Remote Root Directory Directory on the agent where Jenkins will store files /home/jenkins Must be writable by Jenkins user
Launch Method How Jenkins connects to the agent JNLP Can be SSH or JNLP
Labels Tags used to select agents for jobs None Comma-separated list of labels

Example: Adding an Agent via UI

1. Go to Jenkins Dashboard
2. Click "Manage Jenkins"
3. Select "Manage Nodes"
4. Click "New Node"
5. Enter a name for the agent
6. Choose "Permanent Agent"
7. Click "OK"
8. Configure the agent properties (remote root directory, launch method)
9. Save configuration
Note: Ensure the agent machine has Java installed and accessible in PATH.
Warning: Make sure the firewall allows communication on the required ports (default JNLP port is 50000).

3. Configuring Agent Launch Methods

Method Description Configuration Notes
JNLP Java Web Start protocol for agent connection java -jar agent.jar Default method; requires Jenkins master URL and secret
SSH Connect via SSH to a remote machine SSH key or password in agent configuration Requires SSH server running on agent machine
Launch via Slave Agent JAR Manually launch agent using JAR file Command line options for connection Useful for debugging or custom setups
Docker Launch agent inside a Docker container Docker image and runtime options Requires Docker daemon on Jenkins master
Kubernetes Launch agents as pods in a Kubernetes cluster Kubernetes configuration and pod templates Requires Kubernetes plugin and cluster access

Example: SSH Agent Configuration

ssh -i /path/to/private/key jenkins@agent-host "java -jar agent.jar"
Note: Ensure the Jenkins master can reach the agent via the specified launch method.
Warning: SSH keys must be properly configured to avoid authentication failures.

4. Using Agent Labels

Label Description Usage
agent.label Assigns a label to an agent for job execution agent { label 'linux-agent' }
agent.any Runs the job on any available agent agent any
agent.none Runs the job on the Jenkins master node agent none

Example: Label Assignment in Pipeline

pipeline {
    agent {
        label 'linux-agent'
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}
Note: Labels must be defined in the Jenkins agent configuration or via a plugin like Label Parameter.

5. Setting Agent Executors Count

Property Value Description
jenkins.agent.executors.count 1 Number of executors to run on the agent

Example: Configure executors in Jenkinsfile

pipeline {
    agent {
        label 'my-agent'
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
    post {
        always {
            cleanWs()
        }
    }
}
Note: The number of executors determines how many builds can run concurrently on an agent. Setting this to a higher value allows more parallel builds but may impact system performance.

6. Configuring Agent Environment

Property Value Description
agent.env {} Environment variables to set on the agent
agent.workspace /var/lib/jenkins/workspace Workspace directory on the agent
agent.javaHome /usr/lib/jvm/default-java Java home directory on the agent

Example: Setting Environment Variables

pipeline {
    agent {
        label 'linux-agent'
        env = [
            'JAVA_OPTS': '-Xmx1g',
            'NODE_ENV': 'production'
        ]
    }
    stages {
        stage('Build') {
            steps {
                sh 'echo $JAVA_OPTS'
            }
        }
    }
}
Note: Environment variables set here override system defaults but do not affect the Jenkins master environment.
Warning: Ensure agent-specific paths like workspace are accessible and have appropriate permissions.

7. Using Cloud Agents

Jenkins can leverage cloud agents to scale builds dynamically across distributed environments. These agents are typically provisioned on-demand from cloud providers or containerized environments.

Agent Type Description Provisioning Method Use Case
Jenkins Cloud Manages agents via cloud providers like AWS, Azure, GCP Automated provisioning via Jenkins Cloud plugin Dynamic scaling based on build load
Docker Agent Agents run inside Docker containers Container orchestration via Docker plugin Isolated builds with consistent environments
Kubernetes Agent Agents are provisioned as pods in a Kubernetes cluster Kubernetes plugin manages pod lifecycle Highly scalable, managed in Kubernetes

Example: Docker Agent Configuration

pipeline {
    agent {
        docker {
            image 'node:16-alpine'
            args '-v /tmp:/tmp'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'npm install'
            }
        }
    }
}

Example: Kubernetes Agent Configuration

pipeline {
    agent {
        kubernetes {
            cloud 'my-k8s-cloud'
            yamlFile 'kubernetes-pod.yaml'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'echo Building...'
            }
        }
    }
}
Note: Cloud agents allow for efficient resource utilization and can be configured to spin up and down based on build demand.

Key Benefits of Cloud Agents

  • Scalability: Dynamically scale builds based on demand
  • Isolation: Each build runs in a clean, isolated environment
  • Resource Efficiency: Use cloud resources only when needed
  • Flexibility: Support for various cloud providers and container runtimes

8. Using Kubernetes Plugin for Agents

The Jenkins Kubernetes Plugin allows you to dynamically provision and use Kubernetes agents for running builds. This enables scalable, on-demand agent provisioning without maintaining a permanent pool of build nodes.

Configuration Description Example
Kubernetes Cloud Defines the connection to the Kubernetes cluster. kubernetes
Kubernetes URL URL of the Kubernetes API server. https://kubernetes.default.svc
Credentials Authentication credentials for Kubernetes access. service-account
Namespace Kubernetes namespace to use for agents. jenkins
Pod Templates Templates defining how to create agent pods. agent-pod.yaml

Example: Pod Template Configuration

apiVersion: v1
kind: Pod
metadata:
  name: jenkins-agent
spec:
  containers:
  - name: jnlp
    image: jenkins/inbound-agent:4.13-1
    args:
      - "${JENKINS_SECRET}"
      - "${JENKINS_AGENT_NAME}"
    resources:
      limits:
        cpu: "2"
        memory: "4Gi"
      requests:
        cpu: "500m"
        memory: "512Mi"

Example: Jenkinsfile Usage

pipeline {
  agent {
    kubernetes {
      label "jenkins-agent"
      cloud "kubernetes"
    }
  }
  stages {
    stage("Build") {
      steps {
        sh "echo Building..."
      }
    }
  }
}
Note: Ensure that the Jenkins service account has appropriate RBAC permissions to create and manage pods in the specified namespace.
Warning: Misconfigured pod templates can lead to resource exhaustion or build failures. Always test configurations in a non-production environment.

9. Using Docker Plugin for Agents

Property Value Description
docker.image jenkins/jnlp-slave Base Docker image for the agent
docker.registry https://index.docker.io/v1/ Docker registry URL to pull images from
docker.credentials docker-credentials-id Credentials ID for Docker registry authentication

Example: Docker Agent Configuration

pipeline {
    agent {
        docker {
            image 'jenkins/jnlp-slave:latest'
            registryCredentialsId 'docker-credentials-id'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'echo "Building..."'
            }
        }
    }
}
Note: Ensure the Docker plugin is installed and configured in Jenkins before using this feature.
Warning: Running agents inside Docker containers may introduce security risks if not properly configured.
Option Values Description
docker.pull true Whether to pull the image from registry
docker.volumes [/var/run/docker.sock:/var/run/docker.sock] Mounts to add to the container
docker.environment [JAVA_HOME: '/usr/lib/jvm/java-11-openjdk'] Environment variables to set inside the container

Key Features

  • Supports Docker image-based agents
  • Enables dynamic provisioning of build agents
  • Allows custom Docker registry configuration
  • Supports volume and environment variable mapping

10. Monitoring Agent Status

Property Description Values
agent.status Current status of the Jenkins agent online, offline, connecting
agent.uptime Time since the agent was last connected HH:mm:ss
agent.executors Number of executors currently running on the agent 0 to n

Example: Check Agent Status via CLI

curl -s http://jenkins-server/computer/agent-name/api/json | jq .status
Note: The agent status can be monitored via the Jenkins UI under Manage Jenkins > Manage Nodes.
Warning: If an agent is marked as offline, it may not be able to execute builds until it reconnects.

11. Managing Agent Offline Reasons

Reason Code Description Impact Resolution
AGENT_DISCONNECTED Agent lost connection to Jenkins master Builds cannot run on this agent Restart the agent or check network connectivity
AGENT_LAUNCH_FAILED Failed to launch the agent process Agent is unusable until fixed Check agent launch configuration and logs
AGENT_TIMEOUT Agent did not respond within timeout period Builds queued for this agent may fail Increase timeout or investigate agent performance
AGENT_SHUTTING_DOWN Agent is in the process of shutting down Builds will be rescheduled Wait for shutdown completion or force stop
AGENT_OFFLINE_MANUAL Agent manually marked offline by user Builds will not run on this agent Mark agent online or remove from configuration

Example: Check Agent Offline Reasons via CLI

curl -s "http://jenkins.example.com/computer/agent1" | grep -o "<span class='offline-reason'>[^<]*</span>"
Note: Agent offline reasons can be managed through the Jenkins UI under Manage Jenkins > Manage Nodes.

Was this article helpful?