#Alauda Container Platform Registry

Image Registry Operator 安装并管理集群范围的 Alauda Container Platform Registry 实例。它根据 Config/cluster 协调 Registry 运行时资源，并根据 ImagePruner/cluster 协调计划的清理资源。

#主要组件

#安装 Alauda Container Platform Registry

当 Operator 软件包在 OperatorHub 中可用时，从 Web 控制台安装 Image Registry Operator，以部署 Alauda Container Platform Registry。仅当 Web 控制台不可用时，才使用 YAML 路径进行受控自动化安装或在支持人员指导下安装。

两种安装路径都要求目标 CatalogSource 中存在 cluster-image-registry-operator 软件包。有关如何验证软件包并在缺失时上传软件包，请参阅使用 YAML 安装。

#从 OperatorHub 安装

1. 登录 ，然后导航到管理员页面。
2. 在左侧导航栏中，单击 Marketplace > OperatorHub。
3. 搜索 Alauda Container Platform Registry 或 cluster-image-registry-operator。
4. 单击安装。
5. 在安装页面上，除非版本指南另有说明，否则使用以下设置：

6. 单击安装。
7. 如果出现批准提示，请查看并批准生成的安装计划。
8. 等待 Operator 状态变为已安装。

验证安装：

kubectl -n image-registry-system get subscription,csv,installplan
kubectl -n image-registry-system get deployment cluster-image-registry-operator

预期结果：

• 已安装的 CSV 为 Succeeded。
• cluster-image-registry-operator Deployment 可用。

#使用 YAML 安装

#先决条件

目标 CatalogSource 中必须已存在 cluster-image-registry-operator 软件包。全新平台安装不包含该软件包；缺少该软件包时，check-subscription.cpaas.io admission webhook 会拒绝 Subscription：

admission webhook "check-subscription.cpaas.io" denied the request:
packagemanifests.packages.operators.coreos.com "cluster-image-registry-operator" not found

继续之前验证软件包：

kubectl -n cpaas-system get packagemanifests | grep cluster-image-registry-operator

如果缺少该软件包，请先按照平台的 Operator 软件包上传操作步骤 上传 Operator 软件包。例如：

violet push cluster-image-registry-operator.stable.amd64.<version>.tgz \
  --platform-address="https://<platform-host>" \
  --platform-username="<platform-admin-user>" \
  --platform-password="<platform-admin-password>" \
  --target-catalog-source=platform \
  --dest-repo="<global-registry-address>" \
  --username="<registry-user>" \
  --password="<registry-password>"

推送必须使用在目标仓库上具有 push 权限的 Registry 账户。仅具有拉取权限的账户会失败并显示 requested access to the resource is denied。推送不会为 Operator 自身的工作负载配置镜像拉取凭据；请参阅下面安装步骤中的拉取 Secret 说明。

如果安装命名空间不存在，请创建它：

kubectl get namespace image-registry-system >/dev/null 2>&1 || \
  kubectl create namespace image-registry-system

kubectl label namespace image-registry-system \
  cpaas.io/project=cpaas-system \
  pod-security.kubernetes.io/audit=privileged \
  pod-security.kubernetes.io/enforce=privileged \
  pod-security.kubernetes.io/warn=privileged \
  --overwrite

创建名为 image-registry-operator-subscription.yaml 的文件：

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  annotations:
    cpaas.io/target-namespaces: ""
  name: cluster-image-registry-operator
  namespace: image-registry-system
spec:
  channel: stable
  installPlanApproval: Manual
  name: cluster-image-registry-operator
  source: platform
  sourceNamespace: cpaas-system

应用 Subscription：

kubectl apply -f image-registry-operator-subscription.yaml

批准生成的 InstallPlan：

kubectl -n image-registry-system get installplan

kubectl -n image-registry-system patch installplan <installplan-name> \
  --type=merge \
  -p '{"spec":{"approved":true}}'

等待 Operator：

kubectl -n image-registry-system wait \
  --for=condition=Available \
  deployment/cluster-image-registry-operator \
  --timeout=300s

Operator 随后会创建 image-registry、image-api-server 和 node-ca 工作负载。这些工作负载从平台 Registry 拉取镜像，因此 Operator 使用的 ServiceAccount 必须携带可用的 Registry 拉取 Secret。如果工作负载一直处于 ImagePullBackOff 状态并显示 insufficient_scope: authorization failed，请确认平台 Registry 拉取 Secret 已附加到这些 ServiceAccount：

kubectl -n image-registry-system get serviceaccount registry node-ca image-api-server \
  -o jsonpath='{range .items[*]}{.metadata.name}{" "}{.imagePullSecrets[*].name}{"\n"}{end}'

