3.5. 使用 oc-mirror 插件 v2 为断开连接的安装 mirror 镜像

1. 创建镜像设置配置文件。

2. 使用以下工作流之一将镜像设置为目标镜像 registry：

   • 将镜像直接设置为目标镜像 registry (mirror 到 mirror)。
   • 将镜像设置为 disk (mirror to disk)，将 tar 文件传送到目标环境，然后将镜像设置为目标镜像 registry （disk to mirror)。
3. 配置集群以使用 oc-mirror 插件 v2 生成的资源。
4. 根据需要重复这些步骤以更新目标镜像 registry。

流程

1. 下载 oc-mirror CLI 插件：

   1. 进入到 Red Hat Hybrid Cloud Console 的 Downloads 页。
   2. 在 OpenShift disconnected installation tools 部分中，从下拉菜单中选择 OpenShift Client (oc) mirror plugin 的OS type 和 Architecture type。
   3. 点 Download 保存文件。

2. 运行以下命令来提取存档：

   $ tar xvzf oc-mirror.tar.gz

3. 如有必要，运行以下命令来将插件文件更新为可执行：

   $ chmod +x oc-mirror

   注意

   不要重命名 oc-mirror 文件。

4. 运行以下命令，将文件放在 PATH 中（如 /usr/local/bin ）来安装 oc-mirror CLI 插件：

   $ sudo mv oc-mirror /usr/local/bin/.

1. 从 Red Hat OpenShift Cluster Manager 下载 registry.redhat.io pull secret。

2. 运行以下命令，以 JSON 格式生成 pull secret 副本：

   $ cat ./pull-secret | jq . > <path>/<pull_secret_file_in_json> 1

   1

   指定到存储 pull secret 的文件夹的路径，以及您创建的 JSON 文件的名称。

   pull secret 示例

   {
     "auths": {
       "cloud.openshift.com": {
         "auth": "b3BlbnNo...",
         "email": "you@example.com"
       },
       "quay.io": {
         "auth": "b3BlbnNo...",
         "email": "you@example.com"
       },
       "registry.connect.redhat.com": {
         "auth": "NTE3Njg5Nj...",
         "email": "you@example.com"
       },
       "registry.redhat.io": {
         "auth": "NTE3Njg5Nj...",
         "email": "you@example.com"
       }
     }
   }

3. 如果 $XDG_RUNTIME_DIR/containers 目录不存在，请输入以下命令来创建：

   $ mkdir -p $XDG_RUNTIME_DIR/containers

4. 将 pull secret 文件保存为 $XDG_RUNTIME_DIR/containers/auth.json。

5. 运行以下命令，为您的镜像 registry 生成 base64 编码的用户名和密码或令牌：

   $ echo -n '<user_name>:<password>' | base64 -w0 1

   1

   通过 <user_name> 和 <password> 指定 registry 的用户名和密码。

   输出示例

   BGVtbYk3ZHAtqXs=

6. 编辑 JSON 文件并添加描述 registry 的部分：

     "auths": {
       "<mirror_registry>": { 1
         "auth": "<credentials>", 2
         "email": "you@example.com"
       }
     },

   1

   指定 registry 域名，以及您的镜像 registry 用来提供内容的可选端口。例如：registry.example.com 或 registry.example.com:8443

   2

   指定镜像 registry 的 base64 编码用户名和密码。

   修改的 pull secret 示例

   {
     "auths": {
       "registry.example.com": {
         "auth": "BGVtbYk3ZHAtqXs=",
         "email": "you@example.com"
       },
       "cloud.openshift.com": {
         "auth": "b3BlbnNo...",
         "email": "you@example.com"
       },
       "quay.io": {
         "auth": "b3BlbnNo...",
         "email": "you@example.com"
       },
       "registry.connect.redhat.com": {
         "auth": "NTE3Njg5Nj...",
         "email": "you@example.com"
       },
       "registry.redhat.io": {
         "auth": "NTE3Njg5Nj...",
         "email": "you@example.com"
       }
     }
   }

验证

1. 进入 <file_path> 目录中生成的 working-dir/cluster-resources 目录。
2. 验证 ImageDigestMirrorSet、ImageTagMirrorSet 和 CatalogSource 资源是否存在 YAML 文件。

