|
| 1 | +--- |
| 2 | +title: Use a Docker Hardened Image chart |
| 3 | +linktitle: Use a Helm chart |
| 4 | +description: Learn how to use a Docker Hardened Image chart. |
| 5 | +keywords: use hardened image, helm, k8s, kubernetes, dhi chart, chart |
| 6 | +weight: 36 |
| 7 | +params: |
| 8 | + sidebar: |
| 9 | + badge: |
| 10 | + color: violet |
| 11 | + text: Early Access |
| 12 | +--- |
| 13 | + |
| 14 | +{{< summary-bar feature_name="Docker Hardened Image charts" >}} |
| 15 | + |
| 16 | +Docker Hardened Image (DHI) charts are Docker-provided [Helm charts](https://helm.sh/docs/) built from upstream and |
| 17 | +community-maintained sources, designed for compatibility with Docker Hardened Images. These charts are available as OCI |
| 18 | +artifacts within the DHI catalog on Docker Hub. For more details, see [Docker Hardened Image |
| 19 | +charts](/dhi/features/helm/). |
| 20 | + |
| 21 | +DHI charts incorporate multiple layers of supply chain security that aren't present in upstream charts: |
| 22 | + |
| 23 | +- SLSA Level 3 compliance: Each chart is built with SLSA Build Level 3 standards, including detailed build provenance |
| 24 | +- Software Bill of Materials (SBOMs): Comprehensive SBOMs detail all components referenced within the chart |
| 25 | +- Cryptographic signing: All associated metadata is cryptographically signed by Docker for integrity and authenticity |
| 26 | +- Hardened configuration: Charts automatically reference Docker Hardened Images for secure deployments |
| 27 | +- Tested compatibility: Charts are robustly tested to work out-of-the-box with Docker Hardened Images |
| 28 | + |
| 29 | +This guide walks you through how to use the DHI Redis chart. You can adapt the steps to other DHI charts and your own |
| 30 | +Kubernetes workflows. DHI charts work like any other Helm chart, but you must mirror them to your own repository before |
| 31 | +using them. |
| 32 | + |
| 33 | +## Prerequisites |
| 34 | + |
| 35 | +To follow along with this guide, you need: |
| 36 | + |
| 37 | +- A Kubernetes cluster set up and [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) installed. To |
| 38 | + test locally, you can use Docker Desktop with Kubernetes enabled. For more information, see [Install Docker |
| 39 | + Desktop](/desktop/install/windows-install/) and [Enable Kubernetes](/desktop/features/kubernetes/). |
| 40 | +- Helm installed. For more information, see the [Helm installation guide](https://helm.sh/docs/intro/install/). |
| 41 | +- Access to DHI. For more information about starting a free trial, see [Get started with Docker Hardened |
| 42 | + Images](/dhi/get-started/). |
| 43 | + |
| 44 | +## Step 1: Find a Docker Helm chart and request access |
| 45 | + |
| 46 | +To find a Docker Helm chart for DHI: |
| 47 | + |
| 48 | +1. Go to the Hardened Images catalog in [Docker Hub](https://hub.docker.com/hardened-images/catalog) and sign in. |
| 49 | +2. In the left sidebar, select your organization that has DHI access. |
| 50 | +3. In the left sidebar, select **Hardened Images** > **Catalog**. |
| 51 | +4. In the search bar, search for a Helm chart. For this guide, search for `redis chart`. |
| 52 | +5. Select the Helm chart to view its details. For this guide, select the **Redis HA Helm Chart**. |
| 53 | + |
| 54 | + You will see the **Overview** page with details about the chart. |
| 55 | + |
| 56 | +6. If visible, select **Request access to Helm charts**. |
| 57 | + |
| 58 | + Before you can mirror the chart, you may need to request access for the Early Access program. If **Request access to |
| 59 | + Helm charts** is visible on the Helm chart repository details page, select it and wait for an email notifying you |
| 60 | + that the access has been granted by Docker. |
| 61 | + |
| 62 | +## Step 2: Mirror the Docker Helm chart |
| 63 | + |
| 64 | +You must mirror the Docker Helm chart to your own repository before using it. |
| 65 | + |
| 66 | +To mirror the Docker Helm chart to your organization, in the Helm chart repository details page you opened in [step |
| 67 | +1](#step-1-find-a-docker-helm-chart-and-request-access): |
| 68 | + |
| 69 | +1. Select **Mirror Helm chart**. |
| 70 | +2. Follow the on-screen instructions to mirror the Helm chart. For this guide, name the destination repository |
| 71 | + `dhi-redis-ha-chart`. |
| 72 | + |
| 73 | + When complete, you will see the details page for the mirrored Helm chart in your organization's namespace. On this |
| 74 | + page, you can verify that the necessary dependencies have also been mirrored. |
| 75 | + |
| 76 | +3. If any dependencies are not mirrored, mirror them now. For this guide, select **Mirror image** if necessary for the |
| 77 | + Redis image, then follow the on-screen instructions. |
| 78 | + |
| 79 | +You only need to mirror the Helm chart and its dependencies once. After they are mirrored, you can use them in any |
| 80 | +Kubernetes cluster that can access your organization's namespace. |
| 81 | + |
| 82 | +## Step 3: Optional. Mirror the Helm chart and/or its images to your own registry |
| 83 | + |
| 84 | +By default, when you mirror a chart or image from the Docker Hardened Images catalog, the chart or image is mirrored to |
| 85 | +your namespace in Docker Hub. If you want to then mirror to your own third-party registry, you can follow the |
| 86 | +instructions in [How to mirror an image](/dhi/how-to/mirror/) for either the chart, the image, or both. |
| 87 | + |
| 88 | +The same `regctl` tool that is used for mirroring container images can also be used for mirroring Helm charts, as Helm |
| 89 | +charts are OCI artifacts. |
| 90 | + |
| 91 | +For example: |
| 92 | + |
| 93 | +```console |
| 94 | +regctl image copy \ |
| 95 | + "${SRC_CHART_REPO}:${TAG}" \ |
| 96 | + "${DEST_REG}/${DEST_CHART_REPO}:${TAG}" \ |
| 97 | + --referrers \ |
| 98 | + --referrers-src "${SRC_ATT_REPO}" \ |
| 99 | + --referrers-tgt "${DEST_REG}/${DEST_CHART_REPO}" \ |
| 100 | + --force-recursive |
| 101 | +``` |
| 102 | + |
| 103 | +## Step 4: Create a Kubernetes secret for pulling images |
| 104 | + |
| 105 | +You need to create a Kubernetes secret for pulling images from Docker Hub or your own registry. This is necessary |
| 106 | +because Docker Hardened Images are in private repositories. If you mirror the images to your own registry, you still |
| 107 | +need to create this secret if the registry requires authentication. |
| 108 | + |
| 109 | +1. For Docker Hub, create a [personal access token (PAT)](/security/access-tokens/) using your Docker account or an |
| 110 | + [organization access token (OAT)](/enterprise/security/access-tokens/). Ensure the token has at least read-only |
| 111 | + access to the Docker Hardened Image repositories. |
| 112 | +2. Create a secret in Kubernetes using the following command. Replace `<your-secret-name>`, `<your-username>`, |
| 113 | + `<your-personal-access-token>`, and `<your-email>` with your own values. |
| 114 | + |
| 115 | + > [!NOTE] |
| 116 | + > |
| 117 | + > You need to create this secret in each Kubernetes namespace that uses a DHI. If you've mirror your DHIs to another |
| 118 | + > registry, replace `docker.io` with your registry's hostname. Replace `<your-username>`, `<your-access-token>`, and |
| 119 | + > `<your-email>` with your own values. `<your-username>` is Docker ID if using a PAT or your organization name if |
| 120 | + > using an OAT. `<your-secret-name>` is a name you choose for the secret. |
| 121 | +
|
| 122 | + ```console |
| 123 | + $ kubectl create secret docker-registry <your-secret-name> \ |
| 124 | + --docker-server=docker.io \ |
| 125 | + --docker-username=<your-username> \ |
| 126 | + --docker-password=<your-access-token> \ |
| 127 | + --docker-email=<your-email> |
| 128 | + ``` |
| 129 | + |
| 130 | + For example: |
| 131 | + |
| 132 | + ```console |
| 133 | + $ kubectl create secret docker-registry dhi-pull-secret \ |
| 134 | + --docker-server=docker.io \ |
| 135 | + --docker-username=docs \ |
| 136 | + --docker-password=dckr_pat_12345 \ |
| 137 | + |
| 138 | + ``` |
| 139 | + |
| 140 | +## Step 5: Update the image references in the Helm chart |
| 141 | + |
| 142 | +DHI charts reference images stored in private repositories. While many standard Helm charts use default image locations |
| 143 | +that are accessible to everyone, DHI images must first be mirrored to your own Docker Hub namespace or private registry. |
| 144 | +Since each organization will have their own unique repository location, the Helm chart must be updated to point to the |
| 145 | +correct image locations specific to your organization's Docker Hub namespace or registry. |
| 146 | + |
| 147 | +To do this, you can use one of the following approaches: |
| 148 | + |
| 149 | +- Pre-rendering: Uses a values override file to set the image references before Helm renders the chart templates. |
| 150 | +- Post-rendering: Uses a script that automatically rewrites image references after Helm renders the templates but |
| 151 | + before deploying to Kubernetes. The script is invoked by Helm during the `helm install` command using the |
| 152 | + `--post-renderer` flag, where you pass it the new image prefix as an argument. |
| 153 | + |
| 154 | +{{< tabs group="rendering" >}} {{< tab name="Pre-rendering" >}} |
| 155 | + |
| 156 | +Create a file named `dhi-images.yaml` file with the following: |
| 157 | + |
| 158 | +```yaml |
| 159 | +image: |
| 160 | + repository: <your-namespace>/dhi-redis |
| 161 | +haproxy: |
| 162 | + image: |
| 163 | + repository: <your-namespace>/dhi-haproxy |
| 164 | +sysctlImage: |
| 165 | + image: |
| 166 | + repository: <your-namespace>/dhi-busybox |
| 167 | +configmapTest: |
| 168 | + image: |
| 169 | + repository: <your-namespace>/dhi-shellcheck |
| 170 | +exporter: |
| 171 | + image: |
| 172 | + repository: <your-namespace>/dhi-redis-exporter |
| 173 | +``` |
| 174 | +
|
| 175 | +Replace `<your-namespace>` with your Docker Hub namespace or with your own namespace in your own registry. |
| 176 | + |
| 177 | +For example, for the Redis chart: |
| 178 | + |
| 179 | +```yaml |
| 180 | +image: |
| 181 | + repository: docs/dhi-redis |
| 182 | +haproxy: |
| 183 | + image: |
| 184 | + repository: docs/dhi-haproxy |
| 185 | +sysctlImage: |
| 186 | + image: |
| 187 | + repository: docs/dhi-busybox |
| 188 | +configmapTest: |
| 189 | + image: |
| 190 | + repository: docs/dhi-shellcheck |
| 191 | +exporter: |
| 192 | + image: |
| 193 | + repository: docs/dhi-redis-exporter |
| 194 | +``` |
| 195 | + |
| 196 | +{{< /tab >}} {{< tab name="Post-rendering" >}} |
| 197 | + |
| 198 | +Create a script named `post-renderer.sh` using the following command: |
| 199 | + |
| 200 | +```bash |
| 201 | +cat > post-renderer.sh << 'EOF' |
| 202 | +#!/usr/bin/env bash |
| 203 | +set -euo pipefail |
| 204 | +
|
| 205 | +if [ $# -lt 1 ]; then |
| 206 | + echo "Usage: $0 <new-prefix>" >&2 |
| 207 | + exit 1 |
| 208 | +fi |
| 209 | +
|
| 210 | +# Replaces dhi/ or docker.io/dhi with the specified PREFIX |
| 211 | +PREFIX="$1" |
| 212 | +sed -E "s|(image: )\"?(docker\.io/)?dhi/|\1$PREFIX|g" |
| 213 | +EOF |
| 214 | +chmod +x post-renderer.sh |
| 215 | +``` |
| 216 | + |
| 217 | +This script will replace all references to `dhi/` or `docker.io/dhi/` with the prefix you provide when running `helm |
| 218 | +install`. |
| 219 | + |
| 220 | +{{< /tab >}} {{< /tabs >}} |
| 221 | + |
| 222 | +## Step 6: Install the Helm chart |
| 223 | + |
| 224 | +1. If the chart is in a private repository, sign in to the registry using Helm: |
| 225 | + |
| 226 | + ```console |
| 227 | + $ echo "<your-access-token>" | helm registry login registry-1.docker.io --username <your-username> --password-stdin |
| 228 | + ``` |
| 229 | + |
| 230 | + For example: |
| 231 | + |
| 232 | + ```console |
| 233 | + $ echo "dckr_pat_12345" | helm registry login registry-1.docker.io --username docs --password-stdin |
| 234 | + ``` |
| 235 | + |
| 236 | +2. Install the chart using `helm install`. The command differs slightly depending on whether you are using |
| 237 | + post-rendering or pre-rendering. Optionally, you can also use the `--dry-run` flag to test the installation without |
| 238 | + actually installing anything. |
| 239 | + |
| 240 | + {{< tabs group="rendering" >}} {{< tab name="Pre-rendering" >}} |
| 241 | + |
| 242 | + ```console |
| 243 | + $ helm install <release-name> oci://registry-1.docker.io/<your-namespace>/<helm-chart-repository> --version <chart-version> \ |
| 244 | + --set "imagePullSecrets[0].name=<your-secret-name>" \ |
| 245 | + -f dhi-images.yaml |
| 246 | + ``` |
| 247 | + |
| 248 | + Replace `<your-namespace>` and `<chart-version>` accordingly. If the chart is in your own registry, replace |
| 249 | + `registry-1.docker.io/<your-namespace>` with your own registry and namespace. Replace `<your-secret-name>` with the |
| 250 | + name of the image pull secret you created earlier. |
| 251 | + |
| 252 | + For example, for the Redis chart: |
| 253 | + |
| 254 | + ```console |
| 255 | + $ helm install my-redis-ha oci://registry-1.docker.io/docs/dhi-redis-ha-chart --version 0.1.0 \ |
| 256 | + --set "imagePullSecrets[0].name=dhi-pull-secret" \ |
| 257 | + -f dhi-images.yaml |
| 258 | + ``` |
| 259 | + |
| 260 | + {{< /tab >}} {{< tab name="Post-rendering" >}} |
| 261 | + |
| 262 | + ```console |
| 263 | + $ helm install <release-name> oci://registry-1.docker.io/<your-namespace>/<helm-chart-repository> --version <chart-version> \ |
| 264 | + --set "imagePullSecrets[0].name=<your-secret-name>" \ |
| 265 | + --post-renderer ./post-renderer.sh --post-renderer-args "<your-registry-and-repository>" |
| 266 | + ``` |
| 267 | + |
| 268 | + Replace `<your-namespace>` and `<chart-version>` accordingly. If the chart is in your own registry, replace |
| 269 | + `registry-1.docker.io/<your-namespace>` with your own registry and namespace. Replace |
| 270 | + `<your-registry-and-repository>` with the registry and repository prefix you want to use for the images, for example, |
| 271 | + `gcr.io/my-project/dhi-`, or `your-namespace/` if you are using Docker Hub. Replace `<your-secret-name>` with the |
| 272 | + name of the image pull secret you created earlier. |
| 273 | + |
| 274 | + For example, for the Redis chart: |
| 275 | + |
| 276 | + ```console |
| 277 | + $ helm install my-redis-ha oci://registry-1.docker.io/docs/dhi-redis-ha-chart --version 0.1.0 \ |
| 278 | + --set "imagePullSecrets[0].name=dhi-pull-secret" \ |
| 279 | + --post-renderer ./post-renderer.sh --post-renderer-args "docs/" |
| 280 | + ``` |
| 281 | + |
| 282 | + {{< /tab >}} {{< /tabs >}} |
| 283 | + |
| 284 | +## Step 7: Verify the installation |
| 285 | + |
| 286 | +After a few seconds all the pods should be up and running. |
| 287 | + |
| 288 | +```console |
| 289 | +$ kubectl get pods |
| 290 | +NAME READY STATUS RESTARTS AGE |
| 291 | +<release-name>-<chart-name>-server-0 3/3 Running 0 33s |
| 292 | +``` |
| 293 | + |
| 294 | +For example, for the Redis chart: |
| 295 | + |
| 296 | +```console |
| 297 | +$ kubectl get pods |
| 298 | +NAME READY STATUS RESTARTS AGE |
| 299 | +my-redis-ha-redis-ha-chart-server-0 3/3 Running 0 33s |
| 300 | +``` |
| 301 | + |
| 302 | +## Step 8: Uninstall the Helm chart |
| 303 | + |
| 304 | +To uninstall the Helm chart, run: |
| 305 | + |
| 306 | +```console |
| 307 | +$ helm uninstall <release-name> |
| 308 | +``` |
| 309 | + |
| 310 | +For example, for the Redis chart: |
| 311 | + |
| 312 | +```console |
| 313 | +$ helm uninstall my-redis-ha |
| 314 | +``` |
0 commit comments