自定义 Docker Hardened Image 或 chart

当您拥有 DHI Select 或 DHI Enterprise 订阅时，可以通过 Docker Hub 网页界面自定义 Docker 加固镜像（DHI）和 chart，以满足您的特定需求。对于镜像，您可以选择基础镜像、添加软件包、添加 OCI 制品（例如自定义证书或额外工具）以及配置设置。对于 chart，您可以自定义镜像引用。

您的自定义内容会自动保持安全。当基础 Docker 加固镜像或 chart 收到安全补丁，或您的 OCI 制品更新时，Docker 会在后台自动重建您的自定义内容。这确保了默认情况下持续合规和保护，无需手动操作。重建的制品会按照与基础镜像和 chart 相同的 SLSA Build Level 3 标准进行签名和验证，确保供应链安全可靠且可验证。

自定义 Docker 加固镜像

要向您的组织添加自定义的 Docker 加固镜像，组织所有者必须首先将 DHI 仓库镜像到 Docker Hub 上的您的组织中。一旦仓库被镜像，任何有权访问镜像 DHI 仓库的用户都可以创建自定义镜像。

您可以使用 DHI CLI 或 Docker Hub 网页界面创建自定义。

# 准备单个自定义脚手架
$ docker dhi customization prepare golang 1.25 \
  --org my-org \
  --destination my-org/dhi-golang \
  --name "golang with git" \
  > my-customization.yaml

# 准备批量自定义脚手架（通过 stdin 管道传入 JSON 数组）
$ echo '[{"destination":"my-org/dhi-golang","tag-definition-id":"golang/alpine-3.23/1.24-dev"}]' \
  | docker dhi customization prepare --name "golang with git" --org my-org \
  > my-customization.yaml

# 创建自定义
$ docker dhi customization create my-customization.yaml --org my-org

# 列出自定义
$ docker dhi customization list --org my-org

# 按名称、仓库或来源筛选自定义
$ docker dhi customization list --org my-org --filter git
$ docker dhi customization list --org my-org --repo dhi-golang
$ docker dhi customization list --org my-org --source golang

# 按 ID 获取自定义
$ docker dhi customization get <id> --org my-org

# 更新自定义
$ docker dhi customization edit my-customization.yaml --org my-org

# 按 ID 删除自定义
$ docker dhi customization delete <id> --org my-org

# 无需确认提示直接删除
$ docker dhi customization delete <id> --org my-org --force

resource "dhi_customization" "golang_with_git" {
  repository = "dhi-golang"
  name       = "golang with git"

  contents {
    packages = ["git", "curl"]
  }

  platform {
    os           = "linux"
    architecture = "amd64"
  }
}

镜像自定义 YAML 文件

使用 CLI 时，自定义在 YAML 文件中定义。使用 docker dhi customization prepare 生成包含所有可用字段和注释示例的脚手架。编辑文件以描述您想要的内容，然后将其传递给 docker dhi customization create。

该文件有两部分：标识自定义及其目标的前言，以及指定要更改内容的配置节。

关于 id 字段

id 字段在您运行 docker dhi customization create 时由 Docker Hub 自动分配。创建新自定义时，请完全省略 id。它是只读的。

要查找现有自定义的 ID，请运行：

$ docker dhi customization list --org my-org

id 会显示在输出中，以及通过 docker dhi customization get <id> --org my-org 检索到的文件中。它使 docker dhi customization edit 能够识别要更新的自定义。docker dhi customization prepare 生成的脚手架不包含 id，这是预期的行为。

设置目标

name 和 targets 字段在每个自定义文件中都是必填的。targets 数组指定自定义应用于哪些镜像版本。对单个镜像自定义使用单个条目，或对一次性将相同配置应用于多个镜像的批量自定义使用多个条目。

name: golang with git

targets:
  - destination: my-org/dhi-golang
    tag_definition_id: golang/alpine-3.23/1.25

Note

当 targets 有多个条目时，不支持 accounts、entrypoint 和 cmd 字段。包含它们会导致 docker dhi customization create 返回错误。

添加软件包

要在自定义镜像中安装额外的操作系统软件包，请在 contents.packages 下列出它们。可用的软件包取决于基础镜像变体。

contents:
  packages:
    - git
    - curl

添加 OCI 制品

要将额外文件（例如自定义证书、内部工具或配置文件）分层到自定义镜像中，请在 contents.artifacts 下列出 OCI 制品镜像。

