Alauda Container Platform
  • 简体中文

    • Alauda Container Platform Registry

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

    目录

    主要组件安装 Alauda Container Platform Registry从 OperatorHub 安装使用 YAML 安装先决条件升级 Alauda Container Platform Registry更改 Registry 管理状态Image Pruner 协调检查 Operator 和 Registry 状态检查 Registry 日志和指标访问常见 Operator 问题

    主要组件

    组件用途
    cluster-image-registry-operator Deployment从 Config/cluster 和 ImagePruner/cluster 调和单例 Registry。
    image-registry Deployment提供 OCI 推送和拉取流量、身份验证、授权、存储访问、运行状况检查和指标服务。
    image-api-server Deployment通过 Kubernetes API 聚合提供 Image API。
    APIService/v1.image.alauda.io向 Kubernetes API server 注册 image.alauda.io/v1。
    node-ca DaemonSet向节点分发 Registry CA 信任配置和 Registry 服务主机映射。
    image-pruner CronJob运行计划的镜像清理，并在 Registry 受管理期间运行 registry 垃圾回收。
    受管理的 imagePullSecret controller为内部 registry 创建、注入、刷新和移除 service account 拉取 Secret。

    安装 Alauda Container Platform Registry

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

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

    从 OperatorHub 安装

    1. 登录 并导航到管理员页面。
    2. 在左侧导航栏中，单击 Marketplace > OperatorHub。
    3. 搜索 Alauda Container Platform Registry 或 cluster-image-registry-operator。
    4. 单击安装。
    5. 在安装页面中，除非您的版本指南另有说明，否则使用以下设置：
    参数建议值
    Channelstable
    Installation ModeAll namespaces on the cluster
    Namespaceimage-registry-system
    Upgrade StrategyManual
    1. 单击安装。
    2. 如果出现批准提示，请查看并批准生成的 install plan。
    3. 等待 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 安装

    先决条件

    cluster-image-registry-operator package 必须已存在于目标 CatalogSource 中。 全新平台安装不包含该 package，且当 package 缺失时，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

    继续操作前验证 package：

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

    如果缺失，请先按照平台的 Operator package 上传操作步骤 上传 Operator package。例如：

    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>"

    推送必须使用在目标 repositories 上具有 push 权限的 registry 账户。 仅具有拉取权限的账户会失败，并显示 requested access to the resource is denied。推送不会为 Operator 自身的 workloads 配置镜像拉取凭据；请参阅下面安装步骤中的拉取 Secret 注意事项。

    如果安装 namespace 不存在，请创建它：

    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 workloads。这些 workloads 从平台 registry 拉取其镜像，因此 Operator 使用的 ServiceAccounts 必须携带可用的 registry 拉取 Secret。如果 workload 持续处于 ImagePullBackOff 状态并显示 insufficient_scope: authorization failed，请确认平台 registry 拉取 Secret 已附加到这些 ServiceAccounts：

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

    如果 Secret 缺失，请附加该 Secret，然后重启 workloads：

    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 软件包之前，将 Subscription 审批策略设置为 Manual：

    kubectl -n image-registry-system get subscription
kubectl -n image-registry-system patch subscription <subscription-name> \
  --type=merge \
  -p '{"spec":{"installPlanApproval":"Manual"}}'
    占位符描述
    <subscription-name>Alauda Container Platform Registry Operator 的 Subscription。使用 kubectl -n image-registry-system get subscription 返回的名称。

    在 管理员 > Marketplace > OperatorHub 中提供目标 Operator 软件包。 如果软件包不存在，请按照平台的 Operator 软件包上传操作步骤 操作，然后再继续。

    在 OperatorHub 中打开 Alauda Container Platform Registry，选择目标频道和版本， 并查看待处理的升级。确认 Subscription 使用 Manual 审批后，再批准生成的 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 数据平面是否完成协调：

    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 报告新的已安装 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 拉取 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 数据平面。

    通过将 Config/cluster.spec.managementState 设置为 Managed 来启用 Registry：

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

    验证 Registry 数据平面是否可用：

    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 被移除期间，请勿依赖计划清理。 仅在维护窗口期间或根据支持人员指导进行恢复时使用此状态。

    切换到 Removed 前，请备份所需的镜像数据，并检查存储管理模式：

    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"}}'

    验证数据平面 Deployment 是否已移除：

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

    预期结果：

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

    Image Pruner 协调

    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 discovery 文档不会公开该资源，而 kubectl auth can-i 会通过 discovery 解析资源名称。因此，即使已授予权限，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 问题

    症状检查
    CSV 不是 SucceededSubscription、InstallPlan、CSV 事件以及 cpaas-system catalog source。
    Config/cluster 为 Degraded=TrueConfig.status.conditions、Operator 日志、Registry Pod 事件、存储、TLS Secret 和 RBAC。
    Registry Pod 处于 pending 状态PVC 绑定、节点资源、节点选择器、污点、容忍度和拓扑约束。
    node-ca 未就绪DaemonSet 调度、Pod 日志、节点信任配置以及主机映射更新。