From c4e2ad1b6a01d6731a6ff296349e3979fd461b18 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Tue, 21 Oct 2025 15:37:43 -0700 Subject: [PATCH 1/5] dhi: add helm Signed-off-by: Craig Osterhout --- content/manuals/dhi/features/_index.md | 4 + content/manuals/dhi/features/flexible.md | 1 - content/manuals/dhi/features/helm.md | 28 ++ content/manuals/dhi/how-to/_index.md | 4 + content/manuals/dhi/how-to/helm.md | 311 +++++++++++++++++++++++ data/summary.yaml | 3 + 6 files changed, 350 insertions(+), 1 deletion(-) create mode 100644 content/manuals/dhi/features/helm.md create mode 100644 content/manuals/dhi/how-to/helm.md diff --git a/content/manuals/dhi/features/_index.md b/content/manuals/dhi/features/_index.md index ecb99bf1d15e..07e5d26bce50 100644 --- a/content/manuals/dhi/features/_index.md +++ b/content/manuals/dhi/features/_index.md @@ -24,6 +24,10 @@ params: description: Learn how Docker Hardened Images offer repository-based flexibility with no per-image or per-pull limitations. icon: wallet link: /dhi/features/flexible/ + - title: Docker Hardened Image charts + description: Learn about Docker Hardened Image charts. + icon: leaderboard + link: /dhi/features/helm/ --- Docker Hardened Images (DHIs) go beyond minimal base and application images by diff --git a/content/manuals/dhi/features/flexible.md b/content/manuals/dhi/features/flexible.md index f1f7d00b17bb..cfa7d680a314 100644 --- a/content/manuals/dhi/features/flexible.md +++ b/content/manuals/dhi/features/flexible.md @@ -3,7 +3,6 @@ title: Flexibility through pricing and customization linktitle: Flexibility 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 diff --git a/content/manuals/dhi/features/helm.md b/content/manuals/dhi/features/helm.md new file mode 100644 index 000000000000..9d939e5a7cb7 --- /dev/null +++ b/content/manuals/dhi/features/helm.md @@ -0,0 +1,28 @@ +--- +title: Docker Hardened Image charts +linktitle: Helm charts +description: Learn about Docker Hardened Image charts. +keywords: docker hardened images helm, dhi helm charts, kubernetes hardened images, k8s hardened images +--- + +Docker Hardened Image (DHI) charts are Docker-provided Helm charts built from upstream and community-maintained sources, +designed for compatibility with Docker Hardened Images. These charts are available as OCI artifacts within the DHI +catalog on Docker Hub. + +## Comprehensive supply chain security + +Like the hardened images, DHI charts incorporate multiple layers of security metadata to ensure transparency and trust: + +- SLSA Level 3 compliance: Each chart is built with our SLSA Build Level 3 system, including a detailed build + provenance, and meeting the standards set by the Supply-chain Levels for Software Artifacts (SLSA) framework. +- Software Bill of Materials (SBOMs): Comprehensive SBOMs are provided, detailing all components referenced within the + chart to facilitate vulnerability management and compliance audits. +- Cryptographic signing: All associated metadata is cryptographically signed by Docker, ensuring integrity and + authenticity. +- Hardened configuration: Charts automatically reference Docker hardened images, ensuring security in deployments. + +## Developer Friendly + +DHI charts are robustly tested after building to ensure they work out-of-the-box with Docker Hardened Images. This +removes friction in migration and reduces developer workload in implementing the charts, ensuring seamless +compatibility. diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md index 7b2372dd6bb9..6019cf2dc1e9 100644 --- a/content/manuals/dhi/how-to/_index.md +++ b/content/manuals/dhi/how-to/_index.md @@ -24,6 +24,10 @@ params: description: Learn how to use Docker Hardened Images in Kubernetes deployments. icon: play_arrow link: /dhi/how-to/k8s/ + - title: Use a Docker Hardened Image chart + description: Learn how to use a Docker Hardened Image chart. + icon: leaderboard + link: /dhi/how-to/helm/ - title: Manage Docker Hardened Images description: Learn how to manage your mirrored and customized Docker Hardened Images in your organization. icon: reorder diff --git a/content/manuals/dhi/how-to/helm.md b/content/manuals/dhi/how-to/helm.md new file mode 100644 index 000000000000..090b835630b7 --- /dev/null +++ b/content/manuals/dhi/how-to/helm.md @@ -0,0 +1,311 @@ +--- +title: Use a Docker Hardened Image chart +linktitle: Use a Helm chart +description: Learn how to use a Docker Hardened Image chart. +keywords: use hardened image, helm, k8s, kubernetes, dhi chart, chart +weight: 36 +params: + sidebar: + badge: + color: violet + text: EA +--- + +{{< summary-bar feature_name="Docker Hardened Image charts" >}} + +Docker Hardened Image (DHI) charts are Docker-provided [Helm charts](https://helm.sh/docs/) built from upstream and +community-maintained sources, designed for compatibility with Docker Hardened Images. These charts are available as OCI +artifacts within the DHI catalog on Docker Hub. For more details, see [Docker Hardened Image +charts](/dhi/features/helm/). + +DHI charts incorporate multiple layers of supply chain security that aren't present in upstream charts: + +- SLSA Level 3 compliance: Each chart is built with SLSA Build Level 3 standards, including detailed build provenance +- Software Bill of Materials (SBOMs): Comprehensive SBOMs detail all components referenced within the chart +- Cryptographic signing: All associated metadata is cryptographically signed by Docker for integrity and authenticity +- Hardened configuration: Charts automatically reference Docker Hardened Images for secure deployments +- Tested compatibility: Charts are robustly tested to work out-of-the-box with Docker Hardened Images + +This guide walks you through how to use the DHI Redis chart. You can adapt the steps to other DHI charts and your own +Kubernetes workflows. DHI charts work like any other Helm chart, but you must mirror them to your own repository before +using them. + +## Prerequisites + +To follow along with this guide, you need: + +- A Kubernetes cluster set up and [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) installed. To + test locally, you can use Docker Desktop with Kubernetes enabled. For more information, see [Install Docker + Desktop](/desktop/install/windows-install/) and [Enable Kubernetes](/desktop/features/kubernetes/). +- Helm installed. For more information, see the [Helm installation guide](https://helm.sh/docs/intro/install/). +- Access to DHI. For more information about starting a free trial, see [Get started with Docker Hardened + Images](/dhi/get-started/). + +## Step 1: Find a Docker Helm chart and request access + +To find a Docker Helm chart for DHI: + +1. Go to the Hardened Images catalog in [Docker Hub](https://hub.docker.com/hardened-images/catalog) and sign in. +2. In the left sidebar, select your organization that has DHI access. +3. In the left sidebar, select **Hardened Images** > **Catalog**. +4. In the search bar, search for a Helm chart. For this guide, search for `redis chart`. +5. Select the Helm chart to view its details. For this guide, select the **Redis HA Helm Chart**. + + You will see the **Overview** page with details about the chart. + +6. If visible, select **Request access**. + + Before you can mirror the chart, you may need to request access for the Early Access program. If **Request access** + is visible on the Helm chart repository details page, select it and wait for an email notifying you that the access + has been granted by Docker. + +## Step 2: Mirror the Docker Helm chart + +You must mirror the Docker Helm chart to your own repository before using it. + +To mirror the Docker Helm chart to your organization, in the Helm chart repository details page you opened in [step +1](#step-1-find-the-docker-helm-chart): + +1. Select **Mirror Helm chart**. +2. Follow the on-screen instructions to mirror the Helm chart. For this guide, name the destination repository + `dhi-redis-ha-chart`. + + When complete, you will see the details page for the mirrored Helm chart in your organization's namespace. On this + page, you can verify that the necessary dependencies have also been mirrored. + +3. If any dependencies are not mirrored, mirror them now. For this guide, select **Mirror image** if necessary for the + Redis image, then follow the on-screen instructions. + +You only need to mirror the Helm chart and its dependencies once. After they are mirrored, you can use them in any +Kubernetes cluster that can access your organization's namespace. + +## Step 3: Optional. Mirror the Helm chart and/or its images to your own registry + +By default, when you mirror a chart or image from the Docker Hardened Images catalog, the chart or image is mirrored to +your namespace in Docker Hub. If you want to then mirror to your own third-party registry, you can follow the +instructions in [How to mirror an image](/dhi/how-to/mirror/) for either the chart, the image, or both. + +The same `regctl` tool that is used for mirroring container images can also be used for mirroring Helm charts, as Helm +charts are OCI artifacts. + +For example: + +```console +regctl image copy \ + "${SRC_CHART_REPO}:${TAG}" \ + "${DEST_REG}/${DEST_CHART_REPO}:${TAG}" \ + --referrers \ + --referrers-src "${SRC_ATT_REPO}" \ + --referrers-tgt "${DEST_REG}/${DEST_CHART_REPO}" \ + --force-recursive +``` + +## Step 4: Create a Kubernetes secret for pulling images + +You need to create a Kubernetes secret for pulling images from Docker Hub or your own registry. This is necessary +because Docker Hardened Images are in private repositories. If you mirror the images to your own registry, you still +need to create this secret if the registry requires authentication. + +1. For Docker Hub, create a [personal access token (PAT)](/security/access-tokens/) using your Docker account or an + [organization access token (OAT)](/enterprise/security/access-tokens/). Ensure the token has at least read-only + access to the Docker Hardened Image repositories. +2. Create a secret in Kubernetes using the following command. Replace ``, ``, + ``, and `` with your own values. + + > [!NOTE] + > + > You need to create this secret in each Kubernetes namespace that uses a DHI. If you've mirror your DHIs to another + > registry, replace `docker.io` with your registry's hostname. Replace ``, ``, and + > `` with your own values. `` is Docker ID if using a PAT or your organization name if + > using an OAT. `` is a name you choose for the secret. + + ```console + $ kubectl create secret docker-registry \ + --docker-server=docker.io \ + --docker-username= \ + --docker-password= \ + --docker-email= + ``` + + For example: + + ```console + $ kubectl create secret docker-registry dhi-pull-secret \ + --docker-server=docker.io \ + --docker-username=docs \ + --docker-password=dckr_pat_12345 \ + --docker-email=moby@example.com + ``` + +## Step 5: Update the image references in the Helm chart + +DHI charts reference images stored in private repositories. While many standard Helm charts use default image locations +that are accessible to everyone, DHI images must first be mirrored to your own Docker Hub namespace or private registry. +Since each organization will have their own unique repository location, the Helm chart must be updated to point to the +correct image locations specific to your organization's Docker Hub namespace or registry. + +To do this, you can either use pre-rendering or post-rendering. Pre-rendering uses a values override file to set the +image references, while post-rendering uses a script to rewrite the image references after Helm has rendered the +templates. + +{{< tabs group="rendering" >}} {{< tab name="Pre-rendering" >}} + +Create a file named `dhi-images.yaml` file with the following: + +```yaml +image: + repository: /dhi-redis +haproxy: + image: + repository: /dhi-haproxy +sysctlImage: + image: + repository: /dhi-busybox +configmapTest: + image: + repository: /dhi-shellcheck +exporter: + image: + repository: /dhi-redis-exporter +``` + +Replace `` with your Docker Hub namespace or with your own namespace in your own registry. + +For example, for the Redis chart: + +```yaml +image: + repository: docs/dhi-redis +haproxy: + image: + repository: docs/dhi-haproxy +sysctlImage: + image: + repository: docs/dhi-busybox +configmapTest: + image: + repository: docs/dhi-shellcheck +exporter: + image: + repository: docs/dhi-redis-exporter +``` + +{{< /tab >}} {{< tab name="Post-rendering" >}} + +Create a script named `post-renderer.sh` using the following command: + +```bash +cat > post-renderer.sh << 'EOF' +#!/usr/bin/env bash +set -euo pipefail + +if [ $# -lt 1 ]; then + echo "Usage: $0 " >&2 + exit 1 +fi + +# Replaces dhi/ or docker.io/dhi with the specified PREFIX +PREFIX="$1" +sed -E "s|(image: )\"?(docker\.io/)?dhi/|\1$PREFIX|g" +EOF +chmod +x post-renderer.sh +``` + +This script will replace all references to `dhi/` or `docker.io/dhi/` with the prefix you provide when running `helm +install`. + +{{< /tab >}} {{< /tabs >}} + +## Step 6: Install the Helm chart + +1. If the chart is in a private repository, log in to the registry using Helm: + + ```console + $ echo "" | helm registry login registry-1.docker.io --username --password-stdin + ``` + + For example: + + ```console + $ echo "dckr_pat_12345" | helm registry login registry-1.docker.io --username docs --password-stdin + ``` + +2. Install the chart using `helm install`. The command differs slightly depending on whether you are using + post-rendering or pre-rendering. Optionally, you can also use the `--dry-run` flag to test the installation without + actually installing anything. + + {{< tabs group="rendering" >}} {{< tab name="Pre-rendering" >}} + + ```console + $ helm install oci://registry-1.docker.io// --version \ + --set "imagePullSecrets[0].name=" \ + -f dhi-images.yaml + ``` + + Replace `` and `` accordingly. If the chart is in your own registry, replace + `registry-1.docker.io/` with your own registry and namespace. Replace `` with the + name of the image pull secret you created earlier. + + For example, for the Redis chart: + + ```console + $ helm install my-redis-ha oci://registry-1.docker.io/docs/dhi-redis-ha-chart --version 0.1.0 \ + --set "imagePullSecrets[0].name=dhi-pull-secret" \ + -f dhi-images.yaml + ``` + + {{< /tab >}} {{< tab name="Post-rendering" >}} + + ```console + $ helm install oci://registry-1.docker.io// --version \ + --set "imagePullSecrets[0].name=" \ + --post-renderer ./post-renderer.sh --post-renderer-args "" + ``` + + Replace `` and `` accordingly. If the chart is in your own registry, replace + `registry-1.docker.io/` with your own registry and namespace. Replace + `` with the registry and repository prefix you want to use for the images, for example, + `gcr.io/my-project/dhi-`, or `your-namespace/` if you are using Docker Hub. Replace `` with the + name of the image pull secret you created earlier. + + For example, for the Redis chart: + + ```console + $ helm install my-redis-ha oci://registry-1.docker.io/docs/dhi-redis-ha-chart --version 0.1.0 \ + --set "imagePullSecrets[0].name=dhi-pull-secret" \ + --post-renderer ./post-renderer.sh --post-renderer-args "docs/" + ``` + + {{< /tab >}} {{< /tabs >}} + +## Step 7: Verify the installation + +After a few seconds all the pods should be up and running. + +```console +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +--server-0 3/3 Running 0 33s +``` + +For example, for the Redis chart: + +```console +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +my-redis-ha-redis-ha-chart-server-0 3/3 Running 0 33s +``` + +## Step 8: Uninstall the Helm chart + +To uninstall the Helm chart, run: + +```console +$ helm uninstall +``` + +For example, for the Redis chart: + +```console +$ helm uninstall my-redis-ha +``` \ No newline at end of file diff --git a/data/summary.yaml b/data/summary.yaml index 191626357e5f..5e40cfe7ce4f 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -170,6 +170,9 @@ Docker GitHub Copilot: availability: Early Access Docker Hardened Images: subscription: [Docker Hardened Images] +Docker Hardened Image charts: + availability: Early Access + subscription: [Docker Hardened Images] Docker Init: requires: Docker Desktop [4.27](/manuals/desktop/release-notes.md#4270) and later Docker Model Runner: From 4eb0bc305b6d359ffc145c47c0071afac2b3100c Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Wed, 29 Oct 2025 07:59:47 -0700 Subject: [PATCH 2/5] lint fixes Signed-off-by: Craig Osterhout --- content/manuals/dhi/features/helm.md | 2 +- content/manuals/dhi/how-to/helm.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/dhi/features/helm.md b/content/manuals/dhi/features/helm.md index 9d939e5a7cb7..7fb784d07a2f 100644 --- a/content/manuals/dhi/features/helm.md +++ b/content/manuals/dhi/features/helm.md @@ -13,7 +13,7 @@ catalog on Docker Hub. Like the hardened images, DHI charts incorporate multiple layers of security metadata to ensure transparency and trust: -- SLSA Level 3 compliance: Each chart is built with our SLSA Build Level 3 system, including a detailed build +- SLSA Level 3 compliance: Each chart is built with Docker's SLSA Build Level 3 system, including a detailed build provenance, and meeting the standards set by the Supply-chain Levels for Software Artifacts (SLSA) framework. - Software Bill of Materials (SBOMs): Comprehensive SBOMs are provided, detailing all components referenced within the chart to facilitate vulnerability management and compliance audits. diff --git a/content/manuals/dhi/how-to/helm.md b/content/manuals/dhi/how-to/helm.md index 090b835630b7..450a619e0dd6 100644 --- a/content/manuals/dhi/how-to/helm.md +++ b/content/manuals/dhi/how-to/helm.md @@ -218,7 +218,7 @@ install`. ## Step 6: Install the Helm chart -1. If the chart is in a private repository, log in to the registry using Helm: +1. If the chart is in a private repository, sign in to the registry using Helm: ```console $ echo "" | helm registry login registry-1.docker.io --username --password-stdin From 10d15dc7517af3389ebd1c967ceb177bee0125c2 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Wed, 29 Oct 2025 08:03:17 -0700 Subject: [PATCH 3/5] fix link Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/helm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/dhi/how-to/helm.md b/content/manuals/dhi/how-to/helm.md index 450a619e0dd6..9da11cc46d5d 100644 --- a/content/manuals/dhi/how-to/helm.md +++ b/content/manuals/dhi/how-to/helm.md @@ -64,7 +64,7 @@ To find a Docker Helm chart for DHI: You must mirror the Docker Helm chart to your own repository before using it. To mirror the Docker Helm chart to your organization, in the Helm chart repository details page you opened in [step -1](#step-1-find-the-docker-helm-chart): +1](#step-1-find-a-docker-helm-chart-and-request-access): 1. Select **Mirror Helm chart**. 2. Follow the on-screen instructions to mirror the Helm chart. For this guide, name the destination repository From 3ff2c612bee78f9657e924de7408128b3132ea4c Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Wed, 29 Oct 2025 09:04:32 -0700 Subject: [PATCH 4/5] feedback Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/helm.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/content/manuals/dhi/how-to/helm.md b/content/manuals/dhi/how-to/helm.md index 9da11cc46d5d..d05620627458 100644 --- a/content/manuals/dhi/how-to/helm.md +++ b/content/manuals/dhi/how-to/helm.md @@ -8,7 +8,7 @@ params: sidebar: badge: color: violet - text: EA + text: Early Access --- {{< summary-bar feature_name="Docker Hardened Image charts" >}} @@ -144,9 +144,12 @@ that are accessible to everyone, DHI images must first be mirrored to your own D Since each organization will have their own unique repository location, the Helm chart must be updated to point to the correct image locations specific to your organization's Docker Hub namespace or registry. -To do this, you can either use pre-rendering or post-rendering. Pre-rendering uses a values override file to set the -image references, while post-rendering uses a script to rewrite the image references after Helm has rendered the -templates. +To do this, you can use one of the following approaches: + +- Pre-rendering: Uses a values override file to set the image references before Helm renders the chart templates. +- Post-rendering: Uses a script that automatically rewrites image references after Helm renders the templates but + before deploying to Kubernetes. The script is invoked by Helm during the `helm install` command using the + `--post-renderer` flag, where you pass it the new image prefix as an argument. {{< tabs group="rendering" >}} {{< tab name="Pre-rendering" >}} From db23b86f92a3a901ae5bdbb849f28cd895e5c17b Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Wed, 29 Oct 2025 10:25:10 -0700 Subject: [PATCH 5/5] update UI wording Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/helm.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/manuals/dhi/how-to/helm.md b/content/manuals/dhi/how-to/helm.md index d05620627458..d764fc7f3b53 100644 --- a/content/manuals/dhi/how-to/helm.md +++ b/content/manuals/dhi/how-to/helm.md @@ -53,11 +53,11 @@ To find a Docker Helm chart for DHI: You will see the **Overview** page with details about the chart. -6. If visible, select **Request access**. +6. If visible, select **Request access to Helm charts**. - Before you can mirror the chart, you may need to request access for the Early Access program. If **Request access** - is visible on the Helm chart repository details page, select it and wait for an email notifying you that the access - has been granted by Docker. + Before you can mirror the chart, you may need to request access for the Early Access program. If **Request access to + Helm charts** is visible on the Helm chart repository details page, select it and wait for an email notifying you + that the access has been granted by Docker. ## Step 2: Mirror the Docker Helm chart