使用容器映像的注册表镜像

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本页介绍了如何使用从注册表镜像（而非从 gcr.io 等公共注册表）中拉取的映像创建和升级集群。您可以在集群生命周期中随时启用或停用此功能。

本页面适用于配置和管理存储性能、用量和费用的运维人员和存储专家。如需详细了解我们在 Google Cloud 内容中提及的常见角色和示例任务，请参阅常见的 GKE Enterprise 用户角色和任务。

注册表镜像是公共注册表的本地副本，它会复制或镜像公共注册表的文件结构。例如，假设本地注册表镜像的路径为 172.18.0.20:5000。当 containerd 遇到拉取 gcr.io/kubernetes-e2e-test-images/nautilus:1.0 等映像的请求时，containerd 会尝试从位于以下路径的本地注册表（而非从 gcr.io）中拉取该映像：172.18.0.20:5000/kubernetes-e2e-test-images/nautilus:1.0。如果该映像不在此本地注册表路径中，则系统会自动从 gcr.io 公共注册表中拉取该映像。

使用注册表镜像具有以下优势：

• 保护您免受公共注册表服务中断的影响。
• 加速 Pod 创建。
• 使您可以执行自己的漏洞扫描。
• 避免公共注册表对发出命令的频率施加限制。

准备工作

• 您必须在网络中设置容器注册表服务器。
• 如果您的注册表服务器运行专用 TLS 证书，则您必须拥有证书授权机构 (CA) 文件。
• 如果您的注册表服务器需要身份验证，则您必须具有适当的登录凭据或 Docker 配置文件。
• 如果您使用的是 Red Hat Quay 注册库，则可能需要手动创建本地注册库的目录结构。
• 如需使用注册表镜像，您必须将容器运行时设置为 containerd。
• 确保您的管理员工作站上有足够的磁盘空间来支持图片上传。图片上传命令 bmctl push images 会先解压缩下载的图片软件包文件，然后在本地提取所有图片文件，然后再上传这些图片。您应至少有下载的图片软件包文件大小的三倍磁盘空间，以便容纳图片上传内容。例如，压缩后的 bmpackages_1.31.200-gke.59.tar.xz 文件大约占用 8.5 GB 的磁盘空间，因此您在下载该文件之前，应至少有 25.5 GB 的可用磁盘空间。

下载 Google Distributed Cloud 的所有必需映像

从下载页面下载最新版本的 bmctl 工具和映像软件包。

将容器映像上传到您的注册表服务器

当您使用 bmctl push images 将容器映像上传到代码库服务器时，bmctl 会按顺序执行以下步骤：

1. 将下载的映像软件包压缩 tar 文件（例如 bmpackages_1.31.300-gke.81.tar.xz）解压缩为 bmpackages_1.31.300-gke.81.tar。

2. 将解压缩的 tar 文件中的所有图片提取到名为 bmpackages_1.31.300-gke.81 的目录中。

3. 将每个映像文件推送到指定的私有注册表。

   bmctl 使用 --username 和 --password 值进行基本身份验证，以将映像推送到您的私有注册表。

以下部分介绍了用于将图片上传到代码库服务器的 bmctl push images 命令的一些常见变体。

使用您的注册库进行身份验证并共享 TLS 证书

以下命令包含 --username 和 --password 标志，用于对注册表服务器进行用户身份验证。该命令还包含用于传递 CA 传输层安全协议 (TLS) 证书的 --cacert 标志，该证书用于安全的注册库服务器通信，包括映像推送和拉取。这些标志可为您的注册表服务器提供基本安全保障。

如果您的注册表服务器需要身份验证，并且您未使用 --username 和 --password 标志，则在运行 bmctl push images 时，系统应会提示您输入凭据。您可以输入密码，也可以选择包含凭据的 Docker 配置文件。

如需上传带有身份验证和私有 CA 证书的映像，请使用类似以下的命令：

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --username USERNAME \
    --password PASSWORD \
    --cacert CERT_PATH

替换以下内容：

• IMAGES_TAR_FILE_PATH：下载的映像软件包 tar 文件的路径，例如 bmpackages_1.31.300-gke.81.tar.xz。

• REGISTRY_IP:PORT：私有注册表服务器的 IP 地址和端口。

• USERNAME：具有将图片上传到注册表服务器的访问权限的用户的用户名。

• PASSWORD：用户用于对注册表服务器进行身份验证的密码。

• CERT_PATH：CA 证书文件的路径（如果您的注册表服务器使用专用 TLS 证书）。

例如：

bmctl push images \
    --source bmpackages_1.31.300-gke.81.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --username alex --password pa55w0rd \
    --cacert /etc/pki/tls/certs/ca-bundle.crt

无需用户身份验证或证书即可上传图片

如果您的注册表服务器不需要凭据（例如用户名和密码），请在 bmctl 命令中指定 --need-credential=false。如果您的注册表服务器使用公共 TLS 证书，则无需使用 --cacert 标志。此类上传命令最适合测试环境，因为在测试环境中，安全性不如生产环境重要。

如需在不进行身份验证或不使用私有 CA 证书的情况下上传图片，请使用如下命令：

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --need-credential=false

例如：

bmctl push images \
    --source bmpackages_1.31.300-gke.81.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --need-credential=false.

调整线程数

由于图片软件包 tar 文件中的容器映像大小和数量，图片上传常规操作可能需要很长时间。增加并行线程的数量可加快例程的运行速度。您可以使用 --threads 标志更改 bmctl push images 使用的并行线程数量。

默认情况下，图片上传程序使用 4 个线程。如果图片上传时间过长，请提高此值。作为基准，在 Google 测试环境中，使用 8 个并行线程从配备 4 个 CPU 的工作站上传图片大约需要 10 分钟。

bmctl push images \
    --source IMAGES_TAR_FILE_PATH \
    --private-registry REGISTRY_IP:PORT \
    --cacert CERT_PATH \
    --threads NUM_THREADS

将 NUM_THREADS 替换为用于处理图片上传的并行线程数。默认情况下，bmctl push images 使用四个并行线程。

以下命令会将上传线程数从 4 增加到 8，以缩短上传时间：

bmctl push images \
    --source bmpackages_1.31.300-gke.81.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --cacert ~/cert.pem \
    --threads 8

通过代理上传

如果您需要使用代理来将映像从工作站上传到注册表服务器，可以在 bmctl 命令之前添加代理详细信息：

HTTPS_PROXY=http://PROXY_IP:PORT bmctl push images \
    --source=IMAGES_TAR_FILE_PATH \
    --private-registry=REGISTRY_IP:PORT \
    --cacert=CERT_PATH

替换以下内容：

• PROXY_IP:PORT：代理的 IP 地址和端口。

• IMAGES_TAR_FILE_PATH：下载的映像软件包 tar 文件的路径，例如 bmpackages_1.31.300-gke.81.tar.xz。

• REGISTRY_IP:PORT：私有注册表服务器的 IP 地址和端口。

• CERT_PATH：CA 证书文件的路径（如果您的注册表服务器使用专用 TLS 证书）。

出现提示时，输入您的用户名和密码，或选择 Docker 配置文件。

以下命令会通过代理上传图片：

HTTPS_PROXY=http://10.128.0.136:3128 bmctl push images \
    --source bmpackages_1.31.300-gke.81.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --cacert ~/cert.pem

将 bmctl push images 与您自己的命名空间搭配使用

如果您想要在注册表服务器中使用您自己的命名空间（而非根命名空间），则可在集群配置文件的 registryMirrors.endpoint 字段中提供您的私有注册表的 API 端点，以便 containerd 可以从此命名空间执行拉取。端点通常采用 <REGISTRY_IP:PORT>/v2/<NAMESPACE> 格式。请参阅私有注册表用户指南，以了解具体详情。如需了解详情，请参阅关于在注册表端点中使用 v2。

