mirror of https://github.com/docker/docs.git
dhi: add customizations (#23035)
<!--Delete sections as needed --> ## Description Add customize topic for DHI. Add customize to features. Add /go/ redirects for in-app links https://deploy-preview-23035--docsdocker.netlify.app/dhi/how-to/customize/ https://deploy-preview-23035--docsdocker.netlify.app/dhi/features/flexible/ ## Related issues or tickets ENGDOCS-2823 ENGDOCS-2808 ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: Craig <craig.osterhout@docker.com>
This commit is contained in:
Craig Osterhout
GitHub
parent
4ba5ea0554
commit
081dcfdc8c
|
|
@ -1,14 +1,15 @@
|
|||
---
|
||||
title: Flexible, repository-based pricing
|
||||
title: Flexibility through pricing and customization
|
||||
linktitle: Flexibility
|
||||
description: Understand how Docker Hardened Images give you cost control by charging only for what you mirror and use.
|
||||
keywords: docker hardened images pricing, per repo billing, flexible pricing model, mirror image pricing, container pricing model
|
||||
description: Learn how Docker Hardened Images give you control over costs and image behavior through repository-based pricing and secure customization.
|
||||
keywords: docker hardened images pricing, per repo billing, flexible pricing model, mirror image pricing, container pricing model, customize hardened image
|
||||
weight: 30
|
||||
---
|
||||
|
||||
Docker Hardened Images are designed not only for security and compliance, but
|
||||
also for operational and financial efficiency. With a model that charges per
|
||||
repository, you get precise control over what you use and what you pay for.
|
||||
repository and tooling that lets you customize images securely, you gain both
|
||||
cost control and configuration flexibility.
|
||||
|
||||
## Repository mirroring on your terms
|
||||
|
||||
|
|
@ -30,15 +31,27 @@ freely choose the best tag for each use case without incurring additional cost.
|
|||
This flexibility allows teams to adopt secure images without being limited by
|
||||
billing complexity or image count.
|
||||
|
||||
## Customize images to fit your environment
|
||||
|
||||
In addition to cost flexibility, Docker Hardened Images let you securely
|
||||
customize images before use. You can add your own packages, tools, certificates,
|
||||
and configuration files using a guided customization workflow in Docker Hub.
|
||||
These customizations are securely built and signed, so they integrate with your
|
||||
compliance and CI/CD policies.
|
||||
|
||||
## Share access across your team
|
||||
|
||||
Once a repository is mirrored, anyone in your organization can pull, verify,
|
||||
scan, and run images from it. There are no extra charges based on usage volume.
|
||||
You mirror what you need, and your teams use it freely.
|
||||
|
||||
## Cost efficiency for platform teams
|
||||
## Cost and operational efficiency for platform teams
|
||||
|
||||
This model simplifies budgeting for platform and security teams. Rather than
|
||||
tracking usage at the individual image or tag level, you manage your spend
|
||||
through the repositories you control, aligning security enforcement, team access,
|
||||
and cost in one place.
|
||||
The Docker Hardened Images model simplifies budgeting for platform and security
|
||||
teams. Instead of tracking usage at the image or tag level, you manage spend
|
||||
through the repositories you mirror. And since you can customize images within
|
||||
Docker Hub itself, everything is in one place, reducing complexity and
|
||||
operational overhead.
|
||||
|
||||
By aligning repository mirroring, team access, image customization, and cost,
|
||||
Docker Hardened Images help you build securely and operate efficiently.
|
||||
|
|
|
|||
|
|
@ -12,6 +12,10 @@ params:
|
|||
description: Learn how to mirror an image into your organization's namespace and optionally push it to another private registry.
|
||||
icon: compare_arrows
|
||||
link: /dhi/how-to/mirror/
|
||||
- title: Customize a Docker Hardened Image
|
||||
description: Learn how to customize a DHI to suit your organization's needs.
|
||||
icon: settings
|
||||
link: /dhi/how-to/customize/
|
||||
- title: Use a Docker Hardened Image
|
||||
description: Learn how to pull, run, and reference Docker Hardened Images in Dockerfiles, CI pipelines, and standard development workflows.
|
||||
icon: play_arrow
|
||||
|
|
|
|||
|
|
@ -0,0 +1,147 @@
|
|||
---
|
||||
title: Customize a Docker Hardened Image
|
||||
linkTitle: Customize an image
|
||||
weight: 25
|
||||
keywords: debug, hardened images, DHI, customize, certificate, artifact
|
||||
description: Learn how to customize a Docker Hardened Images (DHI).
|
||||
---
|
||||
|
||||
You can customize a Docker Hardened Image (DHI) to suit your specific needs
|
||||
using the Docker Hub UI. This allows you to select a base image, add packages,
|
||||
add artifacts, and configure settings. In addition, the build pipeline ensures that
|
||||
your customized image is built securely and includes attestations.
|
||||
|
||||
To add a customized Docker Hardened Image to your organization, an organization
|
||||
owner must first [mirror](./mirror.md) the DHI repository to your organization.
|
||||
Once the repository is mirrored, any user with access to the mirrored DHI
|
||||
repository can create a customized image.
|
||||
|
||||
## Customize a Docker Hardened Image
|
||||
|
||||
To customize a Docker Hardened Image, follow these steps:
|
||||
|
||||
1. Sign in to [Docker Hub](https://hub.docker.com).
|
||||
2. Select **My Hub**.
|
||||
3. In the namespace drop-down, select your organization that has a mirrored DHI
|
||||
repository.
|
||||
4. Select the mirrored DHI repository.
|
||||
5. Select the **Customizations** tab.
|
||||
6. Select **Create customization**.
|
||||
|
||||
At this point, the on-screen instructions will guide you through the
|
||||
customization process. You can continue with the following steps for more
|
||||
details.
|
||||
|
||||
7. Select the image version you want to customize.
|
||||
8. Add packages.
|
||||
|
||||
1. In the **Packages** drop-down, select the packages you want to add to the
|
||||
image.
|
||||
|
||||
The packages available in the drop-down are OS system packages for the
|
||||
selected image variant. For example, if you are customizing the Alpine
|
||||
variant of the Python DHI, the list will include all Alpine system
|
||||
packages.
|
||||
|
||||
2. In the **OCI artifacts** drop-down, first, select the repository that
|
||||
contains the OCI artifact image. Then, select the tag you want to use from
|
||||
that repository. Finally, specify the specific paths you want to include
|
||||
from the OCI artifact image.
|
||||
|
||||
The OCI artifacts are images that you have previously
|
||||
built and pushed to a repository in the same namespace as the mirrored
|
||||
DHI. For example, you can add a custom root CA certificate or a another
|
||||
image that contains a tool you need, like adding Python to a Node.js
|
||||
image. For more details on how to create an OCI artifact image, see
|
||||
[Create an OCI artifact image](#create-an-oci-artifact-image).
|
||||
|
||||
When combining images that contain directories and files with the same
|
||||
path, images later in the list will overwrite files from earlier images.
|
||||
To manage this, you must select paths to include and optionally exclude
|
||||
from each OCI artifact image. This allows you to control which files are
|
||||
included in the final customized image.
|
||||
|
||||
By default, no files are included from the OCI artifact image. You must
|
||||
explicitly include the paths you want. After including a path, you can
|
||||
then explicitly exclude files or directories underneath it.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> When files necessary for runtime are overwritten by OCI artifacts, the
|
||||
> image build still succeeds, but you may have issues when running the
|
||||
> image.
|
||||
|
||||
9. 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`.
|
||||
2. Select the platforms you want to build the image for.
|
||||
3. 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.
|
||||
4. Specify the users to add to the image.
|
||||
5. Specify the user groups to add to the image.
|
||||
6. Select which [user](/reference/dockerfile/#user) to run the images as.
|
||||
7. Specify the [environment variables](/reference/dockerfile/#env) and their
|
||||
values that the image will contain.
|
||||
8. Add [annotations](/build/metadata/annotations/) to the image.
|
||||
9. Add [labels](/reference/dockerfile/#label) to the image.
|
||||
10. Select **Create Customization**.
|
||||
|
||||
A summary of the customization appears. It may take some time for the image
|
||||
to build. Once built, it will appear in the **Tags** tab of the repository,
|
||||
and your team members can pull it like any other image.
|
||||
|
||||
## Edit or delete a Docker Hardened Image customization
|
||||
|
||||
To edit or delete a Docker Hardened Image customization, follow these steps:
|
||||
|
||||
1. Sign in to [Docker Hub](https://hub.docker.com).
|
||||
2. Select **My Hub**.
|
||||
3. In the namespace drop-down, select your organization that has a mirrored DHI.
|
||||
4. Select the mirrored DHI repository.
|
||||
5. Select the **Customizations** tab.
|
||||
6. Select **Edit** to edit the customization, or select the trashcan icon to
|
||||
delete the customization.
|
||||
7. Follow the on-screen instructions to complete the edit or deletion.
|
||||
|
||||
## Create an OCI artifact image
|
||||
|
||||
An OCI artifact image is a Docker image that contains files or directories that
|
||||
you want to include in your customized Docker Hardened Image (DHI). This can
|
||||
include additional tools, libraries, or configuration files.
|
||||
|
||||
When creating an image to use as an OCI artifact, it should ideally be as
|
||||
minimal as possible and contain only the necessary files.
|
||||
|
||||
For example, to distribute a custom root CA certificate as part of a trusted CA
|
||||
bundle, you can use a multi-stage build. This approach registers your
|
||||
certificate with the system and outputs an updated CA bundle, which can be
|
||||
extracted into a minimal final image:
|
||||
|
||||
```dockerfile
|
||||
# syntax=docker/dockerfile:1
|
||||
|
||||
FROM <your-namespace>/dhi-bash:5-dev AS certs
|
||||
|
||||
ENV DEBIAN_FRONTEND=noninteractive
|
||||
|
||||
RUN mkdir -p /usr/local/share/ca-certificates/my-rootca
|
||||
COPY certs/rootCA.crt /usr/local/share/ca-certificates/my-rootca
|
||||
|
||||
RUN update-ca-certificates
|
||||
|
||||
FROM scratch
|
||||
COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
|
||||
```
|
||||
|
||||
You can follow this pattern to create other OCI artifacts, such as images
|
||||
containing tools or libraries that you want to include in your customized DHI.
|
||||
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.
|
||||
|
|
@ -350,3 +350,10 @@
|
|||
- /go/permissions/
|
||||
"/desktop/setup/install/mac-permission-requirements/#binding-privileged-ports":
|
||||
- /go/port-mapping/
|
||||
|
||||
# Docker Hardened Images (DHI)
|
||||
"/dhi/how-to/customize/":
|
||||
- /go/dhi-customization/
|
||||
|
||||
"/dhi/how-to/customize/#create-an-oci-artifact-image":
|
||||
- /go/dhi-customization-artifacts/
|
||||
Loading…
Reference in New Issue