Skip to content

docker: add distroless container build#17680

Closed
maxhuebler wants to merge 1 commit intoprometheus:mainfrom
maxhuebler:distroless-container-build
Closed

docker: add distroless container build#17680
maxhuebler wants to merge 1 commit intoprometheus:mainfrom
maxhuebler:distroless-container-build

Conversation

@maxhuebler
Copy link

@maxhuebler maxhuebler commented Dec 12, 2025

docker: add distroless container build option

This PR introduces support for building Prometheus container images based on distroless as an alternative to the current busybox-based images. The new distroless images contain only the statically linked Prometheus binaries, CA certificates, and timezone data, minimizing the attack surface and reducing vulnerability scanner noise.

Key changes:

  • Adds Dockerfile.distroless for building minimal images using gcr.io/distroless/static:nonroot as the base.
  • Copies CA certificates and timezone data from a small build stage (Debian).
  • Integrates a common-docker-distroless target into Makefile.common to build these images for all configured architectures.
  • Ensures required binaries and npm license assets are built before the image build.
  • No changes to the default image build flow; distroless images are opt-in.

Rationale:

  • Removes busybox and shell utilities from the final image, as Prometheus does not require them at runtime.
  • Reduces the number of reported vulnerabilities for end users and organizations using automated container scanning.
  • Aligns with best practices for minimal, secure container images.

Which issue(s) does the PR fix:

  • If there are no dependencies to Busybox, such as shell scripts, lets consider just the statically linked binary, CA and TZ data in the Prometheus container images.
  • Minimizing the footprint would help the end-user organizations to focus on the real vulnerabilities. Organizations that do container scanning are easily overloaded by the amount of vulnerabilities. They might not have the capacity to see if each one of those is exploitable. Someone not knowing any better might see many Prometheus ecosystem images show up on their vulnerabilities radar and staying there for some time. This also becomes a problem for whoever runs their observability stack.
  • Discussion from my PR in Add prom/busybox:alpine image busybox#66 (Add prom/busybox:alpine image) to fix vulnerabilities on busybox.

Does this PR introduce a user-facing change?

[ENHANCEMENT] Added support for building Prometheus container images using distroless as a base. Use `make common-docker-distroless` to build minimal images containing only the Prometheus binaries, CA certificates, and timezone data.

Signed-off-by: Max Huebler <max@huebler.us>
ARG OS="linux"

# Stage: get CA certs and tzdata from a small Debian image
FROM debian:trixie-slim AS certs

Check warning

Code scanning / Scorecard

Pinned-Dependencies Medium

score is 7: containerImage not pinned by hash
Remediation tip: pin your Docker image by updating debian:trixie-slim to debian:trixie-slim@sha256:e711a7b30ec1261130d0a121050b4ed81d7fb28aeabcf4ea0c7876d4e9f5aca2
Click Remediation section below for further remediation help
&& rm -rf /var/lib/apt/lists/*

# Final minimal image based on distroless static
FROM gcr.io/distroless/static:nonroot

Check warning

Code scanning / Scorecard

Pinned-Dependencies Medium

score is 7: containerImage not pinned by hash
Remediation tip: pin your Docker image by updating gcr.io/distroless/static:nonroot to gcr.io/distroless/static:nonroot@sha256:2b7c93f6d6648c11f0e80a48558c8f77885eb0445213b8e69a6a0d7c89fc6ae4
Click Remediation section below for further remediation help
Copy link

@jkataja jkataja left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the currently used distroless image, the output will not be as described. Instead it would need to be based on scratch to contain only the statically linked binary and minimal data.

org.opencontainers.image.licenses="Apache License 2.0"

# Copy CA certs and timezone data from certs stage
COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Turns out the GoogleContainerTools distroless image already includes CA certs and TZ data. This is only required with scratch.

&& rm -rf /var/lib/apt/lists/*

# Final minimal image based on distroless static
FROM gcr.io/distroless/static:nonroot
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The first stage is not required with this image. Using scratch will produce the most minimal image.


# Final minimal image based on distroless static
FROM gcr.io/distroless/static:nonroot

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The parameters need to be added to this stage

Suggested change
ARG ARCH
ARG OS

COPY npm_licenses.tar.bz2 /npm_licenses.tar.bz2

WORKDIR /prometheus
RUN mkdir -p /etc/prometheus /prometheus \
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With scratch this should be done in the first stage, as the image will not have mkdir chown etc.

@roidelapluie
Copy link
Member

roidelapluie commented Jan 16, 2026

I did not notice this.
I made #17876 which should provide more flexibility and looks more simple by using google's distroless images. My PR also works with current CI setup.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants