Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 40 ยท Build, Test and Package

Docker Agents and Building Images

Run Jenkins stages inside Docker containers, build and push images from a pipeline, and understand the risks of the Docker socket and the safer alternatives.

Docker and Jenkins meet in two different ways, and it helps to keep them apart. First, you can use Docker to run your build: a stage executes inside a container that already has the right compiler, so your agents do not need every tool installed. Second, you can use Jenkins to build images: the pipeline produces a Docker image, tags it and pushes it to a registry.

This lesson covers both, plus the security trade-off that comes with giving a build access to Docker. Real Docker commands and Jenkinsfiles are shown as read-only code, because a web page cannot run a Docker daemon. The runnable examples are stand-ins that reproduce the tagging and layer-cache logic so you can see why those rules exist. If Docker itself is new to you, read Images and Dockerfiles first.

Two ways to use Docker

Docker as the agent The stage runs inside a container.
Docker as the product The pipeline builds and pushes an image.

Different goals, different risks.

1 / 2

Docker as the build agent

The Docker Pipeline plugin adds docker as an agent type. Jenkins starts a container from the image you name, mounts the job workspace into it, runs your steps inside, and removes the container afterwards.

GROOVY
pipeline {
  agent none
  stages {
    stage('Test') {
      agent {
        docker {
          image 'node:22-alpine'
          args  '-u node'
        }
      }
      steps {
        sh 'node --version'
        sh 'npm ci && npm test'
      }
    }
  }
}

The agent label that runs the container must have Docker installed and a user that may talk to the daemon. args passes extra flags to docker run. Only the workspace is shared with the host, so anything your steps write outside it disappears with the container.

The big benefit is reproducibility: the tool versions live in the Jenkinsfile (node:22-alpine), not on whichever machine happens to run the job. Pin the tag, or better a digest, so the toolchain does not change under you.

Several containers in one stage

docker.image('...').inside { ... } in a script step lets you start helper containers, for example a database for integration tests:

GROOVY
stage('Integration') {
  steps {
    script {
      docker.image('postgres:17').withRun('-e POSTGRES_PASSWORD=test') { db ->
        docker.image('node:22-alpine').inside("--link ${db.id}:db") {
          sh 'npm run test:integration'
        }
      }
    }
  }
}

withRun starts the database, passes you the container, and stops it when the block ends. (--link is a legacy option that still works on the default bridge network; on a modern setup you would create a dedicated network instead, as the networking lessons explain.)

The dockerfile agent

If your project already has a Dockerfile that describes its build environment, let Jenkins build it and run the stage inside the result:

GROOVY
agent {
  dockerfile {
    filename 'Dockerfile.ci'
    dir      'ci'
    additionalBuildArgs '--build-arg NODE_VERSION=22'
  }
}

This keeps the environment definition next to the code, so a change to the toolchain is reviewed like any other change. The cost is a build before every run; Docker's layer cache keeps that cheap when the Dockerfile has not changed.

Building and pushing an image

The second use is producing the image. The Docker Pipeline plugin wraps the CLI:

GROOVY
pipeline {
  agent { label 'docker' }
  environment {
    REGISTRY = 'registry.example.com/team'
    IMAGE    = 'shop-api'
    TAG      = "${env.BUILD_NUMBER}-${env.GIT_COMMIT.take(7)}"
  }
  stages {
    stage('Build image') {
      steps {
        script {
          app = docker.build("${REGISTRY}/${IMAGE}:${TAG}")
        }
      }
    }
    stage('Push') {
      steps {
        script {
          docker.withRegistry('https://registry.example.com', 'registry-creds') {
            app.push()
            app.push('latest')
          }
        }
      }
    }
  }
}

registry-creds is the ID of a username/password credential in Jenkins (see Credentials and Secrets). Many teams skip the plugin and use plain shell steps, which are easier to reproduce on a laptop:

GROOVY
sh 'docker build -t $REGISTRY/$IMAGE:$TAG .'
withCredentials([usernamePassword(credentialsId: 'registry-creds',
                                  usernameVariable: 'U', passwordVariable: 'P')]) {
  sh 'echo "$P" | docker login registry.example.com -u "$U" --password-stdin'
  sh 'docker push $REGISTRY/$IMAGE:$TAG'
}

Note the single quotes: the shell, not Groovy, expands $P, so the secret never lands in the Groovy string. Image tagging strategy explains why you should never rely on latest alone.

A good tag rule

A tag should answer "which build and which commit made this image?" A common recipe is <build number>-<short commit>, plus a moving tag such as latest only on the main branch. The stand-in below applies that rule so you can see the output for different branches. It is not the Docker plugin, just the naming logic.

JS Stand-in: computing image tags from build data

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Docker tags cannot contain slashes or spaces, which is why the branch name feature/Checkout Flow is cleaned up to feature-checkout-flow. The immutable tag (119-c04be99) is the one you deploy; the branch tag is only a convenience.

