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.