如果缺少 Secret，请将其附加，然后重启工作负载：

kubectl -n image-registry-system patch serviceaccount registry node-ca image-api-server \
  --type=merge -p '{"imagePullSecrets":[{"name":"<platform-pull-secret>"}]}'
kubectl -n image-registry-system rollout restart deployment/image-registry daemonset/node-ca

#升级 Alauda Container Platform Registry

通过 OperatorHub 升级 Image Registry Operator，以升级 Alauda Container Platform Registry。Operator 升级会更新 cluster-image-registry-operator Deployment，然后协调现有的 Config/cluster、ImagePruner/cluster、Registry、Image API 及支持资源。

升级前，请确认当前 Registry 运行状况正常。

重要：对于早于 v4.4 的 Alauda Container Platform Registry 版本（包括 ACP 4.3 及更早版本），请联系技术支持以获取升级和迁移计划。

kubectl -n image-registry-system get subscription,csv
kubectl get configs.imageregistry.operator.alauda.io cluster -o yaml
kubectl -n image-registry-system rollout status deployment/image-registry --timeout=300s
kubectl -n image-registry-system rollout status deployment/image-api-server --timeout=300s

在提供新的 Operator package 之前，将 Subscription approval strategy 设置为 Manual：

kubectl -n image-registry-system get subscription
kubectl -n image-registry-system patch subscription <subscription-name> \
  --type=merge \
  -p '{"spec":{"installPlanApproval":"Manual"}}'

在 Administrator > Marketplace > OperatorHub 中提供目标 Operator package。如果不存在该 package，请先按照平台的 Operator package 上传操作步骤 操作，然后再继续。

在 OperatorHub 中打开 Alauda Container Platform Registry，选择目标 channel 和 version，并查看待处理的升级。只有在确认 Subscription 使用 Manual approval 后，才批准生成的 InstallPlan：

PLAN_NAME="$(kubectl -n image-registry-system get subscription <subscription-name> \
  -o jsonpath='{.status.installPlanRef.name}')"
kubectl -n image-registry-system get installplan "$PLAN_NAME" -o yaml
kubectl -n image-registry-system patch installplan "$PLAN_NAME" \
  --type=merge \
  -p '{"spec":{"approved":true}}'

等待新的 CSV 和 Operator Deployment，然后验证 Registry data plane 是否完成协调：

kubectl -n image-registry-system get subscription,csv,installplan
kubectl -n image-registry-system rollout status deployment/cluster-image-registry-operator --timeout=300s
kubectl -n image-registry-system rollout status deployment/image-registry --timeout=300s
kubectl -n image-registry-system rollout status deployment/image-api-server --timeout=300s
kubectl get configs.imageregistry.operator.alauda.io cluster -o yaml
kubectl get imagepruners.imageregistry.operator.alauda.io cluster -o yaml

预期结果：

• 新的 CSV 为 Succeeded，且 Subscription 报告新的 installed CSV。
• cluster-image-registry-operator、image-registry 和 image-api-server 可用。
• 现有存储、路由、Image API 元数据和 ImagePruner 配置仍保持协调状态。
• Config/cluster 报告 Available=True、Progressing=False 和 Degraded=False。

注意：CSV 升级会重新应用 Operator 的 ServiceAccount。如果在安装期间已将 Registry pull Secret 附加到该 ServiceAccount，升级可能会清除该 Secret，导致新的 cluster-image-registry-operator Pod 保持在 ImagePullBackOff 状态并显示 insufficient_scope: authorization failed。请重新附加 Secret，然后重启 Deployment：

kubectl -n image-registry-system patch serviceaccount cluster-image-registry-operator \
  --type=merge -p '{"imagePullSecrets":[{"name":"<platform-pull-secret>"}]}'
kubectl -n image-registry-system rollout restart deployment/cluster-image-registry-operator

Operator 升级期间，请勿删除 Subscription、Config/cluster、存储对象或 Image API 元数据。如果升级未完成，请先检查 Subscription、InstallPlan、CSV 事件、Operator 日志和 Config/cluster.status.conditions，再采取进一步操作。

#更改 Registry 管理状态

启用 Registry 前，请配置一个受支持的存储后端。如果 Config/cluster.spec.storage 为空，将 managementState 设置为 Managed 会使 Operator 保持在 StorageNotConfigured，并且无法协调 Registry data plane。

将 Config/cluster.spec.managementState 设置为 Managed，以启用 Registry：

kubectl patch configs.imageregistry.operator.alauda.io cluster \
  --type=merge \
  -p '{"spec":{"managementState":"Managed"}}'

