Skip to content

Commit 081dcfd

Browse files
craig-osterhoutcraig-osterhout
authored
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 <[email protected]>
1 parent 4ba5ea0 commit 081dcfd

File tree

4 files changed

+180
-9
lines changed

4 files changed

+180
-9
lines changed

‎content/manuals/dhi/features/flexible.md

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,15 @@
11
---
2-
title: Flexible, repository-based pricing
2+
title: Flexibility through pricing and customization
33
linktitle: Flexibility
4-
description: Understand how Docker Hardened Images give you cost control by charging only for what you mirror and use.
5-
keywords: docker hardened images pricing, per repo billing, flexible pricing model, mirror image pricing, container pricing model
4+
description: Learn how Docker Hardened Images give you control over costs and image behavior through repository-based pricing and secure customization.
5+
keywords: docker hardened images pricing, per repo billing, flexible pricing model, mirror image pricing, container pricing model, customize hardened image
66
weight: 30
77
---
88

99
Docker Hardened Images are designed not only for security and compliance, but
1010
also for operational and financial efficiency. With a model that charges per
11-
repository, you get precise control over what you use and what you pay for.
11+
repository and tooling that lets you customize images securely, you gain both
12+
cost control and configuration flexibility.
1213

1314
## Repository mirroring on your terms
1415

@@ -30,15 +31,27 @@ freely choose the best tag for each use case without incurring additional cost.
3031
This flexibility allows teams to adopt secure images without being limited by
3132
billing complexity or image count.
3233

34+
## Customize images to fit your environment
35+
36+
In addition to cost flexibility, Docker Hardened Images let you securely
37+
customize images before use. You can add your own packages, tools, certificates,
38+
and configuration files using a guided customization workflow in Docker Hub.
39+
These customizations are securely built and signed, so they integrate with your
40+
compliance and CI/CD policies.
41+
3342
## Share access across your team
3443

3544
Once a repository is mirrored, anyone in your organization can pull, verify,
3645
scan, and run images from it. There are no extra charges based on usage volume.
3746
You mirror what you need, and your teams use it freely.
3847

39-
## Cost efficiency for platform teams
48+
## Cost and operational efficiency for platform teams
49+
50+
The Docker Hardened Images model simplifies budgeting for platform and security
51+
teams. Instead of tracking usage at the image or tag level, you manage spend
52+
through the repositories you mirror. And since you can customize images within
53+
Docker Hub itself, everything is in one place, reducing complexity and
54+
operational overhead.
4055

41-
This model simplifies budgeting for platform and security teams. Rather than
42-
tracking usage at the individual image or tag level, you manage your spend
43-
through the repositories you control, aligning security enforcement, team access,
44-
and cost in one place.
56+
By aligning repository mirroring, team access, image customization, and cost,
57+
Docker Hardened Images help you build securely and operate efficiently.

‎content/manuals/dhi/how-to/_index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ params:
1212
description: Learn how to mirror an image into your organization's namespace and optionally push it to another private registry.
1313
icon: compare_arrows
1414
link: /dhi/how-to/mirror/
15+
- title: Customize a Docker Hardened Image
16+
description: Learn how to customize a DHI to suit your organization's needs.
17+
icon: settings
18+
link: /dhi/how-to/customize/
1519
- title: Use a Docker Hardened Image
1620
description: Learn how to pull, run, and reference Docker Hardened Images in Dockerfiles, CI pipelines, and standard development workflows.
1721
icon: play_arrow

