Image Building

OCI Image Layout

Key Numbers

The Cache: Why Order Matters

# BAD — every source change rebuilds node_modules
FROM node:20
WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "server.js"]

# GOOD — manifest first, then install, then source
FROM node:20
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install --omit=dev
COPY . .
CMD ["node", "server.js"]

# Cache key for each layer is computed from:
#   - the instruction text
#   - the contents of files referenced by COPY/ADD (hashed)
#   - parent layer's digest
# Anything that changes the cache key invalidates this and all later layers.

Multi-Stage Builds

# Stage 1: heavy builder
FROM golang:1.22 AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /app

# Stage 2: tiny runtime
FROM gcr.io/distroless/static-debian12
COPY --from=builder /app /app
USER nonroot:nonroot
ENTRYPOINT ["/app"]

# Result: a ~12 MB image instead of ~1.5 GB.
# 'builder' is discarded — only its /app file ends up in the final image.

# Build a specific stage (useful for debugging)
$ docker build --target builder -t myapp-builder .

BuildKit: Mounts, Secrets, Cache

# syntax=docker/dockerfile:1.6
FROM golang:1.22

# Cache the Go module download dir between builds
RUN --mount=type=cache,target=/root/.cache/go-build \
    --mount=type=cache,target=/go/pkg/mod \
    go build -o /app .

# Inject a build-time secret without it ending up in any layer
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) npm install --registry=...

# SSH forwarding for private repos
RUN --mount=type=ssh git clone [email protected]:org/private-repo.git

# Build with secrets and SSH
$ docker build --secret id=npm_token,src=$HOME/.npmrc \
              --ssh default \
              -t myapp .

# Inspect cache usage
$ docker buildx du --verbose

buildx: Multi-Architecture Builds

# Create a builder that supports multiple platforms
$ docker buildx create --name multi --driver docker-container --use
$ docker buildx inspect --bootstrap

# Build for both amd64 and arm64 in one command
$ docker buildx build \
    --platform linux/amd64,linux/arm64 \
    -t myorg/app:v1.0 \
    --push .

# Under the hood:
# - amd64 builds natively
# - arm64 builds via QEMU emulation (slow) or remote arm builder (fast)
# - Both get tagged into a multi-arch manifest in the registry

# Verify what was pushed
$ docker buildx imagetools inspect myorg/app:v1.0
Name:      docker.io/myorg/app:v1.0
MediaType: application/vnd.oci.image.index.v1+json
Manifests:
  Name:      docker.io/myorg/app:v1.0@sha256:...
  Platform:  linux/amd64
  Name:      docker.io/myorg/app:v1.0@sha256:...
  Platform:  linux/arm64

Distroless and scratch

# scratch — empty base. Only works for static binaries.
FROM scratch
COPY app /app
ENTRYPOINT ["/app"]
# Final image: ~5 MB (just the binary)

# distroless — minimal but with /etc/passwd, /etc/ssl/certs, tzdata
FROM gcr.io/distroless/base-debian12
COPY app /app
USER nonroot:nonroot
ENTRYPOINT ["/app"]
# Final image: ~25 MB (binary + minimal libs + CA certs)

# Variants
gcr.io/distroless/static-debian12   # Go, Rust static
gcr.io/distroless/base-debian12     # glibc-linked binaries
gcr.io/distroless/cc-debian12       # C/C++ runtime
gcr.io/distroless/python3-debian12  # Python
gcr.io/distroless/java21-debian12   # JDK 21

# Debugging without a shell — use a debug image variant or k8s ephemeral container
$ docker run -it --entrypoint=sh gcr.io/distroless/...:debug

Signing with cosign

# Generate a key pair (or use keyless OIDC)
$ cosign generate-key-pair

# Sign an image
$ cosign sign --key cosign.key myorg/app:v1.0
$ cosign sign myorg/app:v1.0       # keyless, prompts for OIDC provider

# Verify
$ cosign verify --key cosign.pub myorg/app:v1.0
Verification for myorg/app:v1.0 --
The cosign claims were validated
The signatures were verified against the specified public key

# Kubernetes admission policy (sigstore policy-controller)
apiVersion: policy.sigstore.dev/v1beta1
kind: ClusterImagePolicy
metadata:
  name: require-cosign
spec:
  images:
    - glob: "myorg/*"
  authorities:
    - key:
        data: |
          -----BEGIN PUBLIC KEY-----
          ...

Vulnerability Scanning

# Trivy — open source, scans OS packages and language deps
$ trivy image myorg/app:v1.0
myorg/app:v1.0 (alpine 3.19)
==============================
Total: 3 (HIGH: 2, CRITICAL: 1)

┌──────────┬───────────────┬──────────┬────────┬─────────┐
│ Library  │ Vulnerability │ Severity │ Status │ Fixed   │
├──────────┼───────────────┼──────────┼────────┼─────────┤
│ openssl  │ CVE-2024-...  │ CRITICAL │ fixed  │ 3.1.5   │
└──────────┴───────────────┴──────────┴────────┴─────────┘

# Grype, Snyk, Anchore — alternatives. All read SBOM (CycloneDX or SPDX).
# Generate SBOM
$ syft myorg/app:v1.0 -o cyclonedx-json > sbom.json

Tradeoffs

Frequently Asked Questions