Using Pipeline Agent Configurations

1. Using Any Agent

Property	Values	Description
agent	`any`	Allows the pipeline to run on any available agent. This is the default behavior if no agent is specified.

Example: Using Any Agent

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                echo 'Running on any available agent'
            }
        }
    }
}

2. Using None Agent

Property	Values	Description
agent	`none`	Specifies that the pipeline does not require a specific agent and can run on any available node.

Example: Using None Agent

pipeline {
    agent none
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: When using agent none, you must manually specify an agent for each stage that requires one.

3. Using Label-Based Agents

Property	Values	Description
agent.label	`web-server`	Label used to identify agents in the cluster that can run this job.
agent.linux	`true`	Restricts agent selection to Linux agents only.
agent.windows	`false`	Restricts agent selection to Windows agents only.
agent.docker	`true`	Restricts agent selection to Docker agents only.

Example: Label-Based Agent Configuration

pipeline {
    agent {
        label 'web-server'
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}

Note: The label must match exactly with the labels assigned to agents in Jenkins.

Warning: If no agent with the specified label is available, the job will wait in queue until one becomes available.

4. Using Docker Agents

Property	Description	Example
agent { docker { ... } }	Specifies that the build should run inside a Docker container	`agent { docker { image 'maven:3.8.1-jdk-11' args '-v /tmp:/tmp' } }`
image	The Docker image to use for the build environment	`'node:16-alpine'`
registryCredentials	Authentication credentials for private Docker registries	`registryCredentials: [credentialsId: 'docker-registry']`
args	Additional arguments to pass to the Docker run command	`'-v /var/run/docker.sock:/var/run/docker.sock'`
label	Label to use for selecting a specific Docker agent node	`'docker-agent'`

Example: Using Docker Agent with Custom Image

pipeline {
    agent {
        docker {
            image 'python:3.9-slim'
            args '-v /home/jenkins:/app'
        }
    }
    stages {
        stage('Run Tests') {
            steps {
                sh 'python -m pytest tests/'
            }
        }
    }
}

Note: When using Docker agents, ensure that the Docker image contains all necessary tools and dependencies required for your build process.

Warning: Avoid mounting sensitive volumes like /var/run/docker.sock unless strictly necessary, as it can pose security risks.

Key Points

Docker agents provide isolated and reproducible build environments
Images can be pulled from public or private registries
Custom arguments allow for advanced configuration (e.g., volume mounts)
Labels can be used to select specific nodes in a multi-agent setup

5. Using Dockerfile Agents

Using Dockerfile agents in Jenkins allows you to define a custom container environment for your pipeline steps using a Dockerfile. This approach provides flexibility in defining the runtime environment and dependencies.

Property	Description	Example
agent	Specifies the agent configuration to use for running the pipeline.	`agent { dockerfile true }`
dockerfile	Defines the path to the Dockerfile used for building the agent image.	`dockerfile 'path/to/Dockerfile'`
dir	Specifies the directory where the Dockerfile is located, relative to the workspace root.	`dir 'docker'`
label	Assigns a label to the agent for scheduling purposes.	`label 'docker-agent'`

Example: Using Dockerfile Agent

pipeline {
    agent {
        dockerfile {
            filename 'Dockerfile'
            dir 'docker'
            label 'docker-agent'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'echo "Building..."'
            }
        }
    }
}

Note: The Dockerfile must be present in the workspace and accessible by Jenkins. Ensure that the Docker image is built with appropriate permissions for running commands inside the container.

6. Using Kubernetes Pod Agents

Kubernetes Pod Agents allow Jenkins pipelines to run on Kubernetes clusters, leveraging the scalability and resource management capabilities of Kubernetes.

Property	Description	Default Value	Notes
agent	Specifies the agent to use for running the pipeline	`none`	Must be set to `kubernetes` for Pod Agents
agent.label	Label selector to identify the Kubernetes nodes where the pod can be scheduled	`null`	Can be used to restrict pod placement
agent.cloud	Name of the Kubernetes cloud configuration defined in Jenkins	`null`	Required for Pod Agent configuration
agent.yaml	YAML content defining the pod template	`null`	Allows custom pod configuration

Example: Basic Kubernetes Pod Agent Configuration

pipeline {
    agent {
        kubernetes {
            label 'jenkins-slave'
            cloud 'kubernetes'
        }
    }
    stages {
        stage('Run') {
            steps {
                sh 'echo Hello World'
            }
        }
    }
}

Example: Custom Pod Template with YAML

pipeline {
    agent {
        kubernetes {
            yaml 'apiVersion: v1
kind: Pod
metadata:
  name: jenkins-slave
spec:
  containers:
  - name: maven
    image: maven:3.8.1-jdk-11
    command:
    - cat
    tty: true
'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'mvn clean compile'
            }
        }
    }
}

