Docker agent in Jenkinsfile - Step-by-Step Execution

Process Flow - Docker agent in Jenkinsfile

Start Jenkins Pipeline

↓

Define Docker Agent

↓

Jenkins pulls Docker image

↓

Run build steps inside Docker container

↓

Build steps execute commands

↓

Container stops after steps

↓

Pipeline ends

The Jenkins pipeline starts, defines a Docker agent, pulls the Docker image, runs build steps inside the container, then stops the container and ends.

Execution Sample

Jenkins

pipeline {
  agent {
    docker {
      image 'python:3.12'
    }
  }
  stages {
    stage('Test') {
      steps {
        sh 'python --version'
      }
    }
  }
}

This Jenkinsfile runs the 'Test' stage inside a Python 3.12 Docker container and prints the Python version.

Process Table

Step	Action	Evaluation	Result
1	Start pipeline	N/A	Pipeline begins execution
2	Define agent as Docker with image 'python:3.12'	N/A	Jenkins prepares to use Docker agent
3	Pull Docker image 'python:3.12'	Image not present locally	Image downloaded from Docker Hub
4	Start container from image	Container created	Container running
5	Execute step: sh 'python --version'	Run command inside container	Outputs 'Python 3.12.x'
6	Finish stage 'Test'	All steps done	Stage completed
7	Stop Docker container	Container stopped	Container removed
8	Pipeline ends	All stages complete	Pipeline finished successfully

💡 Pipeline ends after all stages complete and Docker container stops

Status Tracker

Variable	Start	After Step 3	After Step 4	After Step 7	Final
Docker Image	undefined	'python:3.12' pulled	Image ready	Container stopped	N/A
Container State	none	none	running	stopped	removed
Pipeline State	not started	started	running	running	finished

Key Moments - 3 Insights

Why does Jenkins pull the Docker image even if it might exist locally?

Jenkins checks if the image exists locally; if not, it pulls it. This is shown in step 3 where the image is downloaded only if missing.

What happens to the Docker container after the build steps finish?

As shown in step 7, the container stops and is removed to clean up resources after the pipeline stage completes.

How does Jenkins run commands inside the Docker container?

In step 5, Jenkins executes shell commands inside the running container, isolating the build environment.

Visual Quiz - 3 Questions

Look at the execution table, at which step does Jenkins start the Docker container?

A Step 4

B Step 3

C Step 5

D Step 7

💡 Hint

Check the 'Action' column for 'Start container from image' in the execution table.

According to the variable tracker, what is the container state after step 7?

A removed

B running

C stopped

D none

💡 Hint

Look at the 'Container State' row under 'After Step 7' in the variable tracker.

If the Docker image is already present locally, which step in the execution table would change?

A Step 4 would be skipped

B Step 3 would be skipped or faster

C Step 5 would not run

D Step 7 would be earlier

💡 Hint

Step 3 is about pulling the image; if present locally, pulling is skipped or very fast.

Concept Snapshot

Jenkins Docker agent syntax:
agent { docker { image 'image_name' } }

Jenkins pulls the image if missing,
runs build steps inside the container,
then stops and removes the container.
Use for isolated, consistent build environments.

Full Transcript

This visual execution shows how Jenkins uses a Docker agent in a pipeline. The pipeline starts, defines a Docker agent with a specific image, and Jenkins pulls the image if it is not already present locally. Then Jenkins starts a container from that image and runs the build steps inside it. After the steps complete, the container stops and is removed. The pipeline then finishes successfully. Variables like Docker image, container state, and pipeline state change step-by-step. Key moments clarify why Jenkins pulls images, how commands run inside containers, and container cleanup. Quiz questions test understanding of container start, container state after stopping, and image pulling behavior.

Practice

1. What is the main purpose of using a docker agent in a Jenkinsfile?

easy

A. To speed up the Jenkins UI loading time

B. To run the build inside a container for a consistent environment

C. To deploy the application automatically after build

D. To backup Jenkins configuration files

Solution

1. Step 1: Understand what a Docker agent does in Jenkins

   A Docker agent runs the build steps inside a Docker container, ensuring the environment is consistent and isolated.

2. Step 2: Compare options with this purpose

   Only To run the build inside a container for a consistent environment describes running builds inside containers for consistency. Other options describe unrelated tasks.

3. Final Answer:

   To run the build inside a container for a consistent environment -> Option B

4. Quick Check:

   Docker agent purpose = consistent build environment [OK]

Hint: Docker agent means build runs inside container [OK]

Common Mistakes:

• Confusing Docker agent with deployment step
• Thinking Docker agent speeds up UI
• Assuming Docker agent manages backups

2. Which of the following is the correct syntax to specify a Docker agent in a Jenkinsfile?

