Choosing Between Native, Docker, and Kubernetes Agents in Jenkins

Decision: Choosing Jenkins Agent Execution Strategy

When configuring a Jenkins pipeline you must decide how the agent that runs your stages will be provisioned. The choice influences reproducibility, isolation, performance, and operational overhead. Constraints often include the existing compute infrastructure, security policies that limit privileged access, the need for deterministic build environments, and latency or resource‑usage targets.

Supported Options

Option	How it works	Typical use‑case
Native agent (VM or bare‑metal)	Jenkins launches a long‑running Java process directly on the host OS. The agent inherits the host’s filesystem, packages, and environment variables.	Environments where the host is already hardened, builds tolerate some drift, and low‑latency execution is critical.
Docker agent	For each stage (or the whole pipeline) Jenkins starts a container from a supplied Docker image. The container provides an isolated filesystem and can be discarded after the step.	Projects that require reproducible toolchains, want to avoid installing build dependencies on the host, or need to test against multiple images.
Kubernetes agent (optional)	Jenkins provisions a pod in a Kubernetes cluster; the pod runs the agent process and each stage can run in additional containers.	Organizations already operating a Kubernetes fleet that desire dynamic scaling, pod‑level security policies, and tight integration with cloud‑native workflows.

Trade‑offs

• Native agents – minimal startup overhead and full access to host hardware (e.g., GPUs, specialized drivers). Drawbacks include environment drift between builds, harder isolation (a misbehaving step can affect the host), and the need to manage host‑level patches.
• Docker agents – each run starts from a known image, giving deterministic builds and easy versioning. The trade‑off is the requirement for the Jenkins agent (or a Docker‑in‑DinD sidecar) to have access to the Docker daemon, which can raise privilege‑escalation concerns, and a modest latency penalty for container start‑up.
• Kubernetes agents – add horizontal scaling and native pod security contexts, but introduce cluster operational complexity, additional networking setup, and a reliance on the Kubernetes API server for agent provisioning.

Concrete Implementation: Docker Agent for a Maven Build

The following Jenkinsfile demonstrates using the docker agent directive to run a Maven verification step inside the official maven:3.9-eclipse-temurin-17 image. No host‑specific tools are assumed to be present.

pipeline {
    agent {
        docker {
            image 'maven:3.9-eclipse-temurin-17'
            // Optional: reuse the same container for multiple stages
            reuseNode true
        }
    }
    stages {
        stage('Build') {
            steps {
                sh 'mvn -B verify'
            }
        }
    }
    post {
        success {
            echo 'Build completed successfully'
        }
        failure {
            echo 'Build failed – check logs for details'
        }
    }
}

Validation Steps

1. After triggering the pipeline, open the build’s console output and confirm that the line [INFO] BUILD SUCCESS appears.
2. Check the Jenkins system log (e.g., $JENKINS_HOME/logs/jenkins.log) for a message similar to Agent launched successfully and verify that the agent label matches the Docker agent (often shown as docker‑xxxxxx).
3. Inspect the workspace directory on the Jenkins agent (visible via ws variable or the “Workspace” link) to ensure no unexpected host packages were installed. For example, verify that a host‑only tool such as /usr/local/bin/host-only-tool is absent.
4. While the build is running, execute docker ps on the Jenkins agent host (requires sufficient permissions). You should see a container ID based on the maven:3.9-eclipse-temurin-17 image; after the stage finishes the container should disappear.

Limitations and Practical Checks

• Docker agents require the Jenkins agent process to be able to talk to the Docker daemon. If the agent runs inside a Docker container itself, you must enable Docker‑in‑DinD or mount the Docker socket, which can expose privileged capabilities.
• Because each step launches a fresh container, any state you want to preserve between stages must be explicitly stored in the workspace or a shared volume.
• To verify that no host tools leaked into the build, you can add a diagnostic step such as sh 'which gcc || echo \"gcc not found\"' and confirm the output indicates the tool is absent.