Note: The kubernetes agent requires the Kubernetes plugin to be installed and configured in Jenkins.

Warning: Ensure that the Kubernetes cloud configuration matches the cluster setup to avoid scheduling issues.

7. Configuring Agent Workspace

Property	Description	Default Value	Notes
workspace	Specifies the workspace directory for the agent	`/var/lib/jenkins/workspace`	Can be overridden per job or pipeline
workspaceCleanup	Whether to clean up the workspace before each build	`false`	Set to `true` to ensure a clean environment
workspaceCleanupOnFailure	Clean workspace only if build fails	`false`	Useful for debugging failed builds

Example: Setting Workspace Path in Pipeline

pipeline {
    agent {
        label 'my-agent'
    }
    stages {
        stage('Build') {
            steps {
                sh 'echo "Building in custom workspace"'
            }
        }
    }
    post {
        always {
            cleanWs()
        }
    }
}

Note: The cleanWs() step ensures that the workspace is cleaned up after each build, which helps maintain a consistent environment.

8. Using Custom Agent Images

Property	Description	Example
agent.customWorkspace	Specifies a custom workspace directory for the agent.	`agent { customWorkspace '/custom/workspace/path' }`
agent.image	Specifies the Docker image to use for the agent.	`agent { image 'custom/jenkins-agent:latest' }`
agent.registryCredentials	Specifies credentials for private Docker registries.	`agent { image 'my-registry.com/custom/image' credentialsId 'docker-credentials' }`

Example: Using Custom Agent Image

pipeline {
    agent {
        docker {
            image 'custom/jenkins-agent:latest'
            registryCredentialsId 'my-registry-credentials'
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'echo "Building with custom image..."'
            }
        }
    }
}

Note: Ensure that the custom image has necessary tools and dependencies installed to support your pipeline steps.

Warning: Using a custom image may introduce compatibility issues if the image does not meet Jenkins agent requirements.

9. Reusing Agents Across Stages

Property	Values	Description
agent	`agent { label 'my-label' }`	Specifies the agent to be used for a stage or pipeline
agent	`agent { docker 'node:16'`	Uses a Docker image for the agent

Example: Reusing Docker Agent Across Stages

pipeline {
  agent none
  stages {
    stage('Build') {
      agent {
        docker 'node:16'
      }
      steps {
        sh 'npm install'
      }
    }
    stage('Test') {
      agent {
        docker 'node:16'
      }
      steps {
        sh 'npm test'
      }
    }
  }
}

Note: Reusing agents across stages can improve performance by avoiding repeated setup and teardown of the same environment.

10. Configuring Agent Resource Limits

Property	Values	Description
agent.resourceLimit	`memory`, `cpu`	Defines the resource type to limit
agent.resourceLimit.memory	`512Mi`, `1Gi`	Maximum memory allocation for the agent
agent.resourceLimit.cpu	`500m`, `1`	Maximum CPU allocation for the agent

Example: Setting Resource Limits in Jenkins Pipeline

pipeline {
    agent {
        kubernetes {
            label 'jenkins-agent'
            resourceLimit {
                memory '1Gi'
                cpu '1'
            }
        }
    }
    stages {
        stage('Build') {
            steps {
                echo 'Building...'
            }
        }
    }
}