mirror of
https://github.com/docker/docs.git
synced 2026-03-27 22:38:54 +07:00
dhi: feedback (#23703)
<!--Delete sections as needed --> ## Description Updated DHI topics from feedback. - [/dhi/how-to/customize/](https://deploy-preview-23703--docsdocker.netlify.app/dhi/how-to/customize/): - Add multi-platform info - Add some initial best practices - [/dhi/about/available/](https://deploy-preview-23703--docsdocker.netlify.app/dhi/about/available/): Add some justification for using Debian. - [dhi/about/build-process/](https://deploy-preview-23703--docsdocker.netlify.app/dhi/about/build-process/): Add high-level build process ## Related issues or tickets ENGDOCS-3099 ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: Craig Osterhout <craig.osterhout@docker.com> Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>
This commit is contained in:
Craig Osterhout
@@ -8,6 +8,10 @@ params:
|
||||
description: Learn what a hardened image is, how Docker Hardened Images are built, what sets them apart from typical base and application images, and why you should use them.
|
||||
icon: info
|
||||
link: /dhi/about/what/
|
||||
- title: Build process
|
||||
description: Learn how Docker builds, tests, and maintains Docker Hardened Images through an automated, security-focused pipeline.
|
||||
icon: build
|
||||
link: /dhi/about/build-process/
|
||||
- title: Image testing
|
||||
description: See how Docker Hardened Images are automatically tested for standards compliance, functionality, and security.
|
||||
icon: science
|
||||
|
||||
@@ -40,7 +40,9 @@ requirements:
|
||||
Each image maintains a minimal and secure runtime layer by removing
|
||||
non-essential components like shells, package managers, and debugging tools.
|
||||
This helps reduce the attack surface while retaining compatibility with common
|
||||
runtime environments.
|
||||
runtime environments. To maintain this lean, secure foundation, DHI standardizes
|
||||
on Debian for glibc-based images, which provides broad compatibility while
|
||||
minimizing complexity and maintenance overhead.
|
||||
|
||||
Example tags include:
|
||||
|
||||
|
||||
151
content/manuals/dhi/about/build-process.md
Normal file
151
content/manuals/dhi/about/build-process.md
Normal file
@@ -0,0 +1,151 @@
|
||||
---
|
||||
title: How Docker Hardened Images are built
|
||||
linkTitle: Build process
|
||||
description: Learn how Docker builds, tests, and maintains Docker Hardened Images through an automated, security-focused pipeline.
|
||||
keywords: docker hardened images, slsa build level 3, automated patching, ai guardrail, build process, signed sbom, supply chain security
|
||||
weight: 15
|
||||
---
|
||||
|
||||
Docker Hardened Images are built through an automated pipeline that monitors
|
||||
upstream sources, applies security updates, and publishes signed artifacts.
|
||||
This page explains the build process for both DHI images and customized
|
||||
images built from them.
|
||||
|
||||
## Build triggers
|
||||
|
||||
Builds start automatically. You don't trigger them manually. The system monitors
|
||||
for changes and starts builds in two scenarios:
|
||||
|
||||
- [Upstream updates](#upstream-updates)
|
||||
- [Customization changes](#customization-changes)
|
||||
|
||||
### Upstream updates
|
||||
|
||||
New releases, package updates, or CVE fixes from upstream projects trigger base
|
||||
image rebuilds. These builds go through quality checks to ensure security and
|
||||
reliability.
|
||||
|
||||
#### Monitoring for updates
|
||||
|
||||
Docker continuously monitors upstream projects for new releases, package
|
||||
updates, and security advisories. When changes are detected, the system
|
||||
automatically queues affected images for rebuild using a SLSA Build Level
|
||||
3-compliant build system.
|
||||
|
||||
Docker uses three strategies to track updates:
|
||||
|
||||
- GitHub releases: Monitors specific GitHub repositories for new releases and
|
||||
automatically updates the image definition when a new version is published.
|
||||
- GitHub tags: Tracks tags in GitHub repositories to detect new versions.
|
||||
- Package repositories: Monitors Alpine Linux, Debian, and Ubuntu package
|
||||
repositories through Docker Scout's package database to detect updated
|
||||
packages.
|
||||
|
||||
In addition to explicit upstream tracking, Docker also monitors transitive
|
||||
dependencies. When a package update is detected (for example, a security patch
|
||||
for a library), Docker automatically identifies and rebuilds all images within
|
||||
the support window that use that package.
|
||||
|
||||
### Customization changes
|
||||
|
||||
Updates to your OCI artifact customizations trigger rebuilds of your customized
|
||||
images.
|
||||
|
||||
When you customize a DHI image, your changes are packaged as OCI artifacts that
|
||||
layer on top of the base image. Docker monitors your artifact repositories and
|
||||
automatically rebuilds your customized images whenever you push updates.
|
||||
|
||||
The rebuild process fetches the current base image, applies your OCI artifacts,
|
||||
signs the result, and publishes it automatically. You don't need to manage
|
||||
builds or maintain CI pipelines for your customized images.
|
||||
|
||||
Customized images are also rebuilt automatically when the base DHI image they
|
||||
depend on receives updates, ensuring your images always include the latest
|
||||
security patches.
|
||||
|
||||
## Build pipeline
|
||||
|
||||
The following sections describe the build pipeline architecture and workflow for
|
||||
Docker Hardened Images based on:
|
||||
|
||||
- [Base image pipeline](#base-image-pipeline)
|
||||
- [Customized image pipeline](#customized-image-pipeline)
|
||||
|
||||
### Base image pipeline
|
||||
|
||||
Each Docker Hardened Image is built through an automated pipeline:
|
||||
|
||||
1. Monitoring: Docker monitors upstream sources for updates (new releases,
|
||||
package updates, security advisories).
|
||||
2. Rebuild trigger: When changes are detected, an automated rebuild starts.
|
||||
3. AI guardrail: An AI system fetches upstream diffs and scans them with
|
||||
language-aware checks. The guardrail focuses on high-leverage issues that can
|
||||
cause significant problems, such as inverted error checks, ignored failures,
|
||||
resource mishandling, or suspicious contributor activity. When it spots
|
||||
potential risks, it blocks the PR from auto-merging.
|
||||
4. Human review: If the AI identifies risks with high confidence,
|
||||
Docker engineers review the flagged code, reproduce the issue, and decide on
|
||||
the appropriate action. Engineers often contribute fixes back to upstream
|
||||
projects, improving the code for the entire community. When fixes are accepted
|
||||
upstream, the DHI build pipeline applies the patch immediately to protect
|
||||
customers while the fix moves through the upstream release process.
|
||||
5. Testing: Images undergo comprehensive testing for compatibility and
|
||||
functionality.
|
||||
6. Signing and attestations: Docker signs each image and generates
|
||||
attestations (SBOMs, VEX documents, build provenance).
|
||||
7. Publishing: The signed image and attestations are published to Docker Hub.
|
||||
8. Cascade rebuilds: If any customized images use this base, their rebuilds
|
||||
are automatically triggered.
|
||||
|
||||
Docker responds quickly to critical vulnerabilities. By building essential
|
||||
components from source rather than waiting for packaged updates, Docker can
|
||||
patch Critical and High-severity CVEs within days of upstream fixes and publish
|
||||
updated images with new attestations.
|
||||
|
||||
The following diagram shows the base image build flow:
|
||||
|
||||
```goat {class="text-sm"}
|
||||
.-------------------. .-------------------. .-------------------. .-------------------.
|
||||
| Docker monitors |----->| Trigger rebuild |----->| AI guardrail |----->| Human review |
|
||||
| upstream sources | | | | scans changes | | |
|
||||
'-------------------' '-------------------' '-------------------' '-------------------'
|
||||
|
|
||||
v
|
||||
.-------------------. .-------------------. .-------------------. .-------------------.
|
||||
| Cascade rebuilds |<-----| Publish to |<-----| Sign & generate |<-----| Testing |
|
||||
| (if needed) | | Docker Hub | | attestations | | |
|
||||
'-------------------' '-------------------' '-------------------' '-------------------'
|
||||
```
|
||||
|
||||
### Customized image pipeline
|
||||
|
||||
When you customize a DHI image, the build process is simplified:
|
||||
|
||||
1. Monitoring: Docker monitors your OCI artifact repositories for changes.
|
||||
2. Rebuild trigger: When you push updates to your OCI artifacts, or when the base
|
||||
DHI image is updated, an automated rebuild starts.
|
||||
3. Fetch base image: The latest base DHI image is fetched.
|
||||
4. Apply customizations: Your OCI artifacts are applied to the base image.
|
||||
5. Signing and attestations: Docker signs the customized image and generates
|
||||
attestations (SBOMs, VEX documents, build provenance).
|
||||
6. Publishing: The signed customized image and attestations are published to
|
||||
Docker Hub.
|
||||
|
||||
Docker handles the entire process automatically, so you don't need to manage
|
||||
builds for your customized images. However, you're responsible for testing your
|
||||
customized images and managing any CVEs introduced by your OCI artifacts.
|
||||
|
||||
The following diagram shows the customized image build flow:
|
||||
|
||||
```goat {class="text-sm"}
|
||||
.-------------------. .-------------------. .-------------------.
|
||||
| Docker monitors |----->| Trigger rebuild |----->| Fetch base |
|
||||
| OCI artifacts | | | | DHI image |
|
||||
'-------------------' '-------------------' '-------------------'
|
||||
|
|
||||
v
|
||||
.-------------------. .-------------------. .-------------------.
|
||||
| Publish to |<-----| Sign & generate |<-----| Apply |
|
||||
| Docker Hub | | attestations | | customizations |
|
||||
'-------------------' '-------------------' '-------------------'
|
||||
```
|
||||
@@ -92,21 +92,28 @@ To customize a Docker Hardened Image, follow these steps:
|
||||
- The UID and GID ownership of the script
|
||||
- The octal file permissions of the script
|
||||
|
||||
1. Select **Next: Configure** and then configure the following options.
|
||||
1. Specify a suffix that is appended to the customized image's tag. For
|
||||
example, if you specify `custom` when customizing the `dhi-python:3.13`
|
||||
image, the customized image will be tagged as `dhi-python:3.13_custom`.
|
||||
1. Select the platforms you want to build the image for.
|
||||
1. Add [`ENTRYPOINT`](/reference/dockerfile/#entrypoint) and
|
||||
[`CMD`](/reference/dockerfile/#cmd) arguments to the image. These
|
||||
arguments are appended to the base image's entrypoint and command.
|
||||
1. Specify the users to add to the image.
|
||||
1. Specify the user groups to add to the image.
|
||||
1. Select which [user](/reference/dockerfile/#user) to run the images as.
|
||||
1. Specify the [environment variables](/reference/dockerfile/#env) and their
|
||||
values that the image will contain.
|
||||
1. Add [annotations](/build/metadata/annotations/) to the image.
|
||||
1. Add [labels](/reference/dockerfile/#label) to the image.
|
||||
1. Select **Next: Configure** to configure the following image settings:
|
||||
|
||||
1. Specify the [environment variables](/reference/dockerfile/#env) and their
|
||||
values that the image will contain.
|
||||
1. Add [labels](/reference/dockerfile/#label) to the image.
|
||||
1. Add [annotations](/build/metadata/annotations/) to the image.
|
||||
1. Specify the users to add to the image.
|
||||
1. Specify the user groups to add to the image.
|
||||
1. Select which [user](/reference/dockerfile/#user) to run the images as.
|
||||
1. Add [`ENTRYPOINT`](/reference/dockerfile/#entrypoint) arguments to the
|
||||
image. These arguments are appended to the base image's entrypoint.
|
||||
1. Add [`CMD`](/reference/dockerfile/#cmd) arguments to the image. These
|
||||
arguments are appended to the base image's command.
|
||||
1. Specify a suffix for the customization name that is appended to the
|
||||
customized image's tag. For example, if you specify `custom` when
|
||||
customizing the `dhi-python:3.13` image, the customized image will be
|
||||
tagged as `dhi-python:3.13_custom`.
|
||||
1. Select the platforms you want to build the image for. You must select at
|
||||
least one platform.
|
||||
|
||||
1. Select **Next: Review customization**.
|
||||
|
||||
1. Select **Create Customization**.
|
||||
|
||||
A summary of the customization appears. It may take some time for the image
|
||||
@@ -168,6 +175,57 @@ Install the necessary tools or libraries in the first stage, and then copy the
|
||||
relevant files to the final stage that uses `FROM scratch`. This ensures that
|
||||
your OCI artifact is minimal and contains only the necessary files.
|
||||
|
||||
Build and push the OCI artifact image to a repository in your organization's
|
||||
namespace and it automatically appears in the customization workflow when you
|
||||
select the OCI artifacts to add to your customized Docker Hardened Image.
|
||||
In order for the OCI artifact to be available in a DHI customization, it must be built and
|
||||
pushed to a repository in the same namespace as the mirrored DHI repository.
|
||||
|
||||
If you're customizing a DHI for multiple platforms (such as `linux/amd64` and
|
||||
`linux/arm64`), build your OCI artifact for all the platforms using the
|
||||
`--platform` flag:
|
||||
|
||||
```console
|
||||
$ docker buildx build --platform linux/amd64,linux/arm64 \
|
||||
-t <your-namespace>/my-oci-artifact:latest \
|
||||
--push .
|
||||
```
|
||||
|
||||
This creates a single image manifest that you can use for each platform. The
|
||||
customization build system automatically selects the correct platform variant
|
||||
when building each customized image.
|
||||
|
||||
> [!IMPORTANT]
|
||||
>
|
||||
> The customization UI will only allow you to select platforms that are
|
||||
> available in all OCI artifacts you've added. If a platform is missing from
|
||||
> any OCI artifact, you won't be able to select that platform for your
|
||||
> customization.
|
||||
|
||||
Once pushed to a repository in your organization's namespace, the OCI artifact
|
||||
automatically appears in the customization workflow when you select OCI
|
||||
artifacts to add to your customized Docker Hardened Image.
|
||||
|
||||
### Best practices for OCI artifacts
|
||||
|
||||
Follow these best practices when creating OCI artifacts for DHI customizations:
|
||||
|
||||
- Use multi-stage builds: Build or install dependencies in a builder stage,
|
||||
then copy only the necessary files to a `FROM scratch` final stage. This keeps
|
||||
the OCI artifact minimal and free of unnecessary build tools.
|
||||
|
||||
- Include only essential files: OCI artifacts should contain only the files
|
||||
you need to add to the customized image. Avoid including package managers,
|
||||
shells, or other utilities that won't be used in the final image.
|
||||
|
||||
- Match target platforms: Build your OCI artifact for all platforms you plan
|
||||
to use in your customizations. Use `docker buildx build --platform` to create
|
||||
multi-platform images when needed.
|
||||
|
||||
- Use specific tags: Tag your OCI artifacts with specific versions or dates
|
||||
(like `v1.0` or `20250101`) rather than relying solely on `latest`. This
|
||||
ensures reproducible builds and makes it easier to track which artifacts are
|
||||
used in which customizations.
|
||||
|
||||
- Enable immutable tags: Consider enabling [immutable
|
||||
tags](../../docker-hub/repos/manage/hub-images/immutable-tags.md) for your
|
||||
OCI artifact repositories. This prevents accidental overwrites and ensures that
|
||||
each version of your OCI artifact remains unchanged, improving reproducibility
|
||||
and reliability of your customizations.
|
||||
Reference in New Issue
Block a user