1. Mirror to disk ：将镜像集 mirror 到一个存档。
2. Disk transfer ：手动将存档传输到断开连接的镜像 registry 的网络。
3. Disk to mirror: 将存档中的镜像集 mirror 到目标断开连接的 registry。

流程

1. 以具有 cluster-admin 角色的用户身份登录 OpenShift CLI。

2. 运行以下命令，将结果目录中的 YAML 文件应用到集群：

   $ oc apply -f <path_to_oc_mirror_workspace>/working-dir/cluster-resources

验证

1. 运行以下命令验证 ImageDigestMirrorSet 资源是否已成功安装：

   $ oc get imagedigestmirrorset

2. 运行以下命令验证 ImageTagMirrorSet 资源是否已成功安装：

   $ oc get imagetagmirrorset

3. 运行以下命令验证 CatalogSource 资源是否已成功安装：

   $ oc get catalogsource -n openshift-marketplace

流程

1. 创建一个 delete-image-set-config.yaml 文件，并包含以下内容：

   DeleteImageSetConfiguration 文件

   apiVersion: mirror.openshift.io/v2alpha1
   kind: DeleteImageSetConfiguration
   delete:
     platform:
       channels:
         - name: <channel_name> 1
           minVersion: <channel_min_version> 2
           maxVersion: <channel_max_version> 3
     operators:
       - catalog: <operator_catalog_name> 4
         packages:
         - name: <operator_name> 5
            minVersion: <operator_max_version> 6
            maxVersion: <operator_min_version> 7
     additionalImages:
       - name: <additional_images> 8

   1 1

   指定要删除的 OpenShift Container Platform 频道的名称，如 stable-4.15。

   2 3

   指定要在频道中删除的镜像版本范围，例如，4.15.0 为最小版本，4.15.1 为最大版本。要只删除一个版本的镜像，在 minVersion 和 maxVersion 字段中都使用要删除的版本号。

   4

   指定要删除的 Operator 目录镜像，如 registry.redhat.io/redhat/redhat-operator-index:v4.14。要删除目录镜像，您必须使用 delete.operators.packages 参数指定独立的 Operator。

   5

   指定要删除的特定 Operator 捆绑包，如 aws-load-balancer-operator。如果指定了单独的 Operator，Operator 目录镜像不会被删除。

   6 7

   指定为 Operator 删除的镜像版本范围，如最小版本为 0.0.1，最大版本为0.0.2。要只删除一个版本的镜像，在 minVersion 和 maxVersion 字段中都使用要删除的版本号。

   8

   指定要删除的额外镜像，如 registry.redhat.io/ubi9/ubi-init:latest。

2. 运行以下命令，创建一个 delete-images.yaml 文件：

   $ oc mirror delete --config delete-image-set-config.yaml --workspace file://<previously_mirrored_work_folder> --v2 --generate docker://<remote_registry>

   其中：

   <previously_mirrored_work_folder>

   指定镜像以前被 mirror 到的或在 mirror 过程中存储镜像的目录。

   <remote_registry>

   指定将从中删除镜像的远程容器 registry 的 URL 或地址。

3. 进入创建的 <previously_mirrored_work_folder>/delete 目录。
4. 验证 delete-images.yaml 文件是否已生成。
5. 手工确保文件中列出的每个镜像不再被集群需要，可以安全地从 registry 中删除。

6. 生成 delete-images YAML 文件后，运行以下命令来从远程 registry 中删除镜像：

   $ oc mirror delete --v2 --delete-yaml-file <previously_mirrored_work_folder>/working-dir/delete/delete-images.yaml docker://<remote_registry>

   其中：

   <previously_mirrored_work_folder>

   指定镜像以前被 mirror 到的或在 mirror 过程中存储镜像的目录。

   <remote_registry>

   指定将从中删除镜像的远程容器 registry 的 URL 或地址。

   重要

   当使用 mirror-to-mirror 方法 mirror 镜像时，镜像不会在本地缓存，因此您无法从本地缓存中删除镜像。

验证

1. 进入生成的工作区目录：

   $ cd <oc_mirror_workspace_path>

2. 检查生成的 mapping.txt 和 missing.txt 文件。这些文件包含将要镜像的所有镜像的列表。

流程

