Docker Distroless Images: Best Practices and Common Pitfalls

Understanding Docker Distroless Images

Distroless images are minimal container images that strip away everything except your application and its runtime dependencies. They contain no package managers, no shells, no utilities, and no operating system bloat. Originally introduced by Google, these images are built from a base operating system layer (like Debian or Alpine) but include only the essential libraries and binaries required to run a specific type of application.

The key insight behind distroless images is simple: your container doesn't need bash, curl, or even a package manager to run in production. It just needs your compiled binary and the shared libraries it links against. By removing everything else, you dramatically reduce the attack surface, image size, and operational overhead.

Here's a quick comparison to illustrate the difference in size and composition:

# Standard Debian-based image
docker pull node:18-slim
# Size: ~240MB, contains bash, curl, package manager, hundreds of binaries

# Distroless equivalent
docker pull gcr.io/distroless/nodejs18-debian12
# Size: ~120MB, contains only node binary, its libraries, and nothing else

Why Distroless Images Matter

The benefits of adopting distroless images extend across security, performance, and operational domains:

Security hardening: Without a shell or utilities, an attacker who compromises your application cannot easily execute arbitrary commands, download payloads, or move laterally within the container. Common exploit patterns like reverse shells simply don't work because /bin/sh doesn't exist. Vulnerability scanners also report far fewer CVEs since there are fewer packages to scan.

Reduced image size: Smaller images mean faster pull times, lower storage costs, and quicker deployments. In large-scale CI/CD pipelines where containers are pulled hundreds of times per day, the cumulative time savings are substantial.

Supply chain simplicity: Each additional package in a container image is a dependency you must track, patch, and verify. Distroless images drastically reduce your supply chain footprint, making software bill of materials (SBOM) management more straightforward.

Compliance alignment: Many regulatory frameworks require minimizing installed software to only what is necessary. Distroless images provide a strong foundation for meeting these requirements by default.

How to Use Distroless Images

Using distroless images effectively requires a multi-stage Docker build. In the first stage, you compile your application or gather dependencies using a full-featured build image. In the second stage, you copy only the necessary artifacts into the distroless runtime image.

Example: Go Application

Go applications are ideal candidates because they compile to static binaries. However, if your binary uses net for DNS resolution or needs TLS certificates, you'll want the distroless static image that includes ca-certificates and a minimal nsswitch configuration.

# Stage 1: Build the application
FROM golang:1.22 AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o server .

# Stage 2: Create the distroless runtime image
FROM gcr.io/distroless/static-debian12:nonroot

WORKDIR /
COPY --from=builder /app/server /server
USER nonroot:nonroot
EXPOSE 8080

ENTRYPOINT ["/server"]

Notice several important details in this Dockerfile:

CGO_ENABLED=0 ensures a fully static binary with no dynamic library dependencies
The static-debian12 image includes CA certificates and /etc/nsswitch.conf for proper DNS resolution
The nonroot tag uses a non-root user with UID 65532, adding another security layer
The ENTRYPOINT uses exec form (JSON array) rather than shell form

Example: Node.js Application

For interpreted languages like Node.js, you need the language-specific distroless image that includes the runtime:

# Stage 1: Install dependencies and build
FROM node:18-slim AS builder

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
# Build TypeScript or bundle assets if needed
RUN npm run build

# Stage 2: Distroless runtime
FROM gcr.io/distroless/nodejs18-debian12

WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

EXPOSE 3000
ENTRYPOINT ["node", "dist/index.js"]

Example: Java Application

Java applications require the JRE and often need specific debugging or monitoring capabilities:

# Stage 1: Build the JAR
FROM maven:3.9-eclipse-temurin-21 AS builder

WORKDIR /app
COPY pom.xml .
COPY src ./src
RUN mvn package -DskipTests

# Stage 2: Distroless Java runtime
FROM gcr.io/distroless/java21-debian12

WORKDIR /app
COPY --from=builder /app/target/myapp.jar ./app.jar

EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

Debugging Distroless Containers

One of the first challenges you'll encounter is the inability to shell into a distroless container for debugging. Since there is no shell, commands like docker exec -it container sh will fail. Here are practical strategies for debugging:

Use a debug companion image: Many distroless images have a corresponding debug tag that includes a shell and debugging tools. During development or troubleshooting, temporarily switch to the debug variant:

# Production image
FROM gcr.io/distroless/static-debian12:nonroot

