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.

Practice

1. What is the main benefit of using Docker agents in Jenkins for running jobs?

easy

A. They provide isolated environments to avoid conflicts between builds.

B. They speed up the Jenkins UI loading time.

C. They allow Jenkins to run without any plugins installed.

D. They automatically backup Jenkins configuration files.

Solution

1. Step 1: Understand Docker agent purpose

   Docker agents run Jenkins jobs inside containers, isolating each build environment.

2. Step 2: Identify the benefit of isolation

   This isolation prevents conflicts and keeps builds clean and reproducible.

3. Final Answer:

   They provide isolated environments to avoid conflicts between builds. -> Option A

4. Quick Check:

   Docker agents = isolated environments [OK]

Hint: Docker agents isolate builds to avoid conflicts [OK]

Common Mistakes:

• Thinking Docker agents speed up Jenkins UI
• Believing Docker agents remove need for plugins
• Assuming Docker agents backup Jenkins configs

2. Which of the following is the correct syntax to specify a Docker agent with image python:3.12 in a Jenkins pipeline?

easy

A. agent { docker { image 'python:3.12' } }

B. agent { docker.image('python:3.12') }

C. agent { docker('python:3.12') }

D. agent { docker { image: 'python:3.12' } }

Solution

1. Step 1: Recall Jenkins pipeline Docker agent syntax

   The correct syntax uses agent { docker { image 'image_name' } } format.

2. Step 2: Match the syntax with options

   agent { docker { image 'python:3.12' } } matches the correct syntax exactly with single quotes and no colon.

3. Final Answer:

   agent { docker { image 'python:3.12' } } -> Option A

4. Quick Check:

   Correct Docker agent syntax = agent { docker { image 'python:3.12' } } [OK]

Hint: Use agent { docker { image 'name' } } syntax [OK]

Common Mistakes:

• Using dot notation instead of block syntax
• Adding colon inside image declaration
• Using parentheses incorrectly

3. Given this Jenkins pipeline snippet:

pipeline {
  agent {
    docker {
      image 'node:18'
      args '-p 3000:3000'
    }
  }
  stages {
    stage('Run') {
      steps {
        sh 'node -v'
      }
    }
  }
}

What will be the output of the sh 'node -v' command?

medium

A. No output, command skipped

B. Error: node command not found

C. v12.x.x (Node.js version 12 output)

D. v18.x.x (Node.js version 18 output)

Solution

1. Step 1: Identify Docker image used

   The pipeline uses the Docker image node:18, which includes Node.js version 18.

2. Step 2: Understand command execution inside container

   The sh 'node -v' runs inside the container, so it will output Node.js version 18.

3. Final Answer:

   v18.x.x (Node.js version 18 output) -> Option D

4. Quick Check:

   Docker image node:18 runs Node.js v18 [OK]

Hint: Command runs inside specified Docker image environment [OK]

Common Mistakes:

• Assuming host Node.js version runs instead
• Expecting error due to missing node
• Confusing image tag with different Node version

4. You wrote this Jenkins pipeline snippet to use a Docker agent:

pipeline {
  agent {
    docker {
      image 'ubuntu:latest'
      args '-v /var/run/docker.sock:/var/run/docker.sock'
    }
  }
  stages {
    stage('Test') {
      steps {
        sh 'docker ps'
      }
    }
  }
}

But the build fails with docker: command not found. What is the likely cause?

medium

A. The Jenkins agent cannot mount volumes.

B. The ubuntu:latest image does not have Docker installed.

C. The args option is incorrect syntax.

D. The docker ps command is invalid inside containers.

Solution

1. Step 1: Check the Docker image capabilities

   The ubuntu:latest image is a minimal OS image and does not include Docker by default.

2. Step 2: Understand why command fails

   Since Docker is not installed inside the container, docker ps command is not found, causing the error.

3. Final Answer:

   The ubuntu:latest image does not have Docker installed. -> Option B

4. Quick Check:

   Missing Docker in image = command not found error [OK]

Hint: Check if Docker is installed inside the container image [OK]

Common Mistakes:

• Blaming volume mount syntax
• Assuming docker commands always work in containers
• Thinking docker ps is invalid inside containers

5. You want to run a Jenkins job inside a Docker container with a custom environment variable MY_VAR=hello and mount the workspace directory to /app inside the container. Which Jenkins pipeline snippet correctly sets this up?

hard

A. agent { docker { image 'python:3.12' args '-e MY_VAR=hello -v /app:$WORKSPACE' } }

B. agent { docker { image 'python:3.12' args '-v $WORKSPACE:/app -e MY_VAR=hello' } }

C. agent { docker { image 'python:3.12' args '-e MY_VAR=hello -v $WORKSPACE:/app' } }

D. agent { docker { image 'python:3.12' args '-v /app -e MY_VAR=hello' } }

Solution

1. Step 1: Understand Docker args for environment and volume

   To set environment variables, use -e VAR=value. To mount volumes, use -v host_path:container_path.

2. Step 2: Match correct volume and env var syntax

   agent { docker { image 'python:3.12' args '-e MY_VAR=hello -v $WORKSPACE:/app' } } correctly uses -e MY_VAR=hello and mounts $WORKSPACE to /app inside container.

3. Final Answer:

   agent { docker { image 'python:3.12' args '-e MY_VAR=hello -v $WORKSPACE:/app' } } -> Option C

4. Quick Check:

   Env var and volume mount syntax = agent { docker { image 'python:3.12' args '-e MY_VAR=hello -v $WORKSPACE:/app' } } [OK]

Hint: Use '-e VAR=value' and '-v host:container' in args [OK]

Common Mistakes:

• Reversing volume mount paths
• Omitting environment variable flag
• Incorrect order or missing colon in volume