What changes in the runtime image
The Distroless project provides runtime images that contain the application and the dependencies it needs, without the full operating environment you would expect in a standard Linux distribution. The project's standard images have no shell or package manager. That choice removes components the application does not need to run.
A smaller image does not make insecure code secure. A vulnerable dependency, an overly broad permission or an endpoint that accepts malformed input still needs to be addressed. So treat Distroless as one decision within runtime hardening, alongside application security and version management.
Separate build tooling from the runtime environment
In a multi-stage build, you install and run build tools in a separate stage and copy only what is needed into the runtime image. Before copying, check which files end up in the artifact: compiled code, runtime dependencies and static assets. Secret files, history and development tools are not automatically part of what you ship.
Pay attention to compatibility of the runtime, native libraries and CPU architecture. A successful build does not prove the application will run in the minimal image. Run the artifact and exercise a real path, including any file access or temporary writes the application needs to perform.
Define the runtime conditions too
Use a non-root user where the application allows it, plan for a read-only file system and limit capabilities and resources to what is needed. If the application must write, define a dedicated path with appropriate permissions. Restrictions applied without a runtime test can cause operational failures that are hard to pin down.
Networking and secrets also call for decisions. The container should have only the destinations and credentials it needs to do its job. There is no reason for a build-stage secret to remain inside the image. Walk through the path by which configuration and secrets reach the process at startup.
Plan diagnostics before you remove the shell
When the production image has no shell, diagnostics rely on logs, metrics, traces and the host environment's tooling. Write error messages that explain what failed without exposing secrets. Verify that a planned failure can be identified from the data you collect.
The project also offers debug variants, but there is no need to make them your regular production image. Define an investigation process in an approved, restricted environment. Do not add diagnostic tools to every image just because no other way of getting the information was planned.
Keep the hardening in place for the life of the product
Scan both the runtime image and the application dependencies. Record the base image and its version, and review updates as part of maintenance. Pinning a digest helps reproduce an artifact, but it requires a process that flags when the base needs updating.
- The image is tested under runtime conditions similar to production.
- It contains no secret files or unnecessary development dependencies.
- There is a diagnostics path that does not require a shell in production.
- Base image updates and scan findings have an owner.