1. 检查与服务器相关的问题：

   错误示例

   [ERROR]  : [Worker] error mirroring image localhost:55000/openshift/graph-image:latest error: copying image 1/4 from manifest list: trying to reuse blob sha256:edab65b863aead24e3ed77cea194b6562143049a9307cd48f86b542db9eecb6e at destination: pinging container registry localhost:5000: Get "https://localhost:5000/v2/": http: server gave HTTP response to HTTPS client

   1. 在 oc-mirror 插件 v2 输出目录中，打开 working-dir/logs 文件夹中的 mirroring_error_date_time.log 文件。
   2. 查找表示服务器端问题的错误消息，如 HTTP 500 错误、令牌过期或超时。
   3. 如果问题仍然存在，请重试镜像过程或联系技术支持。

2. 检查对 Operator 进行镜像的过程不完整：

   错误示例

   error mirroring image docker://registry.redhat.io/3scale-amp2/zync-rhel9@sha256:8bb6b31e108d67476cc62622f20ff8db34efae5d58014de9502336fcc479d86d (Operator bundles: [3scale-operator.v0.11.12] - Operators: [3scale-operator]) error: initializing source docker://localhost:55000/3scale-amp2/zync-rhel9:8bb6b31e108d67476cc62622f20ff8db34efae5d58014de9502336fcc479d86d: reading manifest 8bb6b31e108d67476cc62622f20ff8db34efae5d58014de9502336fcc479d86d in localhost:55000/3scale-amp2/zync-rhel9: manifest unknown
   error mirroring image docker://registry.redhat.io/3scale-amp2/3scale-rhel7-operator-metadata@sha256:de0a70d1263a6a596d28bf376158056631afd0b6159865008a7263a8e9bf0c7d error: skipping operator bundle docker://registry.redhat.io/3scale-amp2/3scale-rhel7-operator-metadata@sha256:de0a70d1263a6a596d28bf376158056631afd0b6159865008a7263a8e9bf0c7d because one of its related images failed to mirror
   error mirroring image docker://registry.redhat.io/3scale-amp2/system-rhel7@sha256:fe77272021867cc6b6d5d0c9bd06c99d4024ad53f1ab94ec0ab69d0fda74588e (Operator bundles: [3scale-operator.v0.11.12] - Operators: [3scale-operator]) error: initializing source docker://localhost:55000/3scale-amp2/system-rhel7:fe77272021867cc6b6d5d0c9bd06c99d4024ad53f1ab94ec0ab69d0fda74588e: reading manifest fe77272021867cc6b6d5d0c9bd06c99d4024ad53f1ab94ec0ab69d0fda74588e in localhost:55000/3scale-amp2/system-rhel7: manifest unknown

   1. 在控制台或日志文件中检查相关的警告，以了解哪些 Operator 不完整。

      如果一个 Operator 被标记为不完整，与该 Operator 相关的镜像可能会无法镜像 (mirror)。

   2. 手动镜像（mirror）缺少的镜像或重试镜像 (mirror) 的过程。

3. 检查与生成的集群资源相关的错误。即使无法镜像（mirror）某些镜像，oc-mirror v2 仍会为已成功镜像（mirror）的镜像生成集群资源，如 IDMS.yaml 和 ITMS.yaml 文件。

   1. 在输出目录中检查生成的文件。
   2. 如果特定镜像缺少了这些文件，请确保在镜像（mirror）过程中没有发生关键错误。

1. 用户执行 oc-mirror 插件 v2，将在线 registry 的内容镜像到本地磁盘目录。
2. 镜像内容保存到磁盘中，用于在离线环境中使用。

流程

1. 在断开连接的环境中运行 oc-mirror 插件 v2 之前，请创建一个 registry.conf 文件。该文件的 TOML 格式如下所述：

   注意

   建议将文件存储在 $HOME/.config/containers/registries.conf 或 /etc/containers/registries.conf 下。

   registry.conf 示例

   [[registry]]
   location="registry.redhat.io"
   [[registry.mirror]]
   location="<enterprise-registry.in>"
   
   [[registry]]
   location="quay.io"
   [[registry.mirror]]
   location="<enterprise-registry.in>"

2. 生成镜像存档。

   1. 要将所有 OpenShift Container Platform 内容收集到磁盘的一个归档中（<file_path>/enterprise-content），请运行以下命令：

      $ oc mirror --v2 -c isc.yaml file://<file_path>/enterprise-content

      isc.yaml 示例

      apiVersion: mirror.openshift.io/v2alpha1
      kind: ImageSetConfiguration
      mirror:
        platform:
          architectures:
            - "amd64"
          channels:
            - name: stable-4.15
              minVersion: 4.15.0
              maxVersion: 4.15.3

      生成存档后，它将传送到断开连接的环境中。传输机制不是 oc-mirror 插件 v2 的一部分。企业网络管理员需要负责制定传输策略。

      在某些情况下，传输是手动完成的，例如在一个没有网络连接的环境中，将磁盘从一个物理机器中拔出，并插入到另外一个系统。在其他情况下，使用安全文件传输协议 (SFTP) 或其他协议。

3. 完成存档传输后，您可以再次执行 oc-mirror 插件 v2，以便将相关存档内容镜像到 registry (在示例中是 entrerpise_registry.in)，如下例所示：

   $ oc mirror --v2 -c isc.yaml --from file://<disconnected_environment_file_path>/enterprise-content docker://<enterprise_registry.in>/

   其中：

   • --from 指向包含存档的文件夹。它以 file:// 开头。
   • docker:// 是镜像 (mirror) 的目的地，这是最后的参数。因为它是一个 docker registry。
   • -c (--config)是一个强制参数。它可让 oc-mirror 插件 v2 最终仅将存档的子部分镜像到 registry。一个存档可能包含几个 OpenShift Container Platform 版本，但断开连接的环境或 enclave 可能只镜像几个。

4. 准备 imageSetConfig YAML 文件，该文件描述了要镜像到 enclave 的内容：

   示例 isc-enclave.yaml

   apiVersion: mirror.openshift.io/v2alpha1
   kind: ImageSetConfiguration
   mirror:
     platform:
       architectures:
         - "amd64"
       channels:
         - name: stable-4.15
           minVersion: 4.15.2
           maxVersion: 4.15.2

   您必须在可访问断开连接的 registry 的机器上运行 oc-mirror 插件 v2。在上例中，可以访问断开连接的环境 enterprise-registry.in。

5. 更新图形 URL

   如果您使用 graph:true，oc-mirror 插件 v2 会尝试访问 cincinnati API 端点。由于此环境断开连接，因此请务必导出环境变量 UPDATE_URL_OVERRIDE，以引用 OpenShift Update Service (OSUS)的 URL：

   $ export UPDATE_URL_OVERRIDE=https://<osus.enterprise.in>/graph

   有关在 OpenShift 集群上设置 OSUS 的更多信息，请参阅"使用 OpenShift Update Service 在断开连接的环境中更新集群"。

   注意

   当在 OpenShift Container Platform 延长更新支持 (EUS) 版本间进行更新时，还需要包括在当前版本和目标版本间的中间次版本的镜像。oc-mirror 插件 v2 可能并不总是自动检测此要求，因此请检查 Red Hat OpenShift Container Platform Update Graph 页以确认包括了所需的中间版本。

   使用 Update Graph 页查找应用程序推荐的中间次版本，在使用 oc-mirror 插件 v2 时，在 ImageSetConfiguration 文件中包括这些版本。

6. 为 enclave 从企业 registry 中生成镜像存档。

   要为 enclave1 准备存档，用户使用针对那个 enclave 专用的 imageSetConfiguration 在企业断开连接的环境中执行 oc-mirror 插件 v2。这样可确保仅镜像 enclave 需要的镜像：

   $ oc mirror --v2 -c isc-enclave.yaml
   file:///disk-enc1/

   此操作将所有 OpenShift Container Platform 内容收集到存档中，并在磁盘上生成存档。

7. 生成存档后，它将传送到 enclave1 网络。传输机制不是 oc-mirror 插件 v2 的责任。

8. 将内容镜像到 enclave registry

   完成存档传输后，用户可以再次执行 oc-mirror 插件 v2，以便将相关存档内容镜像到 registry。

   $ oc mirror --v2 -c isc-enclave.yaml --from file://local-disk docker://registry.enc1.in

   enclave1 中的 OpenShift Container Platform 集群的管理员现在可以安装或升级该集群。