11.4. 镜像配置

了解并配置镜像 registry 设置。

11.4.1. 镜像控制器配置参数

Image.config.openshift.io/cluster 资源包含有关如何处理镜像的集群范围信息。规范且唯一有效的名称是 cluster。它的 spec 提供以下配置参数。

注意

参数,如 DisableScheduledImport, MaxImagesBulkImportedPerRepository, MaxScheduledImportsPerMinute, ScheduledImageImportMinimumIntervalSeconds, InternalRegistryHostname 不可配置。

参数描述

allowedRegistriesForImport

限制普通用户可从中导入镜像的容器镜像 registry。将此列表设置为您信任包含有效镜像且希望应用程序能够从中导入的 registry。有权从 API 创建镜像或 ImageStreamMappings 的用户不受此策略的影响。通常只有集群管理员具有适当权限。

这个列表中的每个项包含由 registry 域名指定的 registry 的位置。

domainname:指定 registry 的域名。如果 registry 使用非标准的 80443 端口,则该端口也应包含在域名中。

insecure:不安全指示 registry 是否安全。默认情况下,如果未另行指定,registry 假定为安全。

additionalTrustedCA

对包含 image stream importpod image pullopenshift-image-registry pullthrough 和构建期间应受信任的额外 CA 的配置映射的引用。

此配置映射的命名空间为 openshift-config。ConfigMap 的格式是使用 registry 主机名作为键,使用 PEM 编码证书作为值,用于每个要信任的额外 registry CA。

externalRegistryHostnames

提供默认外部镜像 registry 的主机名。只有在镜像 registry 对外公开时才应设置外部主机名。第一个值用于镜像流中的 publicDockerImageRepository 字段。该值必须采用 hostname[:port] 格式。

registrySources

包含用于决定容器运行时在访问构建和 pod 的镜像时应如何处理个别 registry 的配置。例如,是否允许不安全的访问。它不包含内部集群 registry 的配置。

insecureRegistries:无有效 TLS 证书或仅支持 HTTP 连接的 registry。要指定所有子域,请在域名中添加星号 (*) 通配符字符作为前缀。例如: *.example.com。您可以在 registry 中指定单独的软件仓库。例如: reg1.io/myrepo/myapp:latest

blockedRegistries:拒绝镜像拉取(pull)和推送(push)操作的 registry。要指定所有子域,请在域名中添加星号 (*) 通配符字符作为前缀。例如: *.example.com。您可以在 registry 中指定单独的软件仓库。例如: reg1.io/myrepo/myapp:latest。允许所有其他 registry。

allowedRegistries:允许镜像拉取(pull)和推送(push)操作的 registry。要指定所有子域,请在域名中添加星号 (*) 通配符字符作为前缀。例如: *.example.com。您可以在 registry 中指定单独的软件仓库。例如: reg1.io/myrepo/myapp:latest。阻止所有其他 registry。

containerRuntimeSearchRegistries:允许使用镜像短名称的镜像拉取(pull)和推送(push)操作的 registry。阻止所有其他 registry。

可以设置 blockedRegistriesallowedRegistries ,但不能同时都被设置。

警告

当定义 allowedRegistries 参数时,除非明确列出,否则所有 registry (包括 registry.redhat.ioquay.io registry 和默认的 OpenShift 镜像 registry)都会被阻断。当使用参数时,为了避免 pod 失败,将所有 registry(包括 registry.redhat.ioquay.io registry)和 internalRegistryHostname 添加到 allowedRegistries 列表中,因为环境中有效负载镜像需要它们。对于断开连接的集群,还应添加镜像的 registry。

image.config.openshift.io/cluster 资源的 status 项包括了从集群观察到的值。

参数描述

internalRegistryHostname

由控制 internalRegistryHostname 的 Image Registry Operator 设置。它设置默认 OpenShift 镜像 registry 的主机名。该值必须采用 hostname[:port] 格式。为实现向后兼容,您仍可使用 OPENSHIFT_DEFAULT_REGISTRY 环境变量,但该设置会覆盖环境变量。

externalRegistryHostnames

由 Image Registry Operator 设置,在镜像 registry 通过外部公开时为它提供外部主机名。第一个值用于镜像流中的 publicDockerImageRepository 字段。该值必须采用 hostname[:port] 格式。

