#通过 YAML 安装

#何时使用此方法？

推荐适用于：

• 高级用户，具备 Kubernetes 经验，且希望采用手动方式。
• 需要企业级存储（NAS、AWS S3、Ceph 等）的生产级部署。
• 需要对 TLS、Ingress 进行细粒度控制的环境。
• 需要针对高级配置进行完整 YAML 自定义。

#前提条件

• 将 Alauda Container Platform Registry 集群插件 安装 到目标集群。
• 已配置 kubectl，能够访问目标 Kubernetes 集群。
• 具备创建集群级资源的 cluster admin 权限。
• 获取一个已注册的 域名（例如，registry.yourcompany.com）创建域
• 为 Registry 数据选择一种存储后端：
  • 对于基于文件系统的存储，请提供有效的 NAS 存储 或其他 RWX StorageClass（例如，NFS、GlusterFS 等）。
  • 对于对象存储，请提供有效的 S3 存储（例如，AWS S3、Ceph 等）。如果当前没有可用的 S3 存储，请在集群中部署一个 MinIO（内置 S3）实例 部署 MinIO。

#通过 YAML 安装 Alauda Container Platform Registry

#操作步骤

1. 创建一个 YAML 配置文件，命名为 registry-plugin.yaml，并使用以下模板：

   apiVersion: cluster.alauda.io/v1alpha1
   kind: ClusterPluginInstance
   metadata:
     annotations:
       cpaas.io/display-name: image-registry
     labels:
       create-by: cluster-transformer
       manage-delete-by: cluster-transformer
       manage-update-by: cluster-transformer
     name: image-registry
   spec:
     config:
       access:
         address: ''
         enabled: false
       fake:
         replicas: 2
       infra:
         enabled: false
       global:
         expose: false
         isIPv6: false
         replicas: 2
         oidc:
           ldapID: ''
         resources:
           limits:
             cpu: 500m
             memory: 512Mi
           requests:
             cpu: 250m
             memory: 256Mi
       ingress:
         enabled: true
         hosts:
           - name: <YOUR-DOMAIN> # [REQUIRED] Customize domain
             tlsCert: <NAMESPACE>/<TLS-SECRET> # [REQUIRED] Namespace/SecretName
         ingressClassName: '<INGRESS-CLASS-NAME>' # [REQUIRED] IngressClassName
         insecure: false
       # Keep the persistence block only for filesystem-backed storage.
       # If s3storage.enabled is true, remove the entire persistence block.
       persistence:
         accessMode: ReadWriteMany
         nodes: ''
         path: <YOUR-HOSTPATH> # Required only for LocalVolume
         size: <STORAGE-SIZE> # Required only for StorageClass, e.g., 10Gi
         storageClass: <STORAGE-CLASS-NAME> # Required only for StorageClass
         type: StorageClass
       s3storage:
         bucket: <S3-BUCKET-NAME> # Required only for S3
         enabled: false # Set true for S3 storage; when true, do not configure persistence
         env:
           REGISTRY_STORAGE_S3_SKIPVERIFY: false # Set true for self-signed certs
         region: <S3-REGION> # S3 region
         regionEndpoint: <S3-ENDPOINT> # S3 endpoint
         secretName: <S3-CREDENTIALS-SECRET> # S3 credentials Secret
       service:
         nodePort: ''
         type: ClusterIP
     pluginName: image-registry

