diff --git a/content/manuals/dhi/get-started.md b/content/manuals/dhi/get-started.md index 27e73da2f85..23e29a8e19d 100644 --- a/content/manuals/dhi/get-started.md +++ b/content/manuals/dhi/get-started.md @@ -74,7 +74,6 @@ a simple Python command just like you would with any other Docker image: To dive deeper into using images, see: - [Use a Docker Hardened Image](./how-to/use.md) for general usage -- [Use in Kubernetes](./how-to/k8s.md) for Kubernetes deployments - [Use a Helm chart](./how-to/helm.md) for deploying with Helm ## Step 3: Compare with other images diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md index ee04a6de5bc..1d6f98d5ba4 100644 --- a/content/manuals/dhi/how-to/_index.md +++ b/content/manuals/dhi/how-to/_index.md @@ -33,18 +33,10 @@ params: description: Learn how to pull, run, and reference Docker Hardened Images in Dockerfiles, CI pipelines, and standard development workflows. icon: play_arrow link: /dhi/how-to/use/ - - title: Use a Docker Hardened Image in Kubernetes - 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: Use Extended Lifecycle Support for Docker Hardened Images - description: Learn how to use Extended Lifecycle Support with Docker Hardened Images. - icon: update - link: /dhi/how-to/els/ - title: Manage Docker Hardened Images and charts 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/els.md b/content/manuals/dhi/how-to/els.md deleted file mode 100644 index 930920b8a98..00000000000 --- a/content/manuals/dhi/how-to/els.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Use Extended Lifecycle Support for Docker Hardened Images -linktitle: Use Extended Lifecycle Support -description: Learn how to use Extended Lifecycle Support with Docker Hardened Images. -weight: 39 -keywords: extended lifecycle support, docker hardened images, container security, image lifecycle, vulnerability management ---- - -{{< summary-bar feature_name="Docker Hardened Images" >}} - -With a Docker Hardened Images subscription add-on, you can use Extended -Lifecycle Support (ELS) for Docker Hardened Images. ELS provides security -patches for end-of-life (EOL) image versions, letting you maintain secure, -compliant operations while planning upgrades on your own timeline. You can use -ELS images like any other Docker Hardened Image, but you must enable ELS for -each repository you want to use with ELS. - -## Discover repositories with ELS support - -To find images with ELS support: - -1. Go to [Docker Hub](https://hub.docker.com) and sign in. -2. Select **My Hub**. -3. In the namespace drop-down, select your organization. -4. Select **Hardened Images** > **Catalog**. -5. In **Filter by**, select **Extended Lifecycle Support**. - -## Enable ELS for a repository - -To enable ELS for a repository, an organization owner must [mirror](./mirror.md) -the repository to your organization. - -To enable ELS when mirroring: - -1. Go to [Docker Hub](https://hub.docker.com) and sign in. -2. Select **My Hub**. -3. In the namespace drop-down, select your organization. -4. Select **Hardened Images** > **Catalog**. -5. Select a DHI repository to view its details. -6. Select **Use this image** > **Mirror repository** -7. Select **Enable support for end-of-life versions** and then follow the - on-screen instructions. - -## Disable ELS for a repository - -To disable ELS for a repository, you must uncheck the ELS option in the mirrored -repository's **Settings** tab, or stop mirroring the repository. To stop mirroring, see -[Stop mirroring a repository](./mirror.md#stop-mirroring-a-repository). - -To update settings: - -1. Go to [Docker Hub](https://hub.docker.com) and sign in. -2. Select **My Hub**. -3. In the namespace drop-down, select your organization. -4. Select **Repositories** and then select the mirrored repository. -5. Select the **Settings** tab. -6. Uncheck the **Mirror end-of-life images** option. - -## Manage ELS repositories - -You can view and manage your mirrored repositories with ELS like any other -mirrored DHI repository. For more details, see [Manage images](./manage.md). \ No newline at end of file diff --git a/content/manuals/dhi/how-to/hardened-packages.md b/content/manuals/dhi/how-to/hardened-packages.md index c2251bb2d01..b15d50cb4de 100644 --- a/content/manuals/dhi/how-to/hardened-packages.md +++ b/content/manuals/dhi/how-to/hardened-packages.md @@ -1,7 +1,7 @@ --- title: Use Hardened System Packages linkTitle: Use hardened packages -weight: 30 +weight: 32 keywords: hardened images, DHI, hardened packages, packages, alpine description: Learn how to use and verify Docker's hardened system packages in your images. --- diff --git a/content/manuals/dhi/how-to/helm.md b/content/manuals/dhi/how-to/helm.md index ddf16e60b2a..6fac70ba5d1 100644 --- a/content/manuals/dhi/how-to/helm.md +++ b/content/manuals/dhi/how-to/helm.md @@ -3,7 +3,7 @@ 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: 32 +weight: 31 --- Docker Hardened Image (DHI) charts are Docker-provided [Helm diff --git a/content/manuals/dhi/how-to/k8s.md b/content/manuals/dhi/how-to/k8s.md deleted file mode 100644 index c033a34d581..00000000000 --- a/content/manuals/dhi/how-to/k8s.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Use a Docker Hardened Image in Kubernetes -linktitle: Use an image in Kubernetes -description: Learn how to use Docker Hardened Images in Kubernetes deployments. -keywords: use hardened image, kubernetes, k8s -weight: 31 ---- - -## Authentication - -To be able to use Docker Hardened Images in Kubernetes, you need to create a -Kubernetes secret for pulling images from your mirror or internal registry. - -> [!NOTE] -> -> You need to create this secret in each Kubernetes namespace that uses a DHI. - -Create a secret using a Personal Access Token (PAT). Ensure the token has at -least read-only access to public repositories. For Docker Hardened Images -replace `` with `dhi.io`. If you are using a mirrored -repository, replace it with your mirror's registry server, such as `docker.io` -for Docker Hub. - -```console -$ kubectl create -n secret docker-registry --docker-server= \ - --docker-username= --docker-password= \ - --docker-email= -``` - -To tests the secrets use the following command: - -```console -kubectl apply --wait -f - < -spec: - containers: - - name: test - image: bash:5 - command: [ "sh", "-c", "echo 'Hello from DHI in Kubernetes!'" ] - imagePullSecrets: - - name: -EOF -``` - -Get the status of the pod by running: - -```console -$ kubectl get -n pods/dhi-test -``` - -The command should return the following result: - -```console -NAME READY STATUS RESTARTS AGE -dhi-test 0/1 Completed ... ... -``` - -If instead, the result is the following, there might be an issue with your secret. - -```console -NAME READY STATUS RESTARTS AGE -dhi-test 0/1 ErrImagePull 0 ... -``` - -Verify the output of the pod by running, which should return `Hello from DHI in Kubernetes!` - -```console -kubectl logs -n pods/dhi-test -``` - -After a successful test, the test pod can be deleted with the following command: - -```console -$ kubectl delete -n pods/dhi-test -``` diff --git a/content/manuals/dhi/how-to/mirror.md b/content/manuals/dhi/how-to/mirror.md index c233ab3d431..c94ae827794 100644 --- a/content/manuals/dhi/how-to/mirror.md +++ b/content/manuals/dhi/how-to/mirror.md @@ -154,9 +154,8 @@ repository. > [!NOTE] > -> If you only want to stop mirroring ELS versions, you can clear the ELS -> option in the mirrored repository's **Settings** tab. For more details, see -> [Disable ELS for a repository](./els.md#disable-els-for-a-repository). +> If you only want to stop mirroring ELS versions, clear the **Mirror +> end-of-life images** option in the mirrored repository's **Settings** tab. To stop mirroring a repository: diff --git a/content/manuals/dhi/how-to/select-enterprise.md b/content/manuals/dhi/how-to/select-enterprise.md index ab31d689f28..645aff470be 100644 --- a/content/manuals/dhi/how-to/select-enterprise.md +++ b/content/manuals/dhi/how-to/select-enterprise.md @@ -231,7 +231,6 @@ image from your organization namespace on Docker Hub. To dive deeper into using images, see: - [Use a Docker Hardened Image](use.md) for general usage -- [Use in Kubernetes](k8s.md) for Kubernetes deployments - [Use a Helm chart](helm.md) for deploying with Helm ## Step 5: Remove customization and stop mirroring diff --git a/content/manuals/dhi/how-to/use.md b/content/manuals/dhi/how-to/use.md index c1b35b13b7a..d3ed93c0556 100644 --- a/content/manuals/dhi/how-to/use.md +++ b/content/manuals/dhi/how-to/use.md @@ -4,6 +4,9 @@ linktitle: Use an image description: Learn how to pull, run, and reference Docker Hardened Images in Dockerfiles, CI pipelines, and standard development workflows. keywords: use hardened image, docker pull secure image, non-root containers, multi-stage dockerfile, dev image variant weight: 30 +aliases: + - /dhi/how-to/els/ + - /dhi/how-to/k8s/ --- You can use a Docker Hardened Image (DHI) just like any other image on Docker @@ -17,131 +20,68 @@ package manager, and may run as a non-root user by default. > [!IMPORTANT] > > You must authenticate to the Docker Hardened Images registry (`dhi.io`) to -> pull images. You can authenticate using either of the following: +> pull DHI Community images. You can authenticate using either of the following: > -> - **Docker ID (personal credentials):** Use the same username and password -> you use for Docker Hub. If you don't have a Docker account, -> [create one](../../accounts/create-account.md) for free. -> - **Organization access token (OAT):** Use your organization name as the -> username and an OAT as the password. OATs are recommended for CI/CD -> pipelines and automated workflows. See -> [Organization access tokens](../../enterprise/security/access-tokens.md). +> - **Docker ID and password:** Use your Docker Hub username and password. If +> you don't have a Docker account, [create one](../../accounts/create-account.md) +> for free. +> - **Access token:** Use a [personal access token +> (PAT)](../../security/access-tokens.md) for personal accounts, or an +> [organization access token +> (OAT)](../../enterprise/security/access-tokens.md) with your organization +> name as the username. > > Run `docker login dhi.io` to authenticate. ## Considerations when adopting DHIs -Docker Hardened Images are intentionally minimal to improve security. If you're updating existing Dockerfiles or frameworks to use DHIs, keep the considerations in mind: +Docker Hardened Images are intentionally minimal to improve security. If you're +updating existing Dockerfiles or frameworks to use DHIs, keep in mind that +runtime images don't include shells or package managers, run as non-root users +by default, and may have different configurations than images you're familiar +with. -| Feature | Details | -|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| No shell or package manager | Runtime images don’t include a shell or package manager. Use `-dev` or `-sdk` variants in build stages to run shell commands or install packages, and then copy artifacts to a minimal runtime image. | -| Non-root runtime | Runtime DHIs default to running as a non-root user. Ensure your application doesn't require privileged access and that all needed files are readable and executable by a non-root user. | -| Ports | Applications running as non-root users can't bind to ports lower than 1024 in older versions of Docker or in some Kubernetes configurations. Use ports higher than 1024 for compatibility. | -| Entry point | DHIs may not include a default entrypoint or might use a different one than the original image you're familiar with. Check the image configuration and update your `CMD` or `ENTRYPOINT` directives accordingly. | -| Multi-stage builds | Always use multi-stage builds for frameworks: a `-dev` image for building or installing dependencies, and a minimal runtime image for the final stage. | -| TLS certificates | DHIs include standard TLS certificates. You do not need to manually install CA certs. | +For a comprehensive checklist of migration considerations and detailed guidance, +see [Migrate to Docker Hardened Images](../migration/_index.md). -If you're migrating an existing application, see [Migrate an existing application to use Docker Hardened Images](../migration/_index.md). +## Pull, run, and reference DHIs -## Use a DHI in a Dockerfile +Docker Hardened Images use different image references depending on your +subscription: -To use a DHI as the base image for your container, specify it in the `FROM` instruction in your Dockerfile: +| Subscription | Image reference | Authentication | +|---------------------|----------------------------|-----------------------| +| Community | `dhi.io/:` | `docker login dhi.io` | +| Select & Enterprise | `/:` | `docker login` | -```dockerfile -FROM dhi.io/: -``` - -Replace the image name and tag with the variant you want to use. For example, -use a `-dev` tag if you need a shell or package manager during build stages: - -```dockerfile -FROM dhi.io/python:3.13-dev AS build -``` - -To learn how to search for available variants, see [Search and evaluate images](./explore.md). - -> [!TIP] -> -> Use a multi-stage Dockerfile to separate build and runtime stages, using a -> `-dev` variant in build stages and a minimal runtime image in the final stage. - -## Pull a DHI +Select and Enterprise users should [mirror](./mirror.md) repositories to their +Docker Hub organization to access compliance variants and customization +features. -Just like any other image, you can pull DHIs using tools such as -the Docker CLI or within your CI pipelines. - -You can pull Docker Hardened Images from three different locations depending on your needs: - -- Directly from `dhi.io` -- From a mirror on Docker Hub -- From a mirror on a third-party registry - -To understand which approach is right for your use case, see [Mirror a Docker Hardened Image repository](./mirror.md). - -The following sections show how to pull images from each location. - -### Pull directly from dhi.io - -After authenticating to `dhi.io`, you can pull images using standard Docker commands: +After authenticating, use the image reference in standard Docker commands and +Dockerfiles. For example: ```console -$ docker login dhi.io $ docker pull dhi.io/python:3.13 +$ docker run --rm dhi.io/python:3.13 python -c "print('Hello from DHI')" ``` -Reference images in your Dockerfile: - ```dockerfile FROM dhi.io/python:3.13 COPY . /app CMD ["python", "/app/main.py"] ``` -### Pull from a mirror on Docker Hub - -Once you've mirrored a repository to Docker Hub, you can pull images from your organization's namespace: - -```console -$ docker login -$ docker pull /dhi-python:3.13 -``` - -Reference mirrored images in your Dockerfile: - -```dockerfile -FROM /dhi-python:3.13 -COPY . /app -CMD ["python", "/app/main.py"] -``` - -To learn how to mirror repositories, see [Mirror a DHI repository to Docker Hub](./mirror.md#mirror-a-dhi-repository-to-docker-hub). +For multi-stage builds: +- Use a `-dev` tag for build stages that need a shell or package manager. See + [Use dev variants for framework-based + applications](#use-dev-variants-for-framework-based-applications). +- Use the `static` image for compiled executables with minimal runtime + dependencies. See [Use a static image for compiled + executables](#use-a-static-image-for-compiled-executables). -### Pull from a mirror on a third-party registry - -Once you've mirrored a repository to your third-party registry, you can pull images: - -```console -$ docker pull //python:3.13 -``` - -Reference third-party mirrored images in your Dockerfile: - -```dockerfile -FROM //python:3.13 -COPY . /app -CMD ["python", "/app/main.py"] -``` - -To learn more, see [Mirror to a third-party registry](./mirror.md#mirror-to-a-third-party-registry). - -## Run a DHI - -After pulling the image, you can run it using `docker run`. For example: - -```console -$ docker run --rm dhi.io/python:3.13 python -c "print('Hello from DHI')" -``` +To learn how to search for available variants, see [Search and evaluate +images](./explore.md). ## Use a DHI in CI/CD pipelines @@ -155,9 +95,9 @@ metadata. You can incorporate these into your pipeline to support supply chain security, policy checks, or audit requirements if your tooling supports it. To strengthen your software supply chain, consider adding your own attestations -when building images from DHIs. This lets you document how the image was -built, verify its integrity, and enable downstream validation and policy -enforcement using tools like Docker Scout. +when building images from DHIs. This lets you document how the image was built, +verify its integrity, and enable downstream validation and policy enforcement +using tools like Docker Scout. To learn how to attach attestations during the build process, see [Docker Build Attestations](/manuals/build/metadata/attestations.md). @@ -166,21 +106,13 @@ Attestations](/manuals/build/metadata/attestations.md). Docker Hardened Images include a `static` image repository designed specifically for running compiled executables in an extremely minimal and secure runtime. +Unlike a non-hardened `FROM scratch` image, the DHI `static` image includes +attestations and essential packages like `ca-certificates`. -Unlike a non-hardened `FROM scratch` image, the DHI `static` image includes all -the attestations needed to verify its integrity and provenance. Although it is -minimal, it includes the common packages needed to run containers securely, such -as `ca-certificates`. - -Use a `-dev` or other builder image in an earlier stage to compile your binary, -and copy the output into a `static` image. - -The following example shows a multi-stage Dockerfile that builds a Go application -and runs it in a minimal static image: +Use a `-dev` or other builder image to compile your binary, then copy the output +into a `static` image: ```dockerfile -#syntax=docker/dockerfile:1 - FROM dhi.io/golang:1.22-dev AS build WORKDIR /app COPY . . @@ -191,8 +123,8 @@ COPY --from=build /app/myapp /myapp ENTRYPOINT ["/myapp"] ``` -This pattern ensures a hardened runtime environment with no unnecessary -components, reducing the attack surface to a bare minimum. +For more multi-stage build patterns, see the [Go migration +example](../migration/examples/go.md). ## Use dev variants for framework-based applications @@ -206,55 +138,108 @@ Use `-dev` images in your inner development loop or in isolated CI stages to maximize productivity. Once you're ready to produce artifacts for production, switch to a smaller runtime variant to reduce the attack surface and image size. -Dev variants are typically configured with no `ENTRYPOINT` and a default `CMD` that -launches a shell (for example, ["/bin/bash"]). In those cases, running the -container without additional arguments starts an interactive shell by default. +For detailed multi-stage Dockerfile examples using dev variants, see the +migration examples: +- [Go](../migration/examples/go.md) +- [Python](../migration/examples/python.md) +- [Node.js](../migration/examples/node.md) -The following example shows how to build a Python app using a `-dev` variant and -run it using the smaller runtime variant: +## Use compliance and ELS variants {tier="DHI Select & Enterprise"} -```dockerfile -#syntax=docker/dockerfile:1 +{{< summary-bar feature_name="Docker Hardened Images" >}} -FROM dhi.io/python:3.13-alpine3.21-dev AS builder +With a DHI Select or DHI Enterprise subscription, you can access additional +image variants: -ENV LANG=C.UTF-8 -ENV PYTHONDONTWRITEBYTECODE=1 -ENV PYTHONUNBUFFERED=1 -ENV PATH="/app/venv/bin:$PATH" +- Compliance variants: FIPS-enabled and STIG-ready images for regulatory + requirements +- ELS (Extended Lifecycle Support) variants (requires add-on): Security patches + for end-of-life image versions -WORKDIR /app +To access these variants, [mirror](./mirror.md) the repository to your Docker +Hub organization. For ELS, enable **Mirror end-of-life images** when setting up +mirroring. Once mirrored, use the compliance or EOL tags like any other image +tag. -RUN python -m venv /app/venv -COPY requirements.txt . +## Use with Kubernetes -RUN pip install --no-cache-dir -r requirements.txt +When deploying Docker Hardened Images to Kubernetes, the process is similar to +using any other container image with one key difference: you must configure +image pull secrets to authenticate to the DHI registry. This applies whether +you're pulling directly from `dhi.io`, from a mirror on Docker Hub, or from +your own third-party registry. -FROM dhi.io/python:3.13-alpine3.21 +### Create an image pull secret -WORKDIR /app +To pull Docker Hardened Images in Kubernetes, create a secret using a Personal +Access Token (PAT) or Organization Access Token (OAT). Ensure the token has at +least read-only access to the repositories. + +For the `--docker-server` value: +- Use `dhi.io` for community images pulled directly from Docker Hardened Images +- Use `docker.io` for mirrored repositories on Docker Hub +- Use your registry's hostname for third-party registries + +```console +$ kubectl create -n secret docker-registry --docker-server= \ + --docker-username= --docker-password= \ + --docker-email= +``` -ENV PYTHONUNBUFFERED=1 -ENV PATH="/app/venv/bin:$PATH" +### Test the image pull secret -COPY image.py image.png ./ -COPY --from=builder /app/venv /app/venv +After creating the secret, verify it works by deploying a test pod that +references the secret in its `imagePullSecrets` configuration. -ENTRYPOINT [ "python", "/app/image.py" ] +Create a test pod: + +```console +kubectl apply --wait -f - < +spec: + containers: + - name: test + image: bash:5 + command: [ "sh", "-c", "echo 'Hello from DHI in Kubernetes!'" ] + imagePullSecrets: + - name: +EOF ``` -This pattern separates the build environment from the runtime environment, -helping reduce image size and improve security by removing unnecessary tooling -from the final image. +Check the pod status to ensure it completed successfully: -## Use compliance variants {tier="DHI Select & Enterprise"} +```console +$ kubectl get -n pods/dhi-test +``` -{{< summary-bar feature_name="Docker Hardened Images" >}} +A successful test shows `Completed` status: + +```console +NAME READY STATUS RESTARTS AGE +dhi-test 0/1 Completed ... ... +``` + +If you see `ErrImagePull` status instead, there's an issue with your secret +configuration: -When you have a DHI Select or DHI Enterprise subscription, you can access -compliance variants such as FIPS-enabled and STIG-ready images. These -variants help meet regulatory and compliance requirements for secure -deployments. +```console +NAME READY STATUS RESTARTS AGE +dhi-test 0/1 ErrImagePull 0 ... +``` + +Verify the pod output matches the expected message: -To use a compliance variant, you must first [mirror](./mirror.md) the -repository, and then pull the compliance image from your mirrored repository. \ No newline at end of file +```console +$ kubectl logs -n pods/dhi-test +Hello from DHI in Kubernetes! +``` + +Clean up the test pod: + +```console +$ kubectl delete -n pods/dhi-test +```