11.4.2. 配置镜像 registry 设置

您可以通过编辑 image.config.openshift.io/cluster 自定义资源(CR)来配置镜像 registry 设置。当对 registry 的更改应用到 image.config.openshift.io/cluster CR 时,Machine Config Operator (MCO) 执行以下顺序操作:

  1. 对节点进行 cordon 操作
  2. 通过重启 CRI-O 应用更改
  3. 取消记录节点

    注意

    MCO 在检测到更改时不会重启节点。

流程

  1. 编辑 image.config.openshift.io/cluster 自定义资源:

    $ oc edit image.config.openshift.io/cluster

    以下是 image.config.openshift.io/cluster CR 示例:

    apiVersion: config.openshift.io/v1
    kind: Image 1
    metadata:
      annotations:
        release.openshift.io/create-only: "true"
      creationTimestamp: "2019-05-17T13:44:26Z"
      generation: 1
      name: cluster
      resourceVersion: "8302"
      selfLink: /apis/config.openshift.io/v1/images/cluster
      uid: e34555da-78a9-11e9-b92b-06d6c7da38dc
    spec:
      allowedRegistriesForImport: 2
        - domainName: quay.io
          insecure: false
      additionalTrustedCA: 3
        name: myconfigmap
      registrySources: 4
        allowedRegistries:
        - example.com
        - quay.io
        - registry.redhat.io
        - image-registry.openshift-image-registry.svc:5000
        - reg1.io/myrepo/myapp:latest
        insecureRegistries:
        - insecure.com
    status:
      internalRegistryHostname: image-registry.openshift-image-registry.svc:5000
    1
    Image:包含有关如何处理镜像的集群范围信息。规范且唯一有效的名称是 cluster
    2
    allowedRegistriesForImport:限制普通用户可从中导入镜像的容器镜像 registry。将此列表设置为您信任包含有效镜像且希望应用程序能够从中导入的 registry。有权从 API 创建镜像或 ImageStreamMappings 的用户不受此策略的影响。通常只有集群管理员具有适当权限。
    3
    additionalTrustedCA:引用包含镜像流导入、Pod 镜像拉取、openshift-image-registry pullthrough 和构建期间受信任的额外证书颁发机构(CA)的配置映射。此配置映射的命名空间为 openshift-config。ConfigMap 的格式是使用 registry 主机名作为键,使用 PEM 证书作为值,用于每个要信任的额外 registry CA。
    4
    registrySources :包含用于决定容器运行时在访问构建和 pod 的镜像时是否允许或阻止个别 registry 的配置。可以设置 allowedRegistries 参数或 blockedRegistries 参数,但不能同时设置这两个参数。您还可以定义是否允许访问允许使用镜像短名称的不安全的 registry。本例使用 allowedRegistries 参数,该参数定义允许使用的 registry。不安全 registry insecure.com 也被允许。registrySources 参数不包含内部集群 registry 的配置。
    注意

    当定义 allowedRegistries 参数时,除非明确列出,否则所有 registry (包括 registry.redhat.io 和 quay.io registry 和默认的 OpenShift 镜像 registry)都会被阻断。如果使用参数,为了避免 pod 失败,您必须将 registry.redhat.ioquay.io registry 以及 internalRegistryHostname 添加到 allowedRegistries 列表中,因为环境中有效负载镜像需要它们。不要将 registry.redhat.ioquay.io registry 添加到 blockedRegistries 列表中。

    使用 allowedRegistriesblockedRegistriesinsecureRegistries 参数时,您可以在 registry 中指定单独的存储库。例如: reg1.io/myrepo/myapp:latest

    应避免使用不安全的外部 registry,以减少可能的安全性风险。

  2. 要检查是否应用了更改,请列出您的节点:

    $ oc get nodes

    输出示例

    NAME                                         STATUS                     ROLES                  AGE   VERSION
    ip-10-0-137-182.us-east-2.compute.internal   Ready,SchedulingDisabled   worker                 65m   v1.26.0
    ip-10-0-139-120.us-east-2.compute.internal   Ready,SchedulingDisabled   control-plane          74m   v1.26.0
    ip-10-0-176-102.us-east-2.compute.internal   Ready                      control-plane          75m   v1.26.0
    ip-10-0-188-96.us-east-2.compute.internal    Ready                      worker                 65m   v1.26.0
    ip-10-0-200-59.us-east-2.compute.internal    Ready                      worker                 63m   v1.26.0
    ip-10-0-223-123.us-east-2.compute.internal   Ready                      control-plane          73m   v1.26.0