# Debug image (has busybox shell)
FROM gcr.io/distroless/static-debian12:debug-nonroot
# Now you can: docker exec -it container sh

Leverage Kubernetes ephemeral containers: In Kubernetes, you can attach an ephemeral debug container to a running pod without modifying the original container image:

kubectl debug -it my-pod --image=busybox --target=my-container

Rely on structured logging and observability: Since you cannot easily inspect file systems or run diagnostic commands, invest in proper application logging, metrics endpoints, and health checks. Export logs to stdout/stderr and collect them with a log aggregator.

Best Practices for Distroless Images

1. Always use multi-stage builds. Never try to install packages directly into a distroless image — there is no package manager. Multi-stage builds are the canonical pattern: build in a full-featured image, copy artifacts into the distroless runtime.

2. Choose the right base image variant. Google maintains several distroless base images, each targeting different use cases:

static: For fully static binaries (Go, Rust) — includes CA certificates and nsswitch
base: For dynamically linked binaries — includes glibc, libssl, and libcrypto
cc: For C/C++ applications requiring libstdc++
nodejs, python3, java: Language-specific runtimes
nonroot variants: Run as non-root user (UID 65532) for additional security

3. Verify dynamic library dependencies. If your binary links against shared libraries, you must ensure those libraries exist in the distroless image. Use ldd on the build system to check dependencies:

# On the build stage, check what libraries your binary needs
RUN ldd /app/my-binary

# Example output:
#   linux-vdso.so.1
#   libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6
#   libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0

# These must be present in your chosen distroless image

If your binary requires libraries not in the distroless image, you have two options: copy the libraries manually from the build stage, or switch to a less minimal image like base or cc.

4. Handle CA certificates properly. Applications making HTTPS requests need root CA certificates. The static and base images include the CA bundle at /etc/ssl/certs/ca-certificates.crt. If your application expects certificates elsewhere, you may need to copy them or set environment variables like SSL_CERT_FILE.

5. Set locale and timezone explicitly. Distroless images have minimal locale data. If your application requires specific locale settings or timezone information, copy the necessary files from the build stage:

FROM debian:12-slim AS builder

# Install timezone data
RUN apt-get update && apt-get install -y tzdata && \
    cp /usr/share/zoneinfo/America/New_York /etc/localtime && \
    echo "America/New_York" > /etc/timezone

FROM gcr.io/distroless/static-debian12
COPY --from=builder /etc/localtime /etc/localtime
COPY --from=builder /etc/timezone /etc/timezone

6. Run as non-root. Always prefer the nonroot tagged images. These run your application as UID 65532, which has no special privileges. If your application needs to bind to a low port (< 1024), use sysctl net.ipv4.ip_unprivileged_port_start=0 or a port mapping strategy rather than running as root.

7. Handle signals correctly. Without a shell, signal handling depends entirely on your application. Ensure your application handles SIGTERM and SIGINT gracefully for proper shutdowns. Test signal behavior with:

docker run --name test my-distroless-app &
docker kill --signal SIGTERM test
# Check if your app exited cleanly

8. Include essential configuration files. Some applications expect certain files to exist, like /etc/passwd, /etc/group, or /etc/nsswitch.conf. Distroless images include minimal versions of these. If your application needs user lookups or specific NSS configurations, verify compatibility early in development.

Common Pitfalls and How to Avoid Them

Pitfall 1: Assuming a shell exists. This is the most frequent mistake. CI/CD scripts, health checks, and orchestration commands often assume /bin/sh is available. Kubernetes liveness probes using exec.command with shell commands will fail:

# This will FAIL on distroless images
livenessProbe:
  exec:
    command:
      - /bin/sh
      - -c
      - "echo healthcheck"

# Use HTTP probes or exec probes without shell
livenessProbe:
  exec:
    command:
      - /server
      - healthcheck   # Your app handles this subcommand
# Or better:
livenessProbe:
  httpGet:
    path: /health
    port: 8080

Pitfall 2: Copying files with incorrect paths. Distroless images have a specific filesystem layout. Copying files to locations like /usr/local/bin may work, but /home or /opt might not exist. Always verify the target directory exists or create it in the distroless stage:

FROM gcr.io/distroless/static-debian12:nonroot

# This directory may not exist — check the image manifest
COPY --from=builder /app/config /etc/myapp/config

# Safer approach: use known paths like /etc, /app, /var
COPY --from=builder /app/config /etc/myapp/