2. 根据您的环境自定义以下字段：

   spec:
     config:
       global:
         oidc:
           ldapID: '<LDAP-ID>' # LDAP ID
       infra:
         enabled: false  # If you want to deploy components to the infra nodes. Default is false means all nodes.
       ingress:
         hosts:
           - name: '<YOUR-DOMAIN>' # e.g., registry.your-company.com
             tlsCert: '<NAMESPACE>/<TLS-SECRET>' # e.g., cpaas-system/tls-secret
         ingressClassName: '<INGRESS-CLASS-NAME>' # e.g., cluster-alb-1

   选择一种存储配置：

   • 对于基于文件系统的存储，保留 persistence，并将 s3storage.enabled 设置为 false。
   • 对于 S3 存储，删除整个 persistence 块，并将 s3storage.enabled 设置为 true。

   基于文件系统的存储示例：

   spec:
     config:
       persistence:
         size: '<STORAGE-SIZE>' # e.g., 10Gi
         storageClass: '<STORAGE-CLASS-NAME>' # e.g., cpaas-system-storage
       s3storage:
         enabled: false

   S3 存储示例：

   spec:
     config:
       s3storage:
         enabled: true
         bucket: '<S3-BUCKET-NAME>' # e.g., prod-registry
         region: '<S3-REGION>' # e.g., us-west-1
         regionEndpoint: '<S3-ENDPOINT>' # e.g., https://s3.amazonaws.com
         secretName: '<S3-CREDENTIALS-SECRET>' # Secret containing AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY
         env:
           REGISTRY_STORAGE_S3_SKIPVERIFY: 'true' # Set "true" for self-signed certs

3. 规划 Ingress controller 并配置 session affinity。

   选择与您的网络环境、运维要求以及现有流量管理模型相匹配的 Ingress controller。当 Registry 使用多个副本并共享文件存储（例如 NFS 或其他 RWX StorageClass）时，请使用所选 Ingress controller 的原生机制来配置 session affinity。

   一次镜像推送会发送多个 POST、PATCH、PUT、HEAD 和 manifest 请求；这些请求应到达同一个 Registry Pod。Kubernetes Service 的 sessionAffinity: ClientIP 设置在 Ingress controller 直接负载均衡到 Pod 端点时，不能保证粘性。

   对于 ingress-nginx，请使用基于客户端地址的 upstream 哈希：

   spec:
     config:
       ingress:
         annotations:
           nginx.ingress.kubernetes.io/upstream-hash-by: "$remote_addr"

   如果您的环境通过 ACP ALB 暴露 Registry，请使用源 IP 哈希亲和性：

   spec:
     config:
       ingress:
         annotations:
           alb.ingress.cpaas.io/session-affinity-policy: sip-hash

   对于其他 Ingress controller 或云负载均衡器，请使用其等效的源 IP 或基于哈希的 session affinity 策略。如果 controller 仅支持基于 cookie 的粘性，请在以多个副本运行 Registry 之前，先使用生产环境中的 OCI client 验证推送行为；否则，请为该访问路径使用一个 Registry 副本。

4. 创建 S3 凭据 secret：

   kubectl create secret generic <S3-CREDENTIALS-SECRET> \
     --from-literal=access-key-id=<YOUR-S3-ACCESS-KEY-ID> \
     --from-literal=secret-access-key=<YOUR-S3-SECRET-ACCESS-KEY> \
     -n cpaas-system

   将 <S3-CREDENTIALS-SECRET> 替换为您的 S3 凭据 secret 名称。

5. 将配置应用到集群：

   kubectl apply -f registry-plugin.yaml

#配置参考

#重要字段

当 spec.config.s3storage.enabled 设置为 true 时，请不要配置 spec.config.persistence。persistence 块仅用于基于文件系统的存储。

#验证

1. 检查插件：

   kubectl get clusterplugininstances image-registry -o yaml
2. 验证 registry Pod：

   kubectl get pods -n cpaas-system -l app=image-registry

#更新/卸载 Alauda Container Platform Registry

#更新

在 global 集群上执行以下命令，并根据上面的参数说明更新资源中的值，以完成更新：

# <CLUSTER-NAME> is the cluster where the plugin is installed
kubectl edit -n cpaas-system \
  $(kubectl get moduleinfo -n cpaas-system -l cpaas.io/cluster-name=<CLUSTER-NAME>,cpaas.io/module-name=image-registry -o name)

#卸载

在 global 集群上执行以下命令：

# <CLUSTER-NAME> is the cluster where the plugin is installed
kubectl get moduleinfo -n cpaas-system -l cpaas.io/cluster-name=<CLUSTER-NAME>,cpaas.io/module-name=image-registry -o name | xargs kubectl delete -n cpaas-system