如需有关允许、阻止和不安全的 registry 参数的更多信息,请参阅配置镜像 registry 设置

11.4.3. 为镜像 registry 访问配置额外的信任存储

Image.config.openshift.io/cluster 自定资源可包含对配置映射的引用,该配置映射包含要在镜像 registry 访问期间被信任的额外证书颁发机构。

先决条件

  • 证书颁发机构(CA)必须经过 PEM 编码。

流程

您可以在openshift-config命名空间中创建配置映射,并在 image.config.openshift.io 子定义资源中的 AdditionalTrustedCA 中使用其名称,以提供与外部 registry 联系时可以被信任的额外CA。

对于每个要信任的额外 registry CA,配置映射键是带有要信任此 CA 的端口的 registry 的主机名,而 PEM 证书内容是要信任的每个额外 registry CA。

镜像 registry CA 配置映射示例

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-registry-ca
data:
  registry.example.com: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  registry-with-port.example.com..5000: | 1
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----

1
如果 registry 带有端口,如 registry-with-port.example.com:5000: 需要被 .. 替换。

您可以按照以下过程配置其他CA。

  1. 配置其他CA:

    $ oc create configmap registry-config --from-file=<external_registry_address>=ca.crt -n openshift-config
    $ oc edit image.config.openshift.io cluster
    spec:
      additionalTrustedCA:
        name: registry-config

11.4.4. 配置镜像 registry 存储库镜像

通过设置容器 registry 存储库镜像,您可以执行以下任务:

  • 配置 OpenShift Container Platform 集群,以便重定向从源镜像 registry 上的存储库拉取(pull)镜像的请求,并通过已镜像 (mirror) 的镜像 registry 上的存储库来解决该请求。
  • 为每个目标存储库识别多个已镜像 (mirror)的存储库,以确保如果一个镜像停止运作,仍可使用其他镜像。

OpenShift Container Platform 中的存储库镜像包括以下属性:

  • 镜像拉取(pull)可应对 registry 停机的问题。
  • 在断开连接的环境中的集群可以从关键位置(如 quay.io)拉取镜像,并让公司防火墙后面的 registry 提供请求的镜像。
  • 发出镜像拉取(pull)请求时尝试特定 registry 顺序,通常最后才会尝试持久性 registry。
  • 您所输入的镜像信息会添加到 OpenShift Container Platform 集群中每个节点上的 /etc/containers/registries.conf 文件中。
  • 当节点从源存储库中请求镜像时,它会依次尝试每个已镜像的存储库,直到找到所请求的内容。如果所有镜像均失败,集群则会尝试源存储库。如果成功,则镜像拉取至节点中。

可通过以下方式设置存储库镜像:

  • 在 OpenShift Container Platform 安装中:

    通过拉取(pull) OpenShift Container Platform 所需的容器镜像,然后将这些镜像放至公司防火墙后,即可将 OpenShift Container Platform 安装到受限网络中的数据中心。

  • 安装 OpenShift Container Platform 后:

    如果您没有在 OpenShift Container Platform 安装过程中配置镜像,您可以在安装后使用以下自定义资源 (CR) 对象之一:

    • ImageDigestMirrorSet.此 CR 允许您使用摘要规格从镜像 registry 中拉取镜像。
    • ImageTagMirrorSet.此 CR 允许您使用镜像标签从已镜像的 registry 中拉取镜像。
    重要

    使用 ImageContentSourcePolicy (ICSP)对象配置存储库镜像是一个已弃用的功能。弃用的功能仍然包含在 OpenShift Container Platform 中,并将继续被支持。但是,这个功能会在以后的发行版本中被删除,且不建议在新的部署中使用。如果您有用于创建 ImageContentSourcePolicy 对象的 YAML 文件,您可以使用 oc adm migrate icsp 命令将这些文件转换为 ImageDigestMirrorSet YAML 文件。如需更多信息,请参阅以下部分"协调 ImageContentSourcePolicy (ICSP)文件以进行镜像 registry 存储库镜像"。