easy

A. agent { docker image 'node:14' }

B. agent docker image: 'node:14'

C. agent docker { 'node:14' }

D. agent { docker { image 'node:14' } }

Solution

1. Step 1: Recall Jenkinsfile Docker agent syntax

   The correct syntax uses a block: agent { docker { image 'node:14' } }.

2. Step 2: Check each option

   agent { docker { image 'node:14' } } matches the correct block syntax. Options A, B, and D have syntax errors or missing braces.

3. Final Answer:

   agent { docker { image 'node:14' } } -> Option D

4. Quick Check:

   Correct Docker agent syntax = agent { docker { image 'node:14' } } [OK]

Hint: Docker agent uses nested braces with image key [OK]

Common Mistakes:

• Omitting braces around docker block
• Using colon instead of braces
• Placing image outside docker block

3. Given this Jenkinsfile snippet:

pipeline {
  agent {
    docker {
      image 'python:3.12'
      args '-v /tmp:/tmp'
    }
  }
  stages {
    stage('Test') {
      steps {
        sh 'python --version'
      }
    }
  }
}

What will be the output of the sh 'python --version' command?

medium

A. Python 3.12.x

B. Python 2.7.x

C. Command not found error

D. Python 3.8.x

Solution

1. Step 1: Identify the Docker image used

   The image specified is 'python:3.12', which contains Python version 3.12.

2. Step 2: Understand the command inside the container

   The command python --version runs inside the container, so it will output the Python version installed in that image, which is 3.12.x.

3. Final Answer:

   Python 3.12.x -> Option A

4. Quick Check:

   Docker image version matches command output [OK]

Hint: Output matches Docker image Python version [OK]

Common Mistakes:

• Assuming host Python version is used
• Confusing image tag with Python version
• Expecting command not found error

4. You wrote this Jenkinsfile snippet:

pipeline {
  agent {
    docker {
      image 'ubuntu'
      args '-it'
    }
  }
  stages {
    stage('Build') {
      steps {
        sh 'echo Hello'
      }
    }
  }
}

But the build fails with error: docker: Error response from daemon: the input device is not a TTY. What is the best fix?

medium

A. Change image to ubuntu:latest

B. Add tty true to the docker agent block

C. Remove the -it argument from args

D. Replace sh with bat

Solution

1. Step 1: Understand the error message

   The error says the input device is not a TTY, caused by using -it (interactive + tty) in a non-interactive Jenkins build.

2. Step 2: Fix the Docker args

   Removing -it from args avoids requesting a TTY, fixing the error.

3. Final Answer:

   Remove the -it argument from args -> Option C

4. Quick Check:

   Remove interactive TTY args in Jenkins Docker agent [OK]

Hint: Avoid -it args in Jenkins Docker agents [OK]

Common Mistakes:

• Adding tty true without removing -it
• Changing image without fixing args
• Using Windows bat step on Linux agent

5. You want to run a Jenkins pipeline using a Docker agent with the image maven:3.8.6-jdk-17 and mount the host directory /var/maven-repo to /root/.m2/repository inside the container. Which Jenkinsfile snippet correctly sets this up?

hard

A. agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo:/root/.m2/repository' } }

B. agent { docker { image 'maven:3.8.6-jdk-17' args '-v /root/.m2/repository:/var/maven-repo' } }

C. agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo' } }

D. agent { docker { image 'maven:3.8.6-jdk-17' args '--mount source=/var/maven-repo,target=/root/.m2/repository' } }

Solution

1. Step 1: Understand Docker volume mount syntax

   The syntax to mount a host directory to a container path is -v host_path:container_path.

2. Step 2: Match the mount paths correctly

   The host directory /var/maven-repo should be mounted to /root/.m2/repository inside the container, so the args must be -v /var/maven-repo:/root/.m2/repository.

3. Step 3: Check options

   agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo:/root/.m2/repository' } } matches the correct syntax and paths. agent { docker { image 'maven:3.8.6-jdk-17' args '-v /root/.m2/repository:/var/maven-repo' } } reverses paths. agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo' } } misses container path. agent { docker { image 'maven:3.8.6-jdk-17' args '--mount source=/var/maven-repo,target=/root/.m2/repository' } } uses incorrect mount syntax for Docker CLI.

4. Final Answer:

   agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo:/root/.m2/repository' } } -> Option A

5. Quick Check:

   Correct volume mount syntax = agent { docker { image 'maven:3.8.6-jdk-17' args '-v /var/maven-repo:/root/.m2/repository' } } [OK]

Hint: Use -v host:container for volume mounts in Docker args [OK]

Common Mistakes:

• Reversing host and container paths
• Omitting container path in volume mount
• Using --mount instead of -v in args