#使用 YAML 安装

#使用场景

在以下场景中使用 YAML 安装：

• 高级用户，具备 Kubernetes 经验，并且偏好手动方式。
• 需要外部管理存储的部署，例如 NAS、S3-compatible 对象存储或 Ceph。
• 需要对 TLS 和 ingress 进行细粒度控制的环境。
• 用于高级配置的完整 YAML 自定义。

#前提条件

• 将 Registry 集群插件安装到目标集群。
• 已配置 kubectl，并且可以访问目标 Kubernetes 集群。
• 具有创建集群级资源的集群管理员权限。
• 获取已注册的域名，例如 registry.example.com。有关域名配置，请参见 创建域名。
• 提供有效的 NAS 存储，例如 NFS。
• 可选：提供有效的 S3-compatible 存储。

#使用 YAML 安装 Registry

#操作步骤

1. 创建一个名为 registry-plugin.yaml 的 ClusterPluginInstance 清单文件，并使用以下模板：

   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
       persistence:
         accessMode: ReadWriteMany
         nodes: ''
         path: <YOUR-HOSTPATH> # [REQUIRED] Local path for LocalVolume
         size: <STORAGE-SIZE> # [REQUIRED] Storage size (e.g., 10Gi)
         storageClass: <STORAGE-CLASS-NAME> # [REQUIRED] StorageClass name
         type: StorageClass
       registryLimitConfig:
         enabled: false
         configMapName: image-registry-limit-config
       s3storage:
         bucket: <S3-BUCKET-NAME> # [REQUIRED] S3 bucket name
         enabled: false # Set false for local storage
         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:
         size: '<STORAGE-SIZE>' # e.g., 10Gi
         storageClass: '<STORAGE-CLASS-NAME>' # e.g., cpaas-system-storage
       registryLimitConfig:
         enabled: true # Set true to enable registry push limits
         configMapName: 'image-registry-limit-config' # Pre-created ConfigMap name
       s3storage:
         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 S3 access credentials
         env:
           REGISTRY_STORAGE_S3_SKIPVERIFY: 'true' # Set "true" for self-signed certs

3. 如何为 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 名称。

4. 可选：启用 registry push 限制，用于限制镜像大小和 tag 数量。

   此能力由内置的 Registry proxy 提供。

   要启用它：

   • 将 spec.config.registryLimitConfig.enabled 设置为 true。
   • 将 spec.config.registryLimitConfig.configMapName 设置为你在 Registry 命名空间中手动创建的 ConfigMap 名称。

   示例：

   spec:
     config:
       registryLimitConfig:
         enabled: true
         configMapName: image-registry-limit-config

   说明：

   • 该 ConfigMap 不由 Registry 插件创建。
   • 对于新部署，推荐的 ConfigMap 名称为 image-registry-limit-config。
   • 运行时仍然出于向后兼容性接受旧的 ConfigMap 名称 registry-gateway-config。
   • 有关详细的 ConfigMap 示例、规则行为和验证步骤，请参见 配置 Registry Push 限制。

   启用此功能后，请在继续执行第 5 步之前应用 ConfigMap：

   kubectl apply -f image-registry-limit-config.yaml

5. 将 Registry 插件清单应用到你的集群。

   此命令会创建或更新名为 image-registry 的 ClusterPluginInstance 资源，从而安装或更新 Registry 集群插件。

   如果启用了 registryLimitConfig，请在此步骤之前应用 配置 Registry Push 限制 中所述的限制 ConfigMap。

   kubectl apply -f registry-plugin.yaml

#配置参考

#常用字段

#验证

1. 检查插件：

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

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

#更新或卸载 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