这两个自定义资源对象都标识以下信息:

  • 您希望镜像 (mirror) 的容器镜像存储库的源。
  • 您希望为其提供从源存储库请求的内容的每个镜像存储库的单独条目。
注意

如果您的集群使用 ImageDigestMirrorSetImageTagMirrorSet 对象来配置存储库镜像,则只能将全局 pull secret 用于镜像 registry。您不能在项目中添加 pull secret。

以下流程创建安装后镜像配置,您可以在其中创建 ImageDigestMirrorSet 对象。

先决条件

  • 确保可以使用具有 cluster-admin 角色的用户访问集群。
  • 确保集群中没有 ImageContentSourcePolicy 对象。例如,您可以使用以下命令:

    $ oc get ImageContentSourcePolicy

    输出示例

    No resources found

流程

  1. 通过以下方法配置已镜像的存储库:

    • 按照 Red Hat Quay 存储库镜像中所述,使用 Red Hat Quay 来设置已镜像的存储库。使用 Red Hat Quay 有助于您将镜像从一个存储库复制到另一存储库,并可随着时间的推移重复自动同步这些存储库。
    • 使用 skopeo 等工具手动将镜像从源目录复制到已镜像的存储库。

      例如:在 Red Hat Enterprise Linux(RHEL 7 或 RHEL 8)系统上安装 skopeo RPM 软件包后,使用 skopeo 命令,如下例所示:

      $ skopeo copy \
      docker://registry.access.redhat.com/ubi9/ubi-minimal:latest@sha256:5cf... \
      docker://example.io/example/ubi-minimal

      在本例中,您有一个名为 example.io 的容器镜像 registry,其中包含一个名为 example 的镜像存储库,您要将 ubi9/ubi-minimal 镜像从 registry.access.redhat.com 复制到其中。创建该 registry 后,您可将 OpenShift Container Platform 集群配置为将源存储库的请求重定向到已镜像的存储库。

  2. 登录您的 OpenShift Container Platform 集群。
  3. 根据需要,创建一个 ImageDigestMirrorSetImageTagMirrorSet CR,将源和镜像(mirror)替换为您自己的 registry、存储库对和镜像:

    apiVersion: config.openshift.io/v1 1
    kind: ImageDigestMirrorSet 2
    metadata:
      name: ubi9repo
    spec:
      imageDigestMirrors: 3
      - mirrors:
        - example.io/example/ubi-minimal 4
        - example.com/example/ubi-minimal 5
        source: registry.access.redhat.com/ubi9/ubi-minimal 6
        mirrorSourcePolicy: AllowContactingSource 7
      - mirrors:
        - mirror.example.com/redhat
        source: registry.redhat.io/openshift4 8
        mirrorSourcePolicy: AllowContactingSource
      - mirrors:
        - mirror.example.com
        source: registry.redhat.io 9
        mirrorSourcePolicy: AllowContactingSource
      - mirrors:
        - mirror.example.net/image
        source: registry.example.com/example/myimage 10
        mirrorSourcePolicy: AllowContactingSource
      - mirrors:
        - mirror.example.net
        source: registry.example.com/example 11
        mirrorSourcePolicy: AllowContactingSource
      - mirrors:
        - mirror.example.net/registry-example-com
        source: registry.example.com 12
        mirrorSourcePolicy: AllowContactingSource
    1
    指明此 CR 要使用的 API。这必须是 config.openshift.io/v1
    2
    根据 pull 类型指示对象类型:
    • ImageDigestMirrorSet :提取摘要引用镜像。
    • ImageTagMirrorSet :提取标签引用镜像。
    3
    表示镜像拉取方法的类型,请执行以下任一方法:
    • imageDigestMirrors :用于 ImageDigestMirrorSet CR。
    • imageTagMirrors :用于 ImageTagMirrorSet CR。
    4
    指明镜像 registry 和存储库的名称。
    5
    可选:指定每个目标仓库的二级镜像存储库。如果一个镜像停机,则目标仓库可以使用另一个镜像。
    6
    指明 registry 和存储库源,这是在镜像拉取规格中引用的存储库。
    7
    可选:如果镜像拉取失败,则指示回退策略:
    • AllowContactingSource :允许继续尝试从源存储库拉取镜像。这是默认值。
    • NeverContactSource: 防止继续尝试从源存储库拉取镜像。
    8
    可选:指示 registry 中的命名空间,它允许您使用该命名空间中的任何镜像。如果您使用 registry 域作为源,则对象将应用到 registry 中的所有存储库。
    9
    可选:指示一个 registry,它允许您使用该 registry 中的任何镜像。如果指定了 registry 名称,对象将应用到源 registry 中的所有存储库到镜像 registry。
    10
    从 mirror mirror.example.net/image@sha256:.. 拉取镜像 registry.example.com/example/myimage@sha256:…​
    11
    从 mirror mirror.example.net/image@sha256:…​ 的源 registry 命名空间中拉取镜像 registry.example.com/example/image@sha256:…​
    12
    从 mirror registry example.net/registry-example-com/myimage@sha256:…​ 中拉取镜像 registry.example.com/myimage@sha256ImageContentSourcePolicy 资源会应用到源 registry 中的所有仓库到到 mirror registry mirror.example.net/registry-example-com
  4. 创建新对象:

    $ oc create -f registryrepomirror.yaml

    创建对象后,Machine Config Operator (MCO) 会限制节点,因为新的设置被部署到每个节点。MCO 只为 ImageTagMirrorSet 对象重启节点。MCO 不会为 ImageDigestMirrorSet 对象重启节点。当节点被取消封锁时,集群开始使用已镜像的存储库向源存储库发出请求。

  5. 要检查是否应用了镜像的配置设置,请在其中一个节点上执行以下操作。

    1. 列出您的节点:

      $ oc get node

      输出示例

      NAME                           STATUS                     ROLES    AGE  VERSION
      ip-10-0-137-44.ec2.internal    Ready                      worker   7m   v1.26.0
      ip-10-0-138-148.ec2.internal   Ready                      master   11m  v1.26.0
      ip-10-0-139-122.ec2.internal   Ready                      master   11m  v1.26.0
      ip-10-0-147-35.ec2.internal    Ready                      worker   7m   v1.26.0
      ip-10-0-153-12.ec2.internal    Ready                      worker   7m   v1.26.0
      ip-10-0-154-10.ec2.internal    Ready                      master   11m  v1.26.0

    2. 启动调试过程以访问节点:

      $ oc debug node/ip-10-0-147-35.ec2.internal

      输出示例

      Starting pod/ip-10-0-147-35ec2internal-debug ...
      To use host binaries, run `chroot /host`

    3. 将您的根目录改为 /host

      sh-4.2# chroot /host
    4. 检查 /etc/containers/registries.conf 文件,确保已完成更改:

      sh-4.2# cat /etc/containers/registries.conf

      以下输出代表了一个 registry.conf 文件,其中应用了 ImageDigestMirrorSet 对象和一个 ImageTagMirrorSet 对象。最后的两个条目分别标记为 digest-onlytag-only

      输出示例

      unqualified-search-registries = ["registry.access.redhat.com", "docker.io"]
      short-name-mode = ""
      
      [[registry]]
        prefix = ""
        location = "registry.access.redhat.com/ubi9/ubi-minimal" 1
      
        [[registry.mirror]]
          location = "example.io/example/ubi-minimal" 2
          pull-from-mirror = "digest-only" 3
      
        [[registry.mirror]]
          location = "example.com/example/ubi-minimal"
          pull-from-mirror = "digest-only"
      
      [[registry]]
        prefix = ""
        location = "registry.example.com"
      
        [[registry.mirror]]
          location = "mirror.example.net/registry-example-com"
          pull-from-mirror = "digest-only"
      
      [[registry]]
        prefix = ""
        location = "registry.example.com/example"
      
        [[registry.mirror]]
          location = "mirror.example.net"
          pull-from-mirror = "digest-only"
      
      [[registry]]
        prefix = ""
        location = "registry.example.com/example/myimage"
      
        [[registry.mirror]]
          location = "mirror.example.net/image"
          pull-from-mirror = "digest-only"
      
      [[registry]]
        prefix = ""
        location = "registry.redhat.io"
      
        [[registry.mirror]]
          location = "mirror.example.com"
          pull-from-mirror = "digest-only"
      
      [[registry]]
        prefix = ""
        location = "registry.redhat.io/openshift4"
      
        [[registry.mirror]]
          location = "mirror.example.com/redhat"
          pull-from-mirror = "digest-only"
      [[registry]]
        prefix = ""
        location = "registry.access.redhat.com/ubi9/ubi-minimal"
        blocked = true 4
      
        [[registry.mirror]]
          location = "example.io/example/ubi-minimal-tag"
          pull-from-mirror = "tag-only" 5

      1
      指明在 pull spec 中引用的存储库。
      2
      指明该存储库的镜像。
      3
      表示从 mirror 的镜像拉取是一个摘要引用镜像。
      4
      表示为此存储库设置了 NeverContactSource 参数。
      5
      表示从 mirror 的镜像拉取是一个标签引用镜像。
    5. 从源拉取镜像到节点,并检查是否通过 mirror 解析。

      sh-4.2# podman pull --log-level=debug registry.access.redhat.com/ubi9/ubi-minimal@sha256:5cf...

