Docker agents for isolation in Jenkins - Commands & Configuration

Introduction

Sometimes, running multiple tasks on the same machine can cause conflicts. Docker agents help by creating separate spaces for each task, so they don't interfere with each other.

When you want to run Jenkins jobs in clean, isolated environments to avoid conflicts.

When you need to test your application on different operating systems or setups without changing your main server.

When you want to keep your Jenkins server clean and avoid installing many tools directly on it.

When you want to easily share the same environment setup across different Jenkins jobs.

When you want to speed up Jenkins job setup by using ready-to-go Docker images.

Config File - Jenkinsfile

Jenkinsfile

pipeline {
  agent {
    docker {
      image 'python:3.10-slim'
      args '-v /tmp:/tmp'
    }
  }
  stages {
    stage('Run Python Script') {
      steps {
        sh 'python --version'
        sh 'echo Hello from Docker agent'
      }
    }
  }
}

This Jenkinsfile defines a pipeline that runs inside a Docker container.

agent docker: tells Jenkins to use a Docker container as the workspace.

image: specifies the Docker image to use, here a lightweight Python 3.10 image.

args: passes extra options to Docker, here mounting the host's /tmp directory inside the container.

The stages section runs commands inside this isolated Docker environment.

Commands

This command downloads the Python 3.10 slim Docker image to your Jenkins server so it can use it for Docker agents.

Terminal

docker pull python:3.10-slim

Expected Output

3.10-slim: Pulling from library/python

Digest: sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Status: Downloaded newer image for python:3.10-slim

docker.io/library/python:3.10-slim

This command starts a Jenkins agent inside the Python Docker container to run jobs isolated from the main server.

Terminal

jenkins-agent --docker-image python:3.10-slim

Expected Output

Starting Jenkins agent with Docker image python:3.10-slim

Agent connected and ready to receive jobs.

This command triggers the Jenkins pipeline that uses the Docker agent to run inside the container.

Terminal

jenkins-cli build my-pipeline

Expected Output

[Pipeline] Start of Pipeline

[Pipeline] node

Running on docker agent inside container

[Pipeline] sh

+ python --version

Python 3.10.9

[Pipeline] sh

+ echo Hello from Docker agent

Hello from Docker agent

[Pipeline] End of Pipeline

Finished: SUCCESS

This command shows running Docker containers, including the Jenkins Docker agent container if it is still running.

Terminal

docker ps

Expected Output

CONTAINER ID   IMAGE             COMMAND                  CREATED          STATUS          PORTS     NAMES

abc123def456   python:3.10-slim  "python3"                10 seconds ago   Up 9 seconds              jenkins-agent-xyz

Key Concept

If you remember nothing else from this pattern, remember: Docker agents let Jenkins run jobs in clean, separate spaces to avoid conflicts and keep the main server clean.

Common Mistakes

Not pulling the Docker image before running the Jenkins job.

Jenkins cannot start the Docker agent if the image is not available locally, causing job failure.

Always pull the required Docker image on the Jenkins server before running jobs that use it.

Forgetting to specify the Docker agent in the Jenkinsfile.

Without specifying the Docker agent, Jenkins runs jobs on the main server, losing isolation benefits.

Define the Docker agent in the Jenkinsfile under the agent section to ensure jobs run inside containers.

Not passing necessary Docker arguments like volume mounts.

Jobs may fail if they need access to files or directories not available inside the container.

Use the args option to pass Docker flags like volume mounts to share files between host and container.

Summary

Use Docker agents in Jenkins to run jobs inside isolated containers.

Pull the required Docker image before running jobs to ensure availability.

Define the Docker agent and image in the Jenkinsfile for clean, repeatable environments.