Writing

Distroless images

Minimal Docker images that include only what's needed to run your app — no shell, no package manager. How they work and why they matter for security.

August 3, 2024 5 min read
DockerSecurityDevOps

Introduction

Distroless images are minimal Docker images designed to include only the essential components required to run an application. They exclude package managers, shells, and other utilities that typically come with standard Docker images. This approach enhances security and performance by reducing the attack surface.

For a Java application, a distroless image contains only the Java Runtime Environment (JRE). Below is an example Dockerfile demonstrating how to set up a Java application using a distroless image:

# Stage 1: Build the application using Maven
FROM maven:3.8.5-openjdk-17 AS build
WORKDIR /app
COPY . .
RUN mvn clean package -DskipTests

# Stage 2: Run the application using a distroless image
FROM gcr.io/distroless/java17
COPY --from=build /app/target/myapp.jar /app/myapp.jar

CMD ["-jar", "/app/myapp.jar"]

In this Dockerfile:

  1. The first stage uses maven:3.8.5-openjdk-17 to compile the application.
  2. WORKDIR sets the working directory to /app.
  3. COPY brings in all source files.
  4. RUN executes Maven to build the JAR, skipping tests.
  5. The second stage uses gcr.io/distroless/java17 to run the app.
  6. COPY --from=build pulls the JAR from the build stage.
  7. CMD specifies the run command.

This setup ensures the final image is minimal — only what is necessary to run the application.

Why use distroless images

  • Lightweight: Smaller size makes them easier to store and transport.
  • Enhanced security: Fewer packages mean fewer potential vulnerabilities.
  • Reduced blast radius: Fewer components limit the damage from a security compromise.

How to use

Google provides open source distroless images at https://github.com/GoogleContainerTools/distroless — pick the image appropriate for your runtime.

Distroless images shine especially when combined with ephemeral containers. Ephemeral containers differ from regular containers in that they lack resource guarantees, will never be automatically restarted, and are not appropriate for building applications — but they are ideal for debugging minimal production images without adding a shell to the image itself.

The future: chiseled images

Chiseled images expand on distroless principles by removing even more unnecessary components, optimized for specific workloads.

Benefits of chiseled images:

  1. Smaller size: Even smaller than distroless, easier to distribute.
  2. Enhanced security: Fewer components, fewer attack vectors.
  3. Optimized performance: Tailored for specific applications.

References