存储库镜像故障排除

如果存储库镜像流程未按规定工作,请使用以下有关存储库镜像如何工作的信息协助排查问题。

  • 首个工作镜像用于提供拉取(pull)的镜像。
  • 只有在无其他镜像工作时,才会使用主 registry。
  • 从系统上下文,Insecure 标志用作回退。
  • 最近更改了 /etc/containers/registries.conf 文件的格式。现在它是第 2 版,采用 TOML 格式。
  • 您不能将同一存储库添加到 ImageDigestMirrorSetImageTagMirrorSet 对象中。

11.4.5. 为镜像 registry 存储库镜像转换 ImageContentSourcePolicy (ICSP) 文件

使用 ImageContentSourcePolicy (ICSP)对象配置存储库镜像是一个已弃用的功能。此功能仍然包含在 OpenShift Container Platform 中,并将继续被支持。但是,这个功能会在以后的发行版本中被删除,且不建议在新的部署中使用。

ICSP 对象被 ImageDigestMirrorSetImageTagMirrorSet 对象替代,以配置存储库镜像。如果您有用于创建 ImageContentSourcePolicy 对象的 YAML 文件,您可以使用 oc adm migrate icsp 命令将这些文件转换为 ImageDigestMirrorSet YAML 文件。命令将 API 更新至当前版本,将 kind 值更改为 ImageDigestMirrorSet,并将 spec.repositoryDigestMirrors 更改为 spec.imageDigestMirrors。文件的其余部分不会改变。