验证 Registry data plane 是否可用：

kubectl -n image-registry-system rollout status deployment/image-registry --timeout=300s
kubectl -n image-registry-system rollout status deployment/image-api-server --timeout=300s
kubectl get configs.imageregistry.operator.alauda.io cluster -o yaml

预期结果：

• Config/cluster 报告 Available=True、Progressing=False 和 Degraded=False。

警告：将管理状态设置为 Removed 会停止 Registry 运行时组件。 Registry 被移除期间，推送和拉取流量以及 Image API 服务器均不可用。 Operator 也可能保留 image-pruner CronJob，但会禁用已移除 Registry 的 registry 垃圾回收。 Registry 被移除期间，请勿依赖计划清理。 仅应在维护窗口期间或根据支持人员指导进行恢复时使用此状态。

切换到 Removed 前，请备份所需的镜像数据，并检查存储 Management Mode：

kubectl get configs.imageregistry.operator.alauda.io cluster \
  -o jsonpath='{.spec.storage.managementState}{"\n"}'

仅当 spec.storage.managementState 为 Unmanaged，或存储管理员已确认后端存储回收策略会在 Registry 实例移除后保留数据时，才能假定镜像数据会被保留。在更改管理状态前，请备份所需的镜像数据。

要停止 Registry，请将管理状态设置为 Removed：

kubectl patch configs.imageregistry.operator.alauda.io cluster \
  --type=merge \
  -p '{"spec":{"managementState":"Removed"}}'

验证 data plane Deployment 是否已移除：

kubectl -n image-registry-system get deployment image-registry image-api-server --ignore-not-found

预期结果：

• Registry 被移除期间，image-registry 和 image-api-server Deployment 不存在。

#ImagePruner 协调

Operator 会将单例 ImagePruner/cluster 协调为 image-pruner 中的 image-registry-system CronJob。在 ImagePruner 资源中配置保留策略。请参阅设置和配置 Registry。

CronJob 默认使用 Registry 内部服务 URL。

#检查 Operator 和 Registry 状态

本节假定已按照更改 Registry 管理状态中的说明，将 Config/cluster.spec.managementState 设置为 Managed，从而启用 Registry。 spec.managementState 没有默认值。未设置该值时，Operator 会报告原因为 Removed 的 Available=True，并且不存在 image-registry 和 image-api-server Deployment。

kubectl -n image-registry-system get subscription,csv,installplan
kubectl -n image-registry-system get deploy cluster-image-registry-operator image-registry image-api-server
kubectl -n image-registry-system get daemonset node-ca
kubectl -n image-registry-system get cronjob image-pruner
kubectl get apiservice v1.image.alauda.io
kubectl get configs.imageregistry.operator.alauda.io cluster -o yaml
kubectl get imagepruners.imageregistry.operator.alauda.io cluster -o yaml

预期结果：

• Operator CSV 为 Succeeded。
• cluster-image-registry-operator、image-registry 和 image-api-server 可用。
• node-ca 已在目标节点上就绪。
• APIService/v1.image.alauda.io 为 Available=True。
• Config/cluster 报告 Available=True、Progressing=False 和 Degraded=False。

#检查 Registry 日志和指标访问

检查 Registry Pod：

kubectl -n image-registry-system get pods -l app.kubernetes.io/name=image-registry

查看 Registry 日志：

kubectl -n image-registry-system logs deployment/image-registry -c registry

检查监控 ServiceAccount 的指标访问权限。

registry/metrics 是仅用于 RBAC 的资源。image.alauda.io/v1 API 发现文档不会公开该资源，而 kubectl auth can-i 会通过发现机制解析资源名称。因此，即使已授予 权限，kubectl auth can-i get registry/metrics.image.alauda.io 也始终报告 no。请改用 SubjectAccessReview：

for SA in prometheus-sa vm-sa; do
  printf '%s: ' "${SA}"
  kubectl create -f - -o jsonpath='{.status.allowed}{"\n"}' <<EOF
apiVersion: authorization.k8s.io/v1
kind: SubjectAccessReview
spec:
  user: system:serviceaccount:cpaas-system:${SA}
  resourceAttributes:
    verb: get
    group: image.alauda.io
    resource: registry
    subresource: metrics
EOF
done

预期结果：

• 每次检查都报告 true。

Operator 通过 registry-monitoring ClusterRoleBinding 将 system:image-registry-metrics-reader 绑定到 prometheus-sa 和 vm-sa。这些 ServiceAccount 由监控 插件创建，因此在安装监控之前，各项检查都会报告 false。

#常见 Operator 问题