diff --git a/content/manuals/dhi/features/flexible.md b/content/manuals/dhi/features/flexible.md index a5dcdcbed53..f1f7d00b17b 100644 --- a/content/manuals/dhi/features/flexible.md +++ b/content/manuals/dhi/features/flexible.md @@ -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 + +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. -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. +By aligning repository mirroring, team access, image customization, and cost, +Docker Hardened Images help you build securely and operate efficiently. diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md index 0492b228b20..f32ec4fccac 100644 --- a/content/manuals/dhi/how-to/_index.md +++ b/content/manuals/dhi/how-to/_index.md @@ -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 diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md new file mode 100644 index 00000000000..ea3810591b5 --- /dev/null +++ b/content/manuals/dhi/how-to/customize.md @@ -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 /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. diff --git a/data/redirects.yml b/data/redirects.yml index 4ecf3bb864b..e5943e3e604 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -349,3 +349,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/ \ No newline at end of file