"Distroless" Docker Images

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

For more information, see this talk (video).

Why should I use distroless images?

Restricting what's in your runtime container to precisely what's necessary for your app is a best practice employed by Google and 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.

How do I use distroless images?

These images are built using the bazel tool, but they can also be used through other Docker image build tooling.

Docker

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

• Pick the right base image for your application stack We publish the following distroless base images on gcr.io:

  • gcr.io/distroless/base
  • gcr.io/distroless/python2.7
  • gcr.io/distroless/python3
  • gcr.io/distroless/nodejs
  • gcr.io/distroless/java
  • gcr.io/distroless/java/jetty
  • gcr.io/distroless/cc
  • gcr.io/distroless/dotnet

• 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 on multi-stage builds.

  Here's a quick example.

  # Start by building the application.
  FROM golang:1.8 as build
  
  WORKDIR /go/src/app
  COPY . .
  
  RUN go-wrapper download   # "go get -d -v ./..."
  RUN go-wrapper install
  
  # Now copy it into our base image.
  FROM gcr.io/distroless/base
  COPY --from=build /go/bin/app /
  CMD ["/app"]
  

Bazel

For full documentation on how to use bazel to generate Docker images, see the bazelbuild/rules_docker repository.

For documentation and examples on how to use the bazel package manager rules, see ./package_manager

Examples can be found in this repository in the examples directory.

Examples

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

• Java
• Python
• Python 3
• Golang
• Node.js
• dotnet

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 are built and released.