From 6fcbcfb30b2ca4def940a2c959cd123da7dc1f42 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Fri, 5 Jun 2026 09:29:23 -0700 Subject: [PATCH 1/3] dhi: env vars in customizations Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/customize.md | 50 +++++++++++++++++++------ 1 file changed, 38 insertions(+), 12 deletions(-) diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md index 0f6e2374bb02..160086cda91f 100644 --- a/content/manuals/dhi/how-to/customize.md +++ b/content/manuals/dhi/how-to/customize.md @@ -81,8 +81,7 @@ You can create customizations using either the DHI CLI or the Docker Hub web int 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 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). + image. You can add multiple OCI artifact images to a single customization. When you add more than one, they're applied in the order you add them in the @@ -102,6 +101,10 @@ You can create customizations using either the DHI CLI or the Docker Hub web int > image build still succeeds, but you may have issues when running the > image. + To learn more about OCI artifacts, including how to create them, best + practices, and how environment variables behave, see + [OCI artifacts](#oci-artifacts). + 1. In the **Scripts** section, you can add, edit, or remove scripts. Scripts let you add files to the container image that you can access at runtime. They are not executed during @@ -351,8 +354,9 @@ contents: | `includes` | Paths to copy from the artifact. No files are included by default. You must list at least one path. | | `excludes` | Paths to exclude after applying `includes`. | -For instructions on building an OCI artifact image, see -[Create an OCI artifact image](#create-an-oci-artifact-image). +To learn more about OCI artifacts, including how to create them, best +practices, and how environment variables behave, see +[OCI artifacts](#oci-artifacts). #### Inject files into the image @@ -481,14 +485,17 @@ tooling. compression: ZSTD ``` -### Create an OCI artifact image +## OCI artifacts + +In DHI customization, OCI artifacts are Docker images containing files you +want to layer into your image, such as custom certificates, internal tools, or +configuration files. This section covers how to build these artifact images and +how they interact with your customization. -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. +### Create an OCI artifact image -When creating an image to use as an OCI artifact, it should ideally be as -minimal as possible and contain only the necessary files. +Keep artifact images as minimal as possible and include 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 @@ -545,13 +552,32 @@ Once pushed to a repository in your organization's namespace, the OCI artifact automatically appears in the customization workflow when you select OCI artifacts to add to your customized Docker Hardened Image. -#### Best practices for OCI artifacts +### Environment variables + +When you include OCI artifacts in a customization, the environment variables +defined in those artifacts are merged into the final image. The merge follows +these rules: + +- Your customization's environment settings take precedence. An artifact's + variable is only applied if the corresponding key is absent or empty in your + customization. +- `PATH` is an exception. Artifact `PATH` entries are prepended to the + existing `PATH`, giving them runtime precedence. + +This differs from `COPY --from` in a Dockerfile, which copies files without +inheriting environment variables from the source image. To include files from +an OCI artifact without inheriting its environment variables, build the +artifact using a `FROM scratch` final stage, as described in +[Create an OCI artifact image](#create-an-oci-artifact-image). + +### Best practices Follow these best practices when creating OCI artifacts for DHI customizations: - Use multi-stage builds: Build or install dependencies in a builder stage, then copy only the necessary files to a `FROM scratch` final stage. This keeps - the OCI artifact minimal and free of unnecessary build tools. + the OCI artifact minimal and avoids inheriting environment variables from the + builder image into your customization. - Include only essential files: OCI artifacts should contain only the files you need to add to the customized image. Avoid including package managers, From 80a45a69ce56d3adcd3f6fcf860276c34f3590a0 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Fri, 5 Jun 2026 09:50:07 -0700 Subject: [PATCH 2/3] vale reword Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/customize.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md index 160086cda91f..3cff1b78af44 100644 --- a/content/manuals/dhi/how-to/customize.md +++ b/content/manuals/dhi/how-to/customize.md @@ -561,8 +561,8 @@ these rules: - Your customization's environment settings take precedence. An artifact's variable is only applied if the corresponding key is absent or empty in your customization. -- `PATH` is an exception. Artifact `PATH` entries are prepended to the - existing `PATH`, giving them runtime precedence. +- `PATH` is an exception. Artifact `PATH` entries are added to the front of + the existing `PATH`, giving them runtime precedence. This differs from `COPY --from` in a Dockerfile, which copies files without inheriting environment variables from the source image. To include files from From 701d21221a176c62565c21173631bbfe5c6333ea Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Fri, 5 Jun 2026 09:59:28 -0700 Subject: [PATCH 3/3] agent nits Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/customize.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md index 3cff1b78af44..e19df5f02a0d 100644 --- a/content/manuals/dhi/how-to/customize.md +++ b/content/manuals/dhi/how-to/customize.md @@ -101,9 +101,7 @@ You can create customizations using either the DHI CLI or the Docker Hub web int > image build still succeeds, but you may have issues when running the > image. - To learn more about OCI artifacts, including how to create them, best - practices, and how environment variables behave, see - [OCI artifacts](#oci-artifacts). + For more details, see [OCI artifacts](#oci-artifacts). 1. In the **Scripts** section, you can add, edit, or remove scripts. @@ -489,8 +487,7 @@ compression: ZSTD In DHI customization, OCI artifacts are Docker images containing files you want to layer into your image, such as custom certificates, internal tools, or -configuration files. This section covers how to build these artifact images and -how they interact with your customization. +configuration files. ### Create an OCI artifact image @@ -565,10 +562,9 @@ these rules: the existing `PATH`, giving them runtime precedence. This differs from `COPY --from` in a Dockerfile, which copies files without -inheriting environment variables from the source image. To include files from -an OCI artifact without inheriting its environment variables, build the -artifact using a `FROM scratch` final stage, as described in -[Create an OCI artifact image](#create-an-oci-artifact-image). +inheriting environment variables from the source image. To avoid inheriting +environment variables, build the artifact using a `FROM scratch` final stage. +See [Create an OCI artifact image](#create-an-oci-artifact-image). ### Best practices