Pitfall 3: Not testing DNS resolution. Some distroless images include /etc/nsswitch.conf to enable DNS, but others may not. If your application makes network calls, test DNS resolution thoroughly. A common symptom is connections failing with "unknown host" errors. The static image includes nsswitch; the base image includes full glibc NSS modules.

Pitfall 4: Ignoring the C library compatibility. If you build a binary against glibc (typical for C, C++, Rust with external C dependencies), it will not run on a musl-based or fully static image. Conversely, a musl-linked binary won't run on glibc-based distroless images. Know your toolchain:

Debian-based distroless images use glibc
Alpine-based static builds can use musl — but distroless doesn't use Alpine
Go binaries with CGO_ENABLED=0 are truly static and work anywhere

Pitfall 5: Overlooking file permissions. When using nonroot images, your copied files must be readable (and writable if needed) by UID 65532. Files copied from the build stage typically retain their original ownership. Use --chown in COPY instructions:

COPY --from=builder --chown=65532:65532 /app/data /app/data

Pitfall 6: Expecting environment variable expansion. Without a shell, environment variable expansion in ENTRYPOINT or CMD doesn't happen. The exec form passes arguments literally. If you need variable expansion, use a small init process or handle it in your application code:

# This does NOT expand $PORT — it passes the literal string '$PORT'
ENTRYPOINT ["server", "--port=$PORT"]

# Handle expansion in your application or use an entrypoint script
# (which requires a shell image)

Pitfall 7: Using the wrong debug tag. Not all distroless images have a debug variant. Check the available tags in the container registry before relying on them. Common debug tags include debug and debug-nonroot.

Pitfall 8: Neglecting to pin image digests. Distroless images are updated regularly. For production reproducibility, always pin to a specific digest rather than a floating tag:

# Floating tag — may change underneath you
FROM gcr.io/distroless/static-debian12:nonroot

# Pinned digest — reproducible builds
FROM gcr.io/distroless/static-debian12:nonroot@sha256:abc123def456...

Use docker inspect or the container registry API to find the current digest of your chosen image.

Building Custom Distroless-Like Images

Sometimes the pre-built distroless images don't match your exact needs. You can build your own minimal images using similar principles with docker/distroless tooling or by manually constructing a minimal filesystem:

# Using bazel and the distroless build tools
# https://github.com/GoogleContainerTools/distroless

# Alternative: manual minimal image with Docker
FROM debian:12-slim AS builder

# Install only what you need
RUN apt-get update && apt-get install -y --no-install-recommends \
    libssl3 libcrypto3 && \
    rm -rf /var/lib/apt/lists/*

# Extract only required files
RUN mkdir /rootfs && \
    cp --parents /lib/x86_64-linux-gnu/libssl.so.3 /rootfs/ && \
    cp --parents /lib/x86_64-linux-gnu/libcrypto.so.3 /rootfs/ && \
    cp --parents /etc/ssl/certs/ca-certificates.crt /rootfs/

FROM scratch
COPY --from=builder /rootfs/ /
COPY my-binary /app/
ENTRYPOINT ["/app/my-binary"]

This approach gives you complete control but requires careful maintenance. For most use cases, the official distroless images are the better starting point.

Integration with CI/CD Pipelines

Distroless images integrate well with modern CI/CD workflows, but require a few adjustments:

# Example GitHub Actions workflow step
- name: Build and push distroless image
  run: |
    docker build \
      --tag myapp:latest \
      --tag myapp:${{ github.sha }} \
      --file Dockerfile \
      .
    
    # Verify the image doesn't contain a shell
    docker run --rm --entrypoint="" myapp:latest sh 2>&1 | grep -q "not found"
    echo "Verified: no shell in production image"

Consider adding a step that verifies your production image doesn't contain unexpected binaries. A simple check that sh or bash is absent can prevent accidentally shipping a debug image to production.

Conclusion

Distroless images represent a significant evolution in container security posture — they trade convenience for a dramatically reduced attack surface and smaller footprint. The initial learning curve of losing shell access is quickly offset by the security gains and operational simplicity of running only what you truly need. By following the patterns outlined here — multi-stage builds, proper base image selection, non-root execution, and signal-aware applications — you can ship containers that are both lean and secure. The most important takeaway is to treat the absence of a shell not as a limitation but as a feature: if an attacker cannot interact with your container, they cannot exploit it in many common attack scenarios. Start with the official distroless images, test thoroughly in staging with debug variants, and pin your production images to specific digests for reproducible, auditable deployments.