contents:
  artifacts:
    - name: my-org/my-certs:latest
      includes:
        - etc/ssl/certs
      excludes:
        - etc/ssl/certs/old

要了解有关 OCI 制品的更多信息，包括如何创建它们、最佳实践以及环境变量的行为，请参阅 OCI artifacts。

向镜像注入文件

要在构建时添加静态文件（例如配置文件或启动脚本），请使用 paths 字段。文件作为静态内容添加，不会在构建期间执行。

paths:
  - path: /etc/myconfig
    contents: |
      key=value
    mode: "0644"
    uid: 0
    gid: 0

配置用户账户

要向镜像添加用户或组，或更改容器以哪个用户运行，请使用 accounts 字段。

Note

批量自定义（多个 targets）不支持。

accounts:
  root: true
  runs-as: nonroot
  users:
    - name: nonroot
      uid: 65532
      gid: 65532
  groups:
    - name: nonroot
      gid: 65532
      members:
        - nonroot

设置环境变量

要向镜像添加或覆盖环境变量，请使用 environment 字段。这些变量会与基础镜像现有的环境变量合并，而不会替换它们。

environment:
  MY_VAR: my_value
  DEBUG: "false"

对 YAML 解析器会解释为非字符串类型的值加引号，例如 "false"、"0" 和 "null"。

设置标签和注解

要向镜像添加 OCI 元数据，请使用 labels 和 annotations。标签存储在镜像配置中；注解存储在镜像清单中。在适用的情况下使用 OCI 标准键。

labels:
  org.opencontainers.image.authors: [email protected]
  org.opencontainers.image.version: "1.0.0"

annotations:
  org.opencontainers.image.title: Custom hardened image
  org.opencontainers.image.description: Customized Docker Hardened Image

覆盖入口点和命令

要更改容器的启动方式，请使用 entrypoint 和 cmd。这些参数会附加到基础镜像现有的入口点和命令。

Note

批量自定义（多个 targets）不支持。

entrypoint:
  - /docker-entrypoint.sh

cmd:
  - /bin/bash

设置平台和压缩

要为多个架构构建，请在 platforms 下列出它们。至少需要一个平台。

platforms:
  - linux/amd64
  - linux/arm64

要控制层压缩，请设置 compression。ZSTD（默认）提供更好的压缩和更快的拉取。使用 GZIP 以兼容较旧的工具。

compression: ZSTD

OCI artifacts

在 DHI 自定义中，OCI 制品是包含您要分层到镜像中文件（例如自定义证书、内部工具或配置文件）的 Docker 镜像。

创建 OCI 制品镜像

使制品镜像尽可能最小化，仅包含必要的文件。

例如，要将自定义根 CA 证书作为受信任 CA 捆绑包的一部分分发，您可以使用多阶段构建。这种方法会将您的证书注册到系统中并输出更新的 CA 捆绑包，可以将其提取到最小的最终镜像中：

# syntax=docker/dockerfile:1

FROM dhi.io/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

您可以遵循此模式创建其他 OCI 制品，例如包含您要包含在自定义 DHI 中的工具或库的镜像。在第一阶段安装必要的工具或库，然后将相关文件复制到使用 FROM scratch 的最终阶段。这确保您的 OCI 制品最小化，并且仅包含必要的文件。

为了使 OCI 制品在 DHI 自定义中可用，必须将其构建并推送到与镜像 DHI 仓库相同命名空间中的仓库。

如果您正在为多个平台（例如 linux/amd64 和 linux/arm64）自定义 DHI，请使用 --platform 标志为所有平台构建 OCI 制品：

$ docker buildx build --platform linux/amd64,linux/arm64 \
  -t <your-namespace>/my-oci-artifact:latest \
  --push .

这会创建一个单一镜像清单，您可以将其用于每个平台。自定义构建系统在构建每个自定义镜像时会自动选择正确的平台变体。

Important

自定义 UI 仅允许您选择所有已添加 OCI 制品中可用的平台。如果任何 OCI 制品中缺少某个平台，您将无法为该自定义选择该平台。

一旦推送到您组织命名空间中的仓库，当您选择要添加到自定义 Docker 加固镜像的 OCI 制品时，OCI 制品会自动出现在自定义工作流中。

环境变量

当您在自定义中包含 OCI 制品时，这些制品中定义的环境变量会合并到最终镜像中。合并遵循以下规则：