有关 ImageDigestMirrorSetImageTagMirrorSet 对象的更多信息,请参阅上一节中的"配置镜像 registry 存储库镜像"。

先决条件

  • 确保可以使用具有 cluster-admin 角色的用户访问集群。
  • 确保集群中具有 ImageContentSourcePolicy 对象。

流程

  1. 使用以下命令,将一个或多个 ImageContentSourcePolicy YAML 文件转换为 ImageDigestMirrorSet YAML 文件:

    $ oc adm migrate icsp <file_name>.yaml <file_name>.yaml <file_name>.yaml --dest-dir <path_to_the_directory>

    其中:

    <file_name>
    指定源 ImageContentSourcePolicy YAML 的名称。您可以列出多个文件名。
    --dest-dir
    可选:指定输出 ImageDigestMirrorSet YAML 的目录。如果未设置,则会将该文件写入当前目录中。

    例如,以下命令可将 icsp.yamlicsp-2.yaml 文件转换,并将新的 YAML 文件保存到 idms-files 目录中。

    $ oc adm migrate icsp icsp.yaml icsp-2.yaml --dest-dir idms-files

    输出示例

    wrote ImageDigestMirrorSet to idms-files/imagedigestmirrorset_ubi8repo.5911620242173376087.yaml
    wrote ImageDigestMirrorSet to idms-files/imagedigestmirrorset_ubi9repo.6456931852378115011.yaml

  2. 运行以下命令来创建 CR 对象:

    $ oc create -f <path_to_the_directory>/<file-name>.yaml

    其中:

    <path_to_the_directory>
    如果使用 --dest-dir 标志,请指定目录的路径。
    <file_name>
    指定 ImageDigestMirrorSet YAML 的名称。