使用 mirror-registry 创建镜像 registry

强烈建议使用组织提供的镜像 registry 作为 平台镜像 registry。如果已有镜像 registry,请跳过本章,继续执行准备目标版本负载。

如果没有可用的镜像 registry,可以使用 mirror-registry。mirror-registry 是一个小规模镜像 registry,可作为 平台镜像的目标 registry。

重要

mirror-registry 不能替代生产级、高可用的镜像 registry。

前提条件

  • 一台位于所有 集群外部的机器。不要使用任何 集群的节点。
  • 已安装 systemd 和 OpenSSL 的 Linux。必须能够以 root 身份运行命令。
  • 4 个或更多 vCPU。
  • 8 GB 或更多 RAM。
  • 本地磁盘或兼容 S3 的对象存储。使用本地磁盘时,存储数据目录的文件系统至少需要 200 GB。建议使用 LVM,以便之后扩展存储。请参阅使用本地存储部署。
  • 安装节点以及拉取平台镜像的每个集群节点都可以访问 registry 端口(默认为 443)。
重要

存储要求取决于您的环境。例如,保留多个版本或多个 CPU 架构时需要更多空间。使用本地磁盘时,请监控已上传镜像所使用的存储空间。

关于 mirror-registry

部署 需要一个用于存储 平台组件镜像的镜像 registry。平台的安装和后续升级都依赖此 registry。如果您可以提供镜像 registry 作为 平台镜像 registry,则不需要 mirror-registry。

如果没有可用的镜像 registry,可以使用 mirror-registry。mirror-registry 是随 提供的小规模镜像 registry,可在 Core Package 下载页面获取。它基于原生 Distribution registry,作为由 systemd 管理的单个实例运行,并且只能通过 HTTPS 访问。默认情况下,它侦听端口 443,使用本地存储和自动生成的自签名证书。部署时必须配置凭据。可选设置包括端口、自定义 TLS 证书和兼容 S3 的对象存储。

mirror-registry 的限制

以下限制适用于 mirror-registry:

  • mirror-registry 不是高可用 registry。使用兼容 S3 的对象存储时,镜像数据存储在机器外部,但 registry 服务仍为单个实例。mirror-registry 不能替代生产级、高可用的镜像 registry。
  • 不建议在生产环境中使用 mirror-registry。它是单点镜像 registry。如果它停止运行,调度到其他节点的 Pod 可能无法启动,因为无法拉取镜像,从而影响平台可用性。
  • mirror-registry 仅支持托管 平台镜像。
  • 用户构建的内容(包括应用镜像)不应托管在 mirror-registry 中。
  • 不建议在多个集群之间共享 mirror-registry,因为这些集群随后会依赖同一 registry,在更新集群时会产生单点故障。对于多个集群,请使用组织提供的生产级、高可用镜像 registry。

安装 mirror-registry

此操作步骤会在本地计算机上安装 mirror-registry 并启动镜像 registry。该 registry 默认侦听端口 443,用于存储 平台镜像。

注意

安装会对计算机进行以下更改:创建 /opt/mirror-registry 目录,其中包含二进制文件、配置和本地存储;创建 mirror-registry systemd 服务,该服务会在启动时运行。安装脚本不会更改防火墙规则。

支持的标志

以下标志适用于 install 和 upgrade 命令。默认值适用于首次安装。当您再次运行 install 或运行 upgrade 时,未指定的标志会保留其现有配置。

常规标志

标志描述
--listen在所有接口的所有 IPv4 和 IPv6 地址上侦听的端口。如果端口不是 443,则在访问 registry 和指定 registry 地址时必须包含该端口。默认为 443。
--auth-file凭据文件的路径。第 1 行是用户名,第 2 行是密码。无默认值。首次安装时必需。
--tls-certTLS 证书的路径,包括完整证书链。与 --tls-key 一起指定。默认为自动生成的自签名证书。
--tls-keyTLS 私钥的路径。与 --tls-cert 一起指定。默认为自动生成的私钥。
--regen-cert重新生成自签名证书。默认为保留现有证书。

存储标志