‎content/manuals/dhi/how-to/customize.md

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
---
2+
title: Customize a Docker Hardened Image
3+
linkTitle: Customize an image
4+
weight: 25
5+
keywords: debug, hardened images, DHI, customize, certificate, artifact
6+
description: Learn how to customize a Docker Hardened Images (DHI).
7+
---
8+
9+
You can customize a Docker Hardened Image (DHI) to suit your specific needs
10+
using the Docker Hub UI. This allows you to select a base image, add packages,
11+
add artifacts, and configure settings. In addition, the build pipeline ensures that
12+
your customized image is built securely and includes attestations.
13+
14+
To add a customized Docker Hardened Image to your organization, an organization
15+
owner must first [mirror](./mirror.md) the DHI repository to your organization.
16+
Once the repository is mirrored, any user with access to the mirrored DHI
17+
repository can create a customized image.
18+
19+
## Customize a Docker Hardened Image
20+
21+
To customize a Docker Hardened Image, follow these steps:
22+
23+
1. Sign in to [Docker Hub](https://hub.docker.com).
24+
2. Select **My Hub**.
25+
3. In the namespace drop-down, select your organization that has a mirrored DHI
26+
repository.
27+
4. Select the mirrored DHI repository.
28+
5. Select the **Customizations** tab.
29+
6. Select **Create customization**.
30+
31+
At this point, the on-screen instructions will guide you through the
32+
customization process. You can continue with the following steps for more
33+
details.
34+
35+
7. Select the image version you want to customize.
36+
8. Add packages.
37+
38+
1. In the **Packages** drop-down, select the packages you want to add to the
39+
image.
40+
41+
The packages available in the drop-down are OS system packages for the
42+
selected image variant. For example, if you are customizing the Alpine
43+
variant of the Python DHI, the list will include all Alpine system
44+
packages.
45+
46+
2. In the **OCI artifacts** drop-down, first, select the repository that
47+
contains the OCI artifact image. Then, select the tag you want to use from
48+
that repository. Finally, specify the specific paths you want to include
49+
from the OCI artifact image.
50+
51+
The OCI artifacts are images that you have previously
52+
built and pushed to a repository in the same namespace as the mirrored
53+
DHI. For example, you can add a custom root CA certificate or a another
54+
image that contains a tool you need, like adding Python to a Node.js
55+
image. For more details on how to create an OCI artifact image, see
56+
[Create an OCI artifact image](#create-an-oci-artifact-image).
57+
58+
When combining images that contain directories and files with the same
59+
path, images later in the list will overwrite files from earlier images.
60+
To manage this, you must select paths to include and optionally exclude
61+
from each OCI artifact image. This allows you to control which files are
62+
included in the final customized image.
63+
64+
By default, no files are included from the OCI artifact image. You must
65+
explicitly include the paths you want. After including a path, you can
66+
then explicitly exclude files or directories underneath it.
67+
68+
> [!NOTE]
69+
>
70+
> When files necessary for runtime are overwritten by OCI artifacts, the
71+
> image build still succeeds, but you may have issues when running the
72+
> image.
73+
74+
9. Select **Next: Configure** and then configure the following options.
75+
76+
1. Specify a suffix that is appended to the customized image's tag. For
77+
example, if you specify `custom` when customizing the `dhi-python:3.13`
78+
image, the customized image will be tagged as `dhi-python:3.13_custom`.
79+
2. Select the platforms you want to build the image for.
80+
3. Add [`ENTRYPOINT`](/reference/dockerfile/#entrypoint) and
81+
[`CMD`](/reference/dockerfile/#cmd) arguments to the image. These
82+
arguments are appended to the base image's entrypoint and command.
83+
4. Specify the users to add to the image.
84+
5. Specify the user groups to add to the image.
85+
6. Select which [user](/reference/dockerfile/#user) to run the images as.
86+
7. Specify the [environment variables](/reference/dockerfile/#env) and their
87+
values that the image will contain.
88+
8. Add [annotations](/build/metadata/annotations/) to the image.
89+
9. Add [labels](/reference/dockerfile/#label) to the image.
90+
10. Select **Create Customization**.
91+
92+
A summary of the customization appears. It may take some time for the image
93+
to build. Once built, it will appear in the **Tags** tab of the repository,
94+
and your team members can pull it like any other image.
95+
96+
## Edit or delete a Docker Hardened Image customization
97+
98+
To edit or delete a Docker Hardened Image customization, follow these steps:
99+
100+
1. Sign in to [Docker Hub](https://hub.docker.com).
101+
2. Select **My Hub**.
102+
3. In the namespace drop-down, select your organization that has a mirrored DHI.
103+
4. Select the mirrored DHI repository.
104+
5. Select the **Customizations** tab.
105+
6. Select **Edit** to edit the customization, or select the trashcan icon to
106+
delete the customization.
107+
7. Follow the on-screen instructions to complete the edit or deletion.
108+
109+
## Create an OCI artifact image
110+
111+
An OCI artifact image is a Docker image that contains files or directories that
112+
you want to include in your customized Docker Hardened Image (DHI). This can
113+
include additional tools, libraries, or configuration files.
114+
115+
When creating an image to use as an OCI artifact, it should ideally be as
116+
minimal as possible and contain only the necessary files.
117+
118+
For example, to distribute a custom root CA certificate as part of a trusted CA
119+
bundle, you can use a multi-stage build. This approach registers your
120+
certificate with the system and outputs an updated CA bundle, which can be
121+
extracted into a minimal final image:
122+
123+
```dockerfile
124+
# syntax=docker/dockerfile:1
125+
126+
FROM <your-namespace>/dhi-bash:5-dev AS certs
127+
128+
ENV DEBIAN_FRONTEND=noninteractive
129+
130+
RUN mkdir -p /usr/local/share/ca-certificates/my-rootca
131+
COPY certs/rootCA.crt /usr/local/share/ca-certificates/my-rootca
132+
133+
RUN update-ca-certificates
134+
135+
FROM scratch
136+
COPY --from=certs /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
137+
```
138+
139+
You can follow this pattern to create other OCI artifacts, such as images
140+
containing tools or libraries that you want to include in your customized DHI.
141+
Install the necessary tools or libraries in the first stage, and then copy the
142+
relevant files to the final stage that uses `FROM scratch`. This ensures that
143+
your OCI artifact is minimal and contains only the necessary files.
144+
145+
Build and push the OCI artifact image to a repository in your organization's
146+
namespace and it automatically appears in the customization workflow when you
147+
select the OCI artifacts to add to your customized Docker Hardened Image.

‎data/redirects.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -350,3 +350,10 @@
350350
- /go/permissions/
351351
"/desktop/setup/install/mac-permission-requirements/#binding-privileged-ports":
352352
- /go/port-mapping/
353+
354+
# Docker Hardened Images (DHI)
355+
"/dhi/how-to/customize/":
356+
- /go/dhi-customization/
357+
358+
"/dhi/how-to/customize/#create-an-oci-artifact-image":
359+
- /go/dhi-customization-artifacts/

0 commit comments

Comments
 (0)