Repository files navigation

"Distroless" images contain only your application and its runtime dependencies.They do not contain package managers, shells or any other programs you would expect to find in a standard Linux distribution.

For more information, see thistalk (video).

Since March 2023, Distroless images use oci manifests, if you see errors referencingapplication/vnd.oci.image.manifest.v1+jsonorapplication/vnd.oci.image.index.v1+json, update your container tooling (docker, jib, etc) to latest.

Restricting what's in your runtime container to precisely what's necessary for your app is a best practice employed by Googleand other tech giants that have used containers in production for many years.It improves the signal to noise of scanners (e.g. CVE) and reduces the burden of establishing provenance to just what you need.

Distroless images arevery small.The smallest distroless image,gcr.io/distroless/static-debian12, is around 2 MiB.That's about 50% of the size ofalpine (~5 MiB), and less than 2% of the size ofdebian (124 MiB).

These images are built usingbazel, but they can also be used through other Docker image build tooling.

The following images are currently published and updated by the distroless project (seeSUPPORT_POLICY.md for support timelines)

These images refer to image indexes with references to all supported architectures. Architecture specific images can be directly referenced using an additional architecture suffix on the tag, likegcr.io/distroless/static-debian12:latest-amd64

Any other tags are considered deprecated and are no longer updated

Debian 13 distroless images use the debianUsrMerge scheme. If you userules_distroless to add packages to an image, setmergedusr = True inapt.install.

Distroless's serving infrastructure has moved to artifact registry but we still use thegcr.io domain. Users will get the benefits of the newer infrastructure without changing their builds.

All distroless images are signed bycosign with ephemeral keys (keyless) -- this is the only supported mechanism starting November 2023.We recommend verifying any distroless image you use before building your image. You can verify the keyless signature of any distroless image with:

cosign verify$IMAGE_NAME --certificate-oidc-issuer https://accounts.google.com --certificate-identity keyless@distroless.iam.gserviceaccount.com

Note that distroless images by default do not contain a shell.That means the DockerfileENTRYPOINT command, when defined, must be specified invector form, to avoid the container runtime prefixing with a shell.

This works:

ENTRYPOINT ["myapp"]

But this does not work:

ENTRYPOINT"myapp"

For the same reasons, if the entrypoint is set to the empty vector, the CMD command should be specified invector form (see examples below).Note that by default static, base and cc images have the empty vector entrypoint. Images with an included language runtime have a language specific default (see:java,nodejs,python3).

Docker multi-stage builds make using distroless images easy.Follow these steps to get started:

• Pick the right base image for your application stack.

• Write a multi-stage docker file.Note: This requires Docker 17.05 or higher.

  The basic idea is that you'll have one stage to build your application artifacts, and insert them into your runtime distroless image.If you'd like to learn more, please see the documentation onmulti-stage builds.

Here's a quick example for go:

# Start by building the application.FROM golang:1.18 as buildWORKDIR /go/src/appCOPY . .RUN go mod downloadRUN CGO_ENABLED=0 go build -o /go/bin/app# Now copy it into our base image.FROM gcr.io/distroless/static-debian12COPY --from=build /go/bin/app /CMD ["/app"]

You can find other examples here:

• Java
• Python 3
• Go
• Node.js
• Rust

To run any example, go to the directory for the language and run:

docker build -t myapp.docker run -t myapp

To run theNode.js Express example app and expose the container's ports:

npm install# Install express and its transitive dependenciesdocker build -t myexpressapp.# Normal build commanddocker run -p 3000:3000 -t myexpressapp

This should expose the Express application to yourlocalhost:3000

For full documentation on how to use bazel to generate Container images, see thebazel-contrib/rules_oci repository.

For documentation and example on how to create custom container images, see theGoogleContainerTools/rules_distroless repository.

Examples can be found in theGoogleContainerTools/rules_distroless repository.

We have some examples on how to run some common application stacks in the /examples directory.See here for:

• Java
• Python 3
• Go
• Node.js

See here for examples on how to complete some common tasks in your image:

• Adding and running as a non-root user
• Including Debian Packages
• Including CA certificates

See here for more information on how these images arebuilt and released.

Distroless images are based on Debian 12 (bookworm). Images are explicitly tagged with Debian version suffixes (e.g.-debian12). Specifying an image without the distribution will currently select-debian12 images, but that will change in the future to a newer version of Debian. It can be useful to reference the distribution explicitly, to prevent breaking builds when the next Debian version is released.

Distroless tracks the upstream Debian releases, usingGithub actions to automatically generate a pull request when there are updates.

Distroless images are minimal and lack shell access. The:debug image set for each language provides a busybox shell to enter.

For example:

cd examples/python3/

edit theDockerfile to change the final image to:debug:

FROM gcr.io/distroless/python3-debian12:debugCOPY . /appWORKDIR /appCMD ["hello.py","/etc"]

then build and launch with a shell entrypoint:

docker build -t my_debug_image.

$ docker run --entrypoint=sh -ti my_debug_image/app# lsBUILD       Dockerfile  hello.py

Note: If the image you are using already has a tag, for examplegcr.io/distroless/java17-debian12:nonroot, use the tagdebug-<existing tag> instead, for examplegcr.io/distroless/java17-debian12:debug-nonroot.

Note:ldd is not installed in the base image as it's a shell script, you can copy it in or download it.

• Kubernetes, since v1.15
• Knative
• Tekton
• Teleport
• BloodHound bySpecterOps

If your project uses Distroless, send a PR to add your project here!

• distroless-users Google Group
• Kubernetes slack #distroless channel