Docker Pipeline, Containerized Build Steps, Docker Agents, Sidecars, Registries, and Image Workflows: Concepts, Architecture, and Mental Model

1. The problem: “runs in a container” is not a complete trust model

Chapter 18 established that a Jenkins build runs because a specific build obtains an eligible agent, that agent connects through Remoting, and an executor owns a workspace. Docker adds another execution layer without erasing any of those facts. A Dockerized step still runs on behalf of a Jenkins build, on a particular agent, against a particular Docker engine or builder.

The common mistake is to collapse all of this into “the build is isolated because it is in Docker.” Linux namespaces and cgroups isolate container processes according to runtime configuration, but a process that can fully control a privileged Docker daemon can often create new containers, host mounts, networks, and other resources. Treat Docker daemon access as a high-impact trust boundary.

2. Mental model: stage → trusted Docker agent → digest → container → registry evidence

Read the chain in order. Jenkins first identifies the source revision and Pipeline stage. The queue selects a trusted Docker-capable agent. That agent talks to a known Docker engine. A reviewed image tag is resolved to an exact digest, then Jenkins/Docker starts a container and mounts a workspace. Optional sidecars add temporary service/network state. The build may then create a new image and push it to a registry. The durable release identity is the registry repository plus digest, linked back to the exact Jenkins build and source SHA.

flowchart TD
  A[Pipeline stage + source SHA] --> B[Trusted Docker-capable agent]
  B --> C[Known Docker engine / builder]
  C --> D[Image tag resolved to digest]
  D --> E[Container + workspace mount]
  E --> F[Optional sidecar + network]
  F --> G[Build/test output]
  G --> H[Registry push / pull]
  H --> I[Immutable image digest]
  I --> J[Jenkins build + source evidence]

A green shell command proves only that command succeeded. It does not prove a registry push happened, that a tag still points to the same content later, or that an external deployment is healthy.

3. State inventory before change

4. Docker Pipeline is an integration layer, not Docker Engine

The Docker Pipeline plugin gives Pipeline Jenkins-native constructs such as Declarative Docker agents and Scripted docker.image(...).inside {}, withRun, docker.build, and withRegistry. It still depends on a suitable Docker-capable agent and daemon/builder. Plugin success does not change the host privilege of that daemon.

5. Workspace mounts are part of the execution model

Current Jenkins documentation states that a Dockerized stage is assigned to an agent and receives a mounted workspace. Declarative reuseNode true can keep the stage on the current node/current workspace; otherwise Jenkins may use a fresh workspace. Scripted Pipeline does not provide the same reuseNode true behavior.

This means deleting a container does not prove the Jenkins workspace was deleted. Conversely, files created only in a container filesystem may disappear when the container exits. Always know which path owns important evidence.

6. Tags are reviewable names; digests are immutable content identity

The chapter uses reviewed tags such as python:3.13-alpine3.24 and alpine:3.24.1. Before a reproducible run, pull the image on the actual agent architecture and record its repository digest:

docker pull python:3.13-alpine3.24
docker image inspect \
  --format '{{join .RepoDigests "\\n"}}' \
  python:3.13-alpine3.24

A digest proves content identity, not authorship or trustworthiness. Preserve the digest together with source SHA, producer build, and reviewed upstream tag. Later supply-chain chapters add signing/provenance.

7. Sidecars are temporary external-system state

A sidecar is another container used as a service while tests run. The service has a container ID, network identity, startup/readiness behavior, logs, and cleanup lifecycle. Docker Pipeline’s withRun can return the sidecar container ID, which should be captured as evidence. An aborted Pipeline must not leave an indefinite service/network behind.

8. Registry acceptance is distinct from image build success

A registry stores content under repository references. Jenkins may authenticate with a username/password credential, but the credential ID is not the image identity. The important retained output is the repository plus registry-reported digest linked to the Jenkins producer build.

The mandatory lab uses registry:3.1.1 on loopback with fake credentials. This gives real authentication semantics without requiring a commercial/cloud registry. It is deliberately not production registry guidance; real registries require TLS, authorization, retention, audit, and availability design.

9. Read-only inspection first

set -eu
printf 'node=%s\nworkspace=%s\n' "$NODE_NAME" "$WORKSPACE"
docker version
docker context show
docker info --format 'server={{.ServerVersion}} driver={{.Driver}} security={{json .SecurityOptions}}'
docker image ls --digests --format '{{.Repository}}:{{.Tag}} {{.Digest}} {{.ID}}'
docker ps --format '{{.ID}} {{.Image}} {{.Names}} {{.Networks}}'
docker network ls --format '{{.ID}} {{.Name}} {{.Driver}}'

These commands establish which daemon and resources the job sees. If the Docker context is unexpected, stop before creating or deleting anything.

10. Security rule: daemon-capable workers are trusted infrastructure

Docker documentation treats daemon access as security-sensitive. Schedule image builds only on a dedicated trusted pool. Untrusted fork/PR code must not inherit privileged Docker-daemon authority, production registry credentials, signing keys, or broad internal network access merely because Jenkins can trigger it.

Knowledge check

Answer before revealing the explanation.

Official references and version notes

• Jenkins LTS changelog — baseline Jenkins 2.568.3 LTS, tested with Java 21 and 25; labs use Java 21 for Jenkins components.
• Using Docker with Pipeline — Docker agents, workspace synchronization, multiple containers, sidecars, builds, remote servers, and custom registries.
• Docker Pipeline plugin — reviewed version 653.v2f2c08eff0ec, requires Jenkins 2.541.3, and is currently marked “up for adoption”.
• Docker Pipeline steps — current step reference; deprecated Docker fingerprint steps are not used as authenticity/provenance evidence.
• Docker Engine security, protect daemon access, and rootless mode.
• Docker Engine 29 release notes — current release family at the chapter timestamp; 29.8.1 was released 2026-09-15.
• Distribution Registry official image — local lab baseline registry:3.1.1.
• Python, Alpine, and httpd official images — reviewed lab tags python:3.13-alpine3.24, alpine:3.24.1, and httpd:2.4.68-alpine3.24; resolve actual architecture-specific digests before execution.