#为业务集群选择镜像 Registry

Alauda Container Platform 会在每个业务集群上安装并管理一组平台组件，包括 Kube-OVN 以及集群启动后交付的平台模块。这些组件的镜像来自镜像 Registry，默认情况下使用 global 集群所使用的同一 Registry。

你也可以将业务集群绑定到专用的 Registry。常见原因是距离：当 global 集群与业务集群位于不同地域时，通过该链路拉取每个平台镜像既缓慢又不稳定。使用靠近业务集群的 Registry 可以消除这种依赖。

请在创建集群之前做出决定。绑定关系仅在创建集群时读取，现有集群无法迁移到其他 Registry。

#选项

这两个选项适用于每个基础设施提供商。默认选项无需任何配置，因此通过 Web UI 创建的集群也适用。专用 Registry 只能通过 YAML 进行配置：集群创建向导不提供可供选择的 Registry 凭证，因此当集群需要使用专用 Registry 时，请使用对应提供商集群创建指南中的 YAML 工作流。

#绑定范围

该绑定适用于 Alauda Container Platform 在业务集群上安装和管理的平台组件，例如 Kube-OVN 以及交付到该集群的平台模块。

以下内容不适用。每项内容都在其他位置配置，将集群指向专用 Registry 不会对其产生任何影响。

#继承 global 集群的 Registry

这是默认行为，无需进行配置。创建集群时不添加 cpaas.io/registry-reference 标签，该集群就会使用与 global 集群相同的 Registry。

地址和凭证如何传递到业务集群，取决于平台 Registry 是否需要身份验证：

• 需要身份验证的 Registry — 平台会将地址和凭证存储在 global 集群上 cpaas-system 中的 public-registry-credential Secret 内。每个未显式引用 Registry 的业务集群都会从该 Secret 解析其 Registry。尽管名称如此，该 Secret 保存的是平台自身使用的 Registry，并不局限于面向互联网的 Registry。
• 匿名 Registry — 不会填充凭证 Secret，平台组件会回退到安装时记录的平台级 Registry 地址。

在这两种情况下，operator 都无需针对每个集群进行配置。

#将业务集群绑定到其专用 Registry

#开始之前

• 你可以在 global 集群的 cpaas-system 命名空间中创建 Secret。引用该凭证 Secret 的集群创建之前，该 Secret 必须已经存在。
• 每个业务集群节点都可以访问专用 Registry；如果你希望从 global 集群进行验证，该集群也必须能够访问专用 Registry。
• 专用 Registry 中已包含目标版本的 Alauda Container Platform Core，以及计划在该集群上安装的每个插件所需的软件包。请参阅准备 Registry。

#步骤 1 — 准备 Registry

平台不会将镜像复制到专用 Registry。请在创建集群之前自行填充该 Registry。

其中必须包含的内容取决于以下两点：

• 始终需要目标版本的 Alauda Container Platform Core。其中的镜像和软件包必须与即将创建的集群的版本和 CPU 架构匹配。
• 除 Core 之外的所有内容取决于你计划在该集群上安装哪些平台插件。只有你知道这组插件；平台不会推导该列表，也不会在之后补齐缺失内容。请将这些插件的软件包与 Core 一起上传。

使用准备外部平台镜像 Registry 时所用的相同 Core Package 上传操作步骤，并将专用 Registry 作为目标地址。

然后，从目标网络中的某个节点确认 Registry 可以响应：

export DEDICATED_REGISTRY="<registry-host>:<port>"
curl -sk "https://${DEDICATED_REGISTRY}/v2/" -o /dev/null -w '%{http_code}\n'

这只能证明网络可达性和 TLS 状态。请在 Registry 自有的管理界面或 API 中确认已上传的仓库和标签。

/v2/ 片段仅用于 Registry HTTP API 请求。请勿将其或协议添加到 Secret 或任何集群字段中。

#步骤 2 — 创建 RegistryCredential Secret

在 global 集群的 cpaas-system 命名空间中创建 Secret。集群上的引用只携带名称，因此只会查询此命名空间；其他命名空间中同名的 Secret 会被忽略。