bmctl push images \
    --source=IMAGES_TAR_FILE_PATH \
    --private-registry=REGISTRY_IP:PORT/NAMESPACE \
    --cacert=CERT_PATH

将 NAMESPACE 替换为您要将图片上传到的注册表服务器中的命名空间的名称。

例如，如果您只拥有 198.51.20:5000/test-namespace/ 的访问权限，则可以使用如下所示的命令上传 test-namespace 命名空间下的所有映像：

bmctl push images \
    --source=./bmpackages_1.31.300-gke.81.tar.xz \
    --private-registry=198.51.20:5000/test-namespace \
    --username=alex \
    --password=pa55w0rd \
    --cacert /etc/pki/tls/certs/ca-bundle.crt

然后，在集群配置文件中，添加以下内容，以便 containerd 从 test-namespace 命名空间执行拉取：

registryMirrors:
  - endpoint: https://198.51.20:5000/v2/test-namespace

如需详细了解 bmctl push images 命令，请参阅 bmctl 命令参考文档。

将集群配置为使用注册表镜像

您可以在创建集群时或每次更新现有集群时为集群配置注册表镜像。您使用的配置方法取决于集群类型，对于用户集群，还取决于您是创建集群还是更新集群。以下两个部分介绍了配置注册表镜像的两种方法。

在集群配置文件中使用标头部分

借助 Google Distributed Cloud，您可以在集群配置文件的标头部分（而非集群规范）中指定注册表镜像：

• 对于管理员集群、混合集群和独立集群，配置注册表镜像的唯一方法是使用集群配置文件中的标头部分。此方法适用于集群创建或集群更新。

• 对于用户集群，您只能在创建集群期间使用此方法配置注册表镜像。或者，如需为现有用户集群配置注册表镜像，您可以使用集群规范中的 nodeConfig.registryMirrors 部分。

以下示例集群配置文件指定从端点为 https://198.51.20:5000 的本地注册表镜像中拉取映像。以下部分会介绍在此配置文件开头出现的一些字段。

# Sample cluster config with registry mirror:
---
gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
sshPrivateKeyPath: /root/ssh-key/id_rsa
registryMirrors:
  - endpoint: https://198.51.20:5000
    caCertPath: /root/ca.crt
    pullCredentialConfigPath: /root/.docker/config.json
    hosts:
      - somehost.io
      - otherhost.io
---
apiVersion: v1
kind: Namespace
metadata:
  name: cluster-admin1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
  name: admin1
  namespace: cluster-admin1
spec:
  nodeConfig:
    containerRuntime: containerd
...

使用集群规范中的 nodeConfig.registryMirrors 部分

这种创建或更新注册表镜像的方法仅适用于用户集群。由于您可以与用户集群共享为管理集群创建的 Secret，因此您可以使用管理员集群或混合集群中的 nodeConfig.registryMirrors 在用户集群的集群规范中指定注册表镜像。

如需将用户集群配置为使用与管理员集群相同的注册表镜像，请按以下步骤操作：

1. 从管理员集群资源的 nodeConfig.registryMirrors 中获取 nodeConfig.registryMirror 部分（包括 Secret 引用）：

   kubectl get cluster CLUSTER_NAME -n CLUSTER_NAMESPACE \
       --kubeconfig ADMIN_KUBECONFIG \
       -o yaml
   

   替换以下内容：

   • CLUSTER_NAME：管理用户集群的管理员集群或混合集群的名称。

   • CLUSTER_NAMESPACE：管理集群的命名空间名称。

   • ADMIN_KUBECONFIG：管理集群的 kubeconfig 文件的路径。