Why the build cache matters

Every Dockerfile instruction produces a layer, and Docker reuses a layer only if the instruction and everything before it are unchanged. On a fresh ephemeral agent there is no cache at all, so builds are slow unless you plan for it: keep a persistent agent, use --cache-from with a registry, or use BuildKit's registry cache export. The stand-in models the rule itself: a changed layer invalidates every layer after it.

JS Stand-in: which layers does a change rebuild?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Build 2 reuses everything up to the source copy, so the slow npm ci is skipped; build 3 changes the lock file, which invalidates every later layer. This is exactly why Dockerfiles copy the dependency manifest before the source (see layers and the build cache).

The Docker socket problem

To run docker build, the agent needs a daemon. The easy way is to mount the host's socket into the Jenkins container: -v /var/run/docker.sock:/var/run/docker.sock. It works, but whoever controls the pipeline then controls the host's Docker daemon. They can start a privileged container, mount the host's root filesystem and read every credential on the machine. A Jenkinsfile from a pull request is code run with that power.

Treat access to the Docker socket as root access to the host. Never give it to controllers or agents that build code from untrusted contributors.

Safer options, roughly in increasing effort:

  • Dedicated build agents that run only Docker builds, are rebuilt often and hold no other secrets. The controller itself runs no builds.
  • Rootless Docker or Podman on the agent, so a container escape lands in an unprivileged user.
  • Docker-in-Docker with a sidecar daemon (covered in Docker in Docker). It needs a privileged container, so it moves the risk rather than removing it.
  • Daemonless builders such as Kaniko or BuildKit running without root. They build an image from a Dockerfile and push it without any Docker daemon, which is why they are popular in Kubernetes.

Docker's newer builder, Buildx with BuildKit, also gives you registry cache export and multi-platform builds (multi-platform images).

Kubernetes pod agents in one picture

When Jenkins runs on Kubernetes, the Kubernetes plugin starts each build as a short-lived pod. The pod can hold several containers, for example one with the language toolchain and one running Kaniko, and you pick which one a step runs in:

GROOVY
pipeline {
  agent {
    kubernetes {
      yaml '''
        apiVersion: v1
        kind: Pod
        spec:
          containers:
            - name: kaniko
              image: gcr.io/kaniko-project/executor:debug
              command: [sleep]
              args: [infinity]
      '''
    }
  }
  stages {
    stage('Image') {
      steps {
        container('kaniko') {
          sh '/kaniko/executor --context $WORKSPACE --destination registry.example.com/team/shop-api:$BUILD_NUMBER'
        }
      }
    }
  }
}

There is no Docker socket and nothing persists after the pod ends, so every build starts clean. Agents, Labels and Scaling returns to this idea, and the Kubernetes overview gives the background.

Practical tips

  • Pin base images and agent images by tag, ideally by digest.
  • Scan the image before you push it (image security) and fail the build on serious findings.
  • Clean up: old images fill agent disks. A scheduled docker system prune on build agents, or ephemeral agents, prevents "no space left on device".
  • Never bake secrets into an image with COPY or ARG; use BuildKit secrets instead.

What is real and what is the stand-in

The Jenkinsfile snippets and Docker commands above are real syntax but are not executed here. The two TryIt blocks are stand-ins that show the tag rule and the layer-cache rule in plain JavaScript; real Docker hashes layers differently, but the principle (a change invalidates everything after it) is the same.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the docker agent in a declarative pipeline do?

    Jenkins starts a container from the image, mounts the workspace, runs the steps inside it and removes it afterwards.
  2. 2. Why is mounting /var/run/docker.sock into a build container dangerous?

    The socket is the daemon's control channel. A build that can reach it can start privileged containers and read the host's files.
  3. 3. You change one source file but not package-lock.json. Which Dockerfile ordering keeps the slow dependency install cached?

    A layer is reused only if it and all earlier layers are unchanged. Copying the manifest first lets the install layer stay cached while the source layers rebuild.
  4. 4. Which tag best lets you trace a deployed image back to a build?

    latest moves with every push, and a branch name moves with the branch. The build number plus commit is unique and permanent.

Summary

  • The docker and dockerfile agents run a stage inside a container, so tool versions live in the repository.
  • To build and push images, use docker.build and docker.withRegistry, or plain sh steps with withCredentials.
  • Tag images with the build number and short commit; use moving tags only as conveniences.
  • Layer order drives cache hits: manifest first, source later.
  • The Docker socket is root on the host. Prefer dedicated agents, rootless setups or daemonless builders such as Kaniko, and ephemeral Kubernetes pod agents.

Next, learn how Jenkins stores and protects the registry passwords this lesson relied on in Credentials and Secrets.