请使用编辑器编写凭证文件，而不要在 shell 提示符中输入这些值。Shell 会将包含密码在内的完整命令记录到历史记录中；使用编辑器写入的文件不会留下此类副本。

registry=<registry-host>:<port>
username=<username>
password=<password>

对于匿名 Registry，仅保留 registry 行，并省略另外两行。

限制文件权限，从文件创建 Secret，然后将其删除：

chmod 600 registry-credential.env

REGISTRY_CREDENTIAL_NAME="<registry-credential-name>"

kubectl create secret generic "${REGISTRY_CREDENTIAL_NAME}" \
  --namespace cpaas-system \
  --from-env-file=registry-credential.env

rm -f registry-credential.env

文件中的每一行都是 key=value。请勿为值添加引号——kubectl 会将引号字符按字面值处理，因此 password="s3cret" 会将带引号的 "s3cret" 存储为值。值可以包含 = 和其他特殊字符；每行中只有第一个 = 用于分隔键和值。

Secret 创建时使用的类型为 Opaque，此处这样设置是正确的。平台通过标签而不是类型识别 Registry 凭证，因此请在创建任何引用该 Secret 的集群之前应用以下两个标签：

kubectl label secret "${REGISTRY_CREDENTIAL_NAME}" --namespace cpaas-system --overwrite \
  capi.cpaas.io/provider=registry-credential \
  cpaas.io/registry-credential-format=direct

#步骤 3 — 创建集群时引用凭证

将 cpaas.io/registry-reference 标签添加到 Cluster 资源，并将 Secret 名称作为其值：

apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: <cluster-name>
  namespace: cpaas-system
  labels:
    cpaas.io/registry-reference: <registry-credential-name>

按照提供商集群创建指南中的说明应用其余集群清单。

执行此操作时，Secret 必须已经存在。平台注册新集群时会解析该引用，并在此时从 cpaas-system 按名称读取 Secret。如果 Secret 不存在，注册将无法完成，集群也不会取得进展。这不是永久性失败——平台会持续重试，因此之后创建 Secret 即可解除集群阻塞——但在此期间不会发生任何变化，并且原因不会报告在 Cluster 资源本身上。请先创建 Secret。

#步骤 4 — 验证绑定

在 global 集群上运行以下检查。确认引用已传递到平台集群记录：

export CLUSTER_NAME="<cluster-name>"
kubectl get cluster.platform.tkestack.io "${CLUSTER_NAME}" \
  -o jsonpath='{.metadata.labels.cpaas\.io/registry-reference}{"\n"}'

确认平台已从凭证中解析 Registry 地址。该注解由平台写入，请勿自行设置：

kubectl get cluster.platform.tkestack.io "${CLUSTER_NAME}" \
  -o jsonpath='{.metadata.annotations.cpaas\.io/registry-address}{"\n"}'

该值必须是 Secret 中的地址。如果为空或仍显示其他 Registry，请参阅故障排除。

最后，在业务集群上确认平台 Pod 是否从预期的 Registry 拉取镜像：

kubectl --kubeconfig <workload-cluster-kubeconfig> get pods -A \
  -o jsonpath='{range .items[*]}{range .spec.containers[*]}{.image}{"\n"}{end}{end}' \
  | sort -u

平台组件镜像使用专用 Registry。kubeadm 管理的镜像以及 pause 镜像不会使用该 Registry——请参阅绑定范围。部分镜像仍解析到其他 Registry 属于预期情况；但所有平台组件镜像都解析到旧 Registry 则不符合预期。

#操作现有绑定

请使用 kubectl patch 更新凭证，而不是使用 kubectl apply，原因与创建凭证时使用 kubectl create 相同：

stringData:
  username: <new-username>
  password: <new-password>

chmod 600 registry-credential-patch.yaml

kubectl patch secret "${REGISTRY_CREDENTIAL_NAME}" --namespace cpaas-system \
  --type=merge --patch-file=registry-credential-patch.yaml

rm -f registry-credential-patch.yaml

补丁中的 stringData 会替换 data 中相应的键。如果此处的值包含 YAML 元字符，请将其引起来——不同于创建时使用的 key=value 文件，此文件是 YAML。

#故障排除