• 您的自定义的 environment 设置优先。只有当相应键在您的自定义中缺失或为空时，才会应用制品的变量。
• PATH 是个例外。制品的 PATH 条目会添加到现有 PATH 的前面，使它们在运行时优先。

这与 Dockerfile 中的 COPY --from 不同，后者复制文件而不会从源镜像继承环境变量。要避免继承环境变量，请使用 FROM scratch 最终阶段构建制品。请参阅创建 OCI 制品镜像。

最佳实践

为 DHI 自定义创建 OCI 制品时，请遵循以下最佳实践：

• 使用多阶段构建：在构建器阶段构建或安装依赖项，然后仅将必要的文件复制到 FROM scratch 最终阶段。这保持 OCI 制品最小化，并避免从构建器镜像继承环境变量到您的自定义中。

• 仅包含必需文件：OCI 制品应仅包含您需要添加到自定义镜像中的文件。避免包含包管理器、shell 或其他在最终镜像中不会使用的实用程序。

• 匹配目标平台：为您计划在自定义中使用的所有平台构建 OCI 制品。在需要时使用 docker buildx build --platform 创建多平台镜像。

• 使用特定标签：使用特定版本或日期（如 v1.0 或 20250101）标记您的 OCI 制品，而不是仅依赖 latest。这可以确保可重现的构建，并使跟踪哪些制品用于哪些自定义更加容易。

• 启用不可变标签：考虑为您的 OCI 制品仓库启用不可变标签。这可以防止意外覆盖，并确保您的 OCI 制品每个版本保持不变，从而提高自定义的可重现性和可靠性。

自定义 DHI Helm chart

您可以自定义 DHI Helm chart 以满足您组织的特定需求。通过 Docker Hub 网页界面，您可以修改镜像引用以引用您创建的镜像镜像或自定义镜像。这使您可以创建一个自定义的、安全构建的 chart，其中包含对存储在 Docker Hub 或其他私有仓库中镜像的引用。默认情况下，DHI 会安全地打包引用您仓库的自定义 Helm chart，无论它们存储在哪里。

要自定义镜像引用，组织所有者必须将 DHI chart 仓库镜像到 Docker Hub 上的您的组织中。

每个 Helm chart 仓库只能创建一个 chart 自定义。这与镜像自定义不同，后者每个仓库可以创建多个自定义。如果您需要进行更改，可以编辑现有自定义。或者，您可以再次镜像相同的 Helm chart 仓库，并向新镜像添加新的自定义。

Note

您可以使用标准 Helm 工具和做法（例如 values.yaml 文件）在 Docker Hub 外部自定义 Docker 加固镜像 chart，就像任何其他 Helm chart 一样。以下说明描述了如何使用 Docker Hub 网页界面自定义 chart 的镜像引用。

要在镜像后自定义 Docker 加固镜像 Helm chart：

1. 登录 Docker Hub。

2. 选择 My Hub。

3. 在命名空间下拉菜单中，选择拥有镜像 DHI 仓库的组织。

4. 选择 Hardened Images > Manage > Mirrored Helm charts。

5. 对于您要自定义的镜像 DHI 仓库，选择 Name。

6. 选择 Customizations 选项卡。

7. 选择 Create customization。

   此时，屏幕上的说明将引导您完成自定义过程。

Helm chart 自定义 YAML 文件

使用 CLI 时，Helm chart 自定义使用与镜像自定义相同的 prepare / create 工作流，但配置节使用 reference_mappings 而非镜像字段。

使用 reference_mappings 替换 chart 中的镜像引用，例如将 chart 的镜像引用指向您镜像的 DHI。

name: use mirrored images

targets:
  - destination: my-org/dhi-haproxy-chart
    tag_definition_id: haproxy/helm/1

reference_mappings:
  - from: dhi/haproxy
    to: my-org/dhi-haproxy

监控自定义构建

创建自定义后，您可以通过 Docker Hub 或 DHI CLI 跟踪构建状态并查看日志。

$ docker dhi customization build list <customization-id> --org my-org

$ docker dhi customization build get <customization-id> <build-id> --org my-org

$ docker dhi customization build logs <customization-id> <build-id> --org my-org

编辑或删除自定义

$ docker dhi customization edit my-customization.yaml --org my-org

$ docker dhi customization delete <id> --org my-org
$ docker dhi customization delete <id> --org my-org --force