标志描述
--storage存储类型,即 filesystem 或 s3,安装后无法更改。默认为 filesystem。
--data-dir本地存储的镜像数据目录,必须为绝对路径。不能与 --storage s3 一起使用。默认为 /opt/mirror-registry/data。
--s3-endpointS3 兼容服务的地址,不包含 bucket 名称或路径。与 --storage s3 一起使用时必需。如果没有 scheme,则使用 https://。无默认值。
--s3-regionbucket 的地域。与 --storage s3 一起使用时必需。无默认值。
--s3-bucketbucket 的名称,该 bucket 必须已存在。与 --storage s3 一起使用时必需。无默认值。
--s3-credentials-fileS3 凭据文件的路径。第 1 行是访问密钥,第 2 行是秘密密钥。默认为没有凭据文件。
--s3-root-dirbucket 内的路径前缀,只能包含字母、数字、.、_、- 和 /。默认为 bucket 根目录。

准备软件包和凭据

  1. 从 Customer Portal 中的 Core Package 下载页面 下载与计算机架构匹配的 mirror-registry-<version>.<arch>.tar.gz 软件包,并将其解压:

    tar xzf mirror-registry-<version>.<arch>.tar.gz
    cd mirror-registry-<version>.<arch>
  2. 创建凭据文件。第 1 行是用户名,第 2 行是密码:

    {
      read -rp "Registry username: " USERNAME
      read -rsp "Registry password: " PASSWORD; printf '\n'
      (umask 077; printf '%s\n%s\n' "$USERNAME" "$PASSWORD" > /root/registry.auth)
      unset USERNAME PASSWORD
    }

    用户名不能包含空格或 :,密码最多为 72 个字节。安装完成后可以删除此文件。

使用本地存储部署

要使用默认数据目录 /opt/mirror-registry/data,请确保其文件系统至少有 200 GB 空间,然后运行:

./mirror-registry install --auth-file /root/registry.auth

要将数据存储在专用数据磁盘上,请使用 LVM 准备磁盘,然后使用 --data-dir 安装 mirror-registry:

  1. 在数据磁盘上创建逻辑卷并将其挂载。以下示例使用空磁盘 /dev/vdb,并创建专用卷组 vg_registry,而不是重复使用系统磁盘的卷组,这样镜像数据就不会与根文件系统共享空间。这些命令会擦除磁盘上的所有数据,并且需要 lvm2 软件包。请根据您的环境替换设备名称和挂载点。挂载点必须位于可写路径上。

    pvcreate /dev/vdb
    vgcreate vg_registry /dev/vdb
    lvcreate -l 100%FREE -n lv_data vg_registry
    mkfs.xfs /dev/vg_registry/lv_data
    mkdir -p /cpaas/registry
    echo "UUID=$(blkid -s UUID -o value /dev/vg_registry/lv_data) /cpaas/registry xfs defaults 0 0" >> /etc/fstab
    systemctl daemon-reload
    mount -a
    df -h /cpaas/registry

    df 的输出显示已挂载到 /cpaas/registry 的逻辑卷。/etc/fstab 条目会在重新启动后自动挂载该逻辑卷。

  2. 将挂载点作为数据目录安装 mirror-registry。以下示例还会更改侦听端口:

    ./mirror-registry install \
      --auth-file /root/registry.auth \
      --data-dir /cpaas/registry \
      --listen 8443

要稍后扩展存储,请添加磁盘(例如 /dev/vdc)到卷组,然后扩展逻辑卷及其文件系统:

pvcreate /dev/vdc
vgextend vg_registry /dev/vdc
lvextend -r -l +100%FREE /dev/vg_registry/lv_data

使用兼容 S3 的对象存储部署

  1. 在 S3 服务上创建 bucket,并准备一个可以在该 bucket 中列出、读取、写入和删除对象以及执行分段上传的访问密钥。脚本不会创建 bucket。bucket 内的路径不需要预先存在。

  2. 创建 S3 凭据文件。第 1 行是访问密钥,第 2 行是秘密密钥:

    {
      read -rp "S3 access key: " S3_ACCESS_KEY
      read -rsp "S3 secret key: " S3_SECRET_KEY; printf '\n'
      (umask 077; printf '%s\n%s\n' "$S3_ACCESS_KEY" "$S3_SECRET_KEY" > /root/s3.cred)
      unset S3_ACCESS_KEY S3_SECRET_KEY
    }
  3. 根据您的存储设置 --s3-endpoint 和 --s3-region:

    存储--s3-endpoint--s3-region
    MinIOhttps://<address>:9000us-east-1
    Ceph RGWhttps://<address>:<RGW-port>us-east-1
    AWS S3https://s3.<region>.amazonaws.combucket 的地域
  4. 安装 mirror-registry:

    ./mirror-registry install \
      --auth-file /root/registry.auth \
      --storage s3 \
      --s3-endpoint https://minio.example.com:9000 \
      --s3-region us-east-1 \
      --s3-bucket registry \
      --s3-credentials-file /root/s3.cred

    如果 bucket 中包含其他内容,请添加 --s3-root-dir mirror/registry,以将数据存储在 bucket 内的路径下。

    安装结束时,脚本会检查 S3 连接。如果出现 S3 check failed,请检查端点、bucket 名称、地域和密钥。