2. 将管理员集群中的 nodeConfig.registryMirrors 配置添加到用户集群的集群配置文件中。

   用户集群配置文件中的 registryMirrors 部分应类似于以下示例：

   ---
   gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
   sshPrivateKeyPath: /root/ssh-key/id_rsa
   ---
   apiVersion: v1
   kind: Namespace
   metadata:
     name: cluster-user1
   ---
   apiVersion: baremetal.cluster.gke.io/v1
   kind: Cluster
   metadata:
     name: user1
     namespace: cluster-user1
   spec:
     nodeConfig:
       containerRuntime: containerd
       registryMirrors:
       -   caCertSecretRef:
           name: the-secret-created-for-the-admin-cluster
           namespace: anthos-creds
         endpoint: https://172.18.0.20:5000
         hosts:
           -   somehost.io
           -   otherhost.io
         pullCredentialSecretRef:
           name: the-image-pull-creds-created-for-the-admin-cluster
           namespace: anthos-creds
   ...
   

如需对用户集群的注册表镜像配置进行后续更改，请修改用户集群配置文件中的 nodeConfig.registryMirrors，然后使用 bmctl update 应用更改。

您无法使用集群配置文件的标头部分更新用户集群的注册表镜像配置。

hosts 字段

containerd 会检查集群配置文件的 hosts 部分，以发现具有本地镜像的主机。这些主机会映射到集群配置文件 (registryMirror.endpoint) 中指定的注册表镜像端点。在上一部分的示例配置文件中，hosts 部分中列出的公共注册表是 somehost.io 和 otherhost.io。由于这些公共注册表显示在 hosts 部分中，因此 containerd 在遇到来自 somehost.io 或 otherhost.io 的映像拉取请求时，会先检查私有注册表镜像。

例如，假设 containerd 收到针对 somehost.io/kubernetes-e2e-test-images/nautilus:1.0 的拉取命令。由于 somehost.io 在集群配置文件的 hosts 部分中被列作主机之一，因此 containerd 会在本地注册表镜像中查找 kubernetes-e2e-test-images/nautilus:1.0 映像。如果 somehost.io 未在 hosts 部分中列出，则 containerd 不知道存在 somehost.io 的本地镜像。在这种情况下，containerd 不会检查映像的镜像，而是从 somehost.io 公共注册表中拉取映像。

请注意，默认情况下，Google Distributed Cloud 会自动镜像 gcr.io 中的映像，因此您无需在 hosts 部分中将 gcr.io 列为主机。

hosts 值和 endpoint 值不应重叠。例如，以下配置示例显示了与端点值的域名部分匹配的主机 europe-docker.pkg.dev。在这种情况下，您无需指定 hosts 值：

...
registryMirrors:
  ...
  endpoint: https://europe-docker.pkg.dev:5000/v2/cloud-data-fusion-images
  hosts:
    - europe-docker.pkg.dev
    ...

gcrKeyPath 字段

如果您希望 Google Distributed Cloud 自动使用 Container Registry (gcr.io) 拉取本地注册表中未显示的映像，则必须指定 Container Registry 服务账号密钥的路径。Google Distributed Cloud 没有为其他公共注册表提供密钥的机制。

如果您不打算使用在本地注册表中未显示映像时从 gcr.io 中拉取映像的功能，则无需将 gcrKeyPath 添加到集群配置文件。

caCertPath 字段

如果您的仓库需要私有传输层安全协议 (TLS) 证书，则此字段会使用服务器根 CA 证书文件的路径。此证书文件应位于管理员工作站上，即运行 bmctl 命令的机器。如果您的仓库不需要私有 TLS 证书，则可以将 caCertPath 字段留空。

pullCredentialConfigPath 字段

如果您的注册表服务器不需要身份验证 Docker 配置文件，则可以将 pullCredentialConfigPath 字段留空。 请注意，这是运行 bmctl 命令的机器上的配置文件的路径。

将注册表镜像与用户集群搭配使用

如果管理员集群已配置为自动从注册表镜像中拉取映像，则用户集群不会自动从注册表镜像中拉取映像。如需让用户集群从注册表镜像中拉取映像，您需要按照将集群配置为使用注册表镜像中的说明单独配置用户集群。

更新注册表镜像端点、证书和拉取凭据

如需更新注册表镜像端点、证书或拉取凭据，请执行以下操作：

1. 在集群配置文件中，更新端点、CA 证书文件和拉取凭据配置文件路径。

2. 通过运行以下命令来应用更改：

   bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG
   

   替换以下内容：

   • 将 CLUSTER_NAME 替换为要更新的集群的名称。

   • 将 ADMIN_KUBECONFIG 替换为管理员集群配置文件的路径。

验证映像是否是从注册表镜像中拉取的

可以通过检查 config.toml 文件的内容来确定 containerd 是否从本地注册表拉取映像，如以下步骤所示：

1. 登录节点并检查以下文件的内容：/etc/containerd/config.toml

2. 检查 config.toml 文件的 plugins."io.containerd.grpc.v1.cri".registry.mirrors 部分，查看您的注册表服务器是否列在 endpoint 字段中。以下摘录自示例 config.toml 文件，其中 endpoint 字段以粗体显示：

   version = 2
   root = "/var/lib/containerd"
   state = "/run/containerd"
   ...
   [plugins."io.containerd.grpc.v1.cri".registry]
     [plugins."io.containerd.grpc.v1.cri".registry.configs]
       [plugins."io.containerd.grpc.v1.cri".registry.configs."gcr.io"]
         [plugins."io.containerd.grpc.v1.cri".registry.configs."privateregistry2.io".tls]
           ca_file = '/etc/containerd/certs.d/privateregistry2.io/ca.crt'
     [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
       [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
         endpoint = ["http://privateregistry.io", "http://privateregistry2.io"]
   ...
   

   如果您的注册表镜像显示在 endpoint 字段中，则该节点会从注册表镜像中拉取映像，而不是从公共注册表中拉取映像。

排查注册表镜像设置问题

您可以使用容器运行时界面命令行工具 crictl 下载单个映像文件，以测试您的注册表设置。每个图片文件都会单独标记一个有意义的版本字符串。例如，集群 API 控制器映像会标记为 Google Distributed Cloud 版本，etcd 映像会标记为相应的 etcd 版本。

对于适用于裸机的 Google Distributed Cloud 1.31.200-gke.59 版，集群 API 控制器映像 cluster-api-controller 和 etcd 映像 etcd 具有以下标记：

• cluster-api-controller:1.31.200-gke.59
• etcd:v3.4.30-0-gke.1

从注册表镜像中拉取映像

如果您的注册表镜像不使用命名空间，请使用以下命令拉取映像：

crictl pull REGISTRY_IP:PORT/IMAGE_PATH:IMAGE_TAG

从使用命名空间的注册表镜像中拉取映像

如果您的注册表镜像使用命名空间，请使用以下命令拉取映像：

crictl pull REGISTRY_IP:PORT/NAMESPACE/IMAGE_PATH:IMAGE_TAG

关于在注册表端点中使用 v2

如果您的注册表使用自定义命名空间，您必须在集群配置文件中注册表端点 (registryMirror.endpoint) 的命名空间前面添加 v2/。如果您不使用命名空间，请勿使用 v2。无论采用何种方式，请勿在 --private-registry 标志值或映像拉取命令中使用 v2：

不使用命名空间

• 有效：
  • endpoint: https://172.18.0.20:5000
  • crictl pull 172.18.0.20:5000/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
• 无效：
  • endpoint: https://172.18.0.20:5000/v2
  • crictl pull 172.18.0.20:5000/v2/anthos-baremetal-release/etcd:v3.4.30-0-gke.1

使用命名空间

• 有效：
  • endpoint: https://172.18.0.21:5000/v2/namespace
  • crictl 172.18.0.21:5000/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
• 无效：
  • endpoint: https://172.18.0.21:5000/namespace
  • crictl pull 172.18.0.21:5000/v2/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1