What are distroless images and what advantages do they offer?

Distroless images are stripped-down container images. Google's GoogleContainerTools team coined the term: "distribution-less" — no full Linux distribution, just the bare minimum to run an app. The result is dramatically smaller and more secure than traditional images.

#Theory

#TL;DR

• A distroless image contains: the language runtime + your binary + CA certs. That is it.
• No shell (no bash, no sh).
• No package manager (no apt, no apk).
• No utilities (no curl, no vim, no ps).
• Maintained by Google: gcr.io/distroless/<runtime>.
• Variants: static, base, cc, python3, nodejs22, java21, etc. Plus :debug and :nonroot flavors.
• Why use it: smaller image (often 5-50 MB final), drastically smaller attack surface, faster CVE remediation (less stuff to scan).

#Distroless variants

Each has :debug and :nonroot (preferred) variants.

#Quick example: Go static binary

Final image: ~10 MB. Just the Go binary + the bare runtime support files. No shell to drop into, no apt-get, nothing that does not directly serve the app.

#Node.js example

Final image: ~150 MB (Node runtime is large). Compare to node:22 (~1 GB) or even node:22-alpine (~200 MB) — and the alpine has shell and apk.

#Why distroless

#Security

• No shell = no shell-based exploits. A compromised app cannot exec bash.
• No package manager = attacker cannot install tools to escalate.
• Fewer files = fewer CVEs. Vulnerability scanners report fewer findings; remediation is just "bump base image".

#Size

• 80-95% smaller than full Debian/Ubuntu.
• Smaller pulls, faster cold starts, less storage.
• Cumulative impact at scale: hundreds of services × millions of pulls = real bandwidth savings.

#Predictability

• The image contains exactly what you put in. No surprise utilities. No drift between dev and prod.

#The debugging trade-off

The biggest objection to distroless: how do I docker exec sh?

Answer: you do not. The trade-off is real. Three workarounds:

#1. :debug variant

The :debug tag adds busybox. Use this for development; deploy :nonroot to production.

#2. Sidecar debug container

In Kubernetes:

Runs an alpine shell that shares namespaces with your distroless container. You can poke at the app's filesystem and processes from a sister container.

#3. Build separate :debug image

Produce two tags: myapp:1.0 (distroless) and myapp:1.0-debug (with shell). Deploy the debug one when needed.

#Comparison with Alpine

Alpine is the size champion among full distros; distroless beats it on attack surface but at the cost of debuggability. Many projects use alpine as builder + distroless as final.

#Common mistakes

Trying to docker exec sh on a distroless image

The shell is not there. For debugging, use the :debug variant or the sidecar pattern.

Running healthchecks that need curl

Solutions:

• For Node: HEALTHCHECK CMD node -e "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))"
• For others: include a tiny static health-checker binary; or use external healthcheck (Kubernetes probe instead of Docker healthcheck).

Using gcr.io/distroless/base for a Go binary that needs glibc

If your Go binary uses CGO (any C interop), use cc or base variant. For pure Go, use static.

Forgetting :nonroot

Use gcr.io/distroless/static:nonroot (UID 65532) by default. Reduces blast radius if escape happens.

#Real-world adoption

• Google internal services: distroless is the default for production images (Google created it).
• Kubernetes ecosystem: many CNCF projects ship distroless images (Prometheus components, kube-state-metrics).
• Banking / regulated industries: distroless reduces auditor pain and CVE management overhead.
• Serverless: smaller images = faster cold starts. AWS Lambda, Cloud Run benefit.

#Follow-up questions

Q: Can I write a Dockerfile that starts FROM distroless directly (without multi-stage)?

A: Technically yes, but you cannot install anything (no shell, no apt). The distroless base is meant as the target of a multi-stage build, not the builder.

Q: What is the difference between static and base?

A: static has just glibc and CA certs. base adds busybox-static (a few utilities). Use static for Go/Rust pure-static binaries; base for C/C++ that need a few utilities.

Q: Are distroless images signed?

A: Yes — Google signs them via Cosign. Verify with cosign verify gcr.io/distroless/base --certificate-identity=....

Q: Is there a Wolfi or Chainguard equivalent?

A: Yes — Chainguard Images is a popular alternative that has been gaining ground. Wolfi-based, similar minimalism, often with even faster CVE patching. Worth evaluating for new projects.

Q: (Senior) When would you NOT use distroless?

A: Three cases. (1) Your app needs a shell at runtime (rare; usually a smell). (2) You need many tools at runtime that would require building a custom minimal image (better: rethink the app). (3) The team is not yet equipped to debug without docker exec sh — invest in tooling (sidecar debug, observability) before forcing distroless on them. For greenfield Go/Rust services, distroless is a no-brainer; for legacy apps with shell-dependent operations, migrate gradually.

#Examples

#Go in scratch (even smaller than distroless)

scratch is even more minimal than distroless. Just the binary + CA certs. Final image: roughly the size of the binary.

#Distroless Node with healthcheck

No curl in distroless; we use the Node runtime as our healthcheck binary. Same effect, no extra tools needed.

#Production-like Python

Python runtime + your code + dependencies, nothing else. Final image around 50-150 MB depending on dep size — much less than python:3.13 slim's ~150-300 MB.