验证部署

  1. 确认 registry 可用:

    ./mirror-registry status
    curl -k -u <username> https://localhost/v2/_catalog

    新 registry 会返回 {"repositories":[]}。如果更改了端口,请将其添加到 URL 中。

  2. 继续执行准备目标版本负载,将平台镜像上传到此 registry。将 registry 地址设置为 <host-or-IPv4>[:port]。如果 registry 使用 IPv6,请使用域名。 使用凭据文件中的用户名和密码。

注意

如果存储层问题影响镜像,可以再次上传平台镜像,或在更稳定的存储上重新安装 mirror-registry。

为灾难恢复部署 mirror-registry

对于 global 集群灾难恢复,请在主端和备用端分别部署 mirror-registry,并使用专用域名作为镜像 registry 地址。该域名通常解析到主集群侧的 mirror-registry。发生故障时,将其 DNS 解析切换到备用集群侧的 mirror-registry。

重要

两个 mirror-registry 实例不会同步数据,因此必须将平台镜像上传到两者。在切换 DNS 解析之前,集群节点无法从 mirror-registry 拉取镜像。

前提条件

  • 主端和备用端各有一台满足前提条件的计算机。
  • 一个专用于镜像 registry 的域名,所有集群节点都可以解析该域名。此域名独立于平台访问地址的域名。

操作步骤

  1. 在两端分别安装 mirror-registry。两端必须使用相同的用户名和密码,因此建议使用同一个凭据文件。监听端口也必须相同。

  2. 将镜像 registry 域名解析到主集群侧的 mirror-registry。

  3. 将平台镜像上传到两端的 mirror-registry。上传时,将 registry 地址设置为对应计算机的地址。有关详细信息,请参阅准备目标版本负载。

  4. 安装主集群和备用集群时,在两端指定相同的镜像 registry 地址、用户名和密码。

发生故障时

  • 将镜像 registry 域名的 DNS 解析切换到备用集群侧的 mirror-registry。

更新 mirror-registry

此操作步骤使用 upgrade 命令更新 mirror-registry。更新会提供新功能、错误修复和安全漏洞修复。

重要

更新期间服务会重启,因此 registry 会短暂不可用。

前提条件

  • 已安装 mirror-registry。

操作步骤

  • 解压新软件包,并从其目录运行以下命令:

    ./mirror-registry upgrade

    未指定的标志会保留其现有配置。如果更新后服务运行状况不佳,系统会自动回滚到上一版本。

替换 mirror-registry SSL/TLS 证书

使用此操作步骤替换当前证书或定期更新证书。

重要

运行以下命令后服务会重启,因此 registry 会短暂不可用。

前提条件

  • 已安装 mirror-registry。

操作步骤

  • 要使用自己的证书,请运行以下命令。必须同时指定两个标志。私钥不能受密码短语保护:

    ./mirror-registry install --tls-cert <full-chain-file> --tls-key <key-file>
  • 如果计算机的 IP 地址或主机名发生变化,请重新生成自签名证书:

    ./mirror-registry install --regen-cert
    注意

    自动生成的证书涵盖主机名、localhost、127.0.0.1、::1 以及生成时计算机的全局 IP 地址,有效期为 10 年。如果通过其他域名访问 registry,请使用自己的证书。

排查 mirror-registry 问题

mirror-registry 会安装 mirror-registry.service systemd 服务。

前提条件

  • 已安装 mirror-registry。

操作步骤

  1. 检查服务状态:

    systemctl status mirror-registry
  2. 检查服务日志:

    journalctl -u mirror-registry