#Install Via YAML

#When to Use This Method?

Recommended for:

• Advanced users with Kubernetes expertise who prefer a manual approach.
• Production-grade deployments requiring enterprise storage (NAS, AWS S3, Ceph, etc.).
• Environments needing fine-grained control over TLS, ingress.
• Full YAML customization for advanced configurations.

#Prerequisites

• Install the Alauda Container Platform Registry cluster plugin to a target cluster.
• Access to the target Kubernetes cluster with kubectl configured.
• Cluster admin permissions to create cluster-scoped resources.
• Obtain a registered domain (e.g., registry.yourcompany.com) Create a Domain
• Choose one storage backend for Registry data:
  • For filesystem-backed storage, provide valid NAS storage or another RWX StorageClass (e.g., NFS, GlusterFS, etc.).
  • For object storage, provide valid S3 storage (e.g., AWS S3, Ceph, etc.). If no existing S3 storage is available, deploy a MinIO (Built-in S3) instance in the cluster Deploy MinIO.

#Installing Alauda Container Platform Registry via YAML

#Procedure

1. Create a YAML configuration file named registry-plugin.yaml with the following template:

   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. Customize the following fields according to your environment:

   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

   Choose one storage configuration:

   • For filesystem-backed storage, keep persistence and set s3storage.enabled to false.
   • For S3 storage, remove the entire persistence block and set s3storage.enabled to true.

   Filesystem-backed storage example:

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

   S3 storage example:

   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. Plan the Ingress controller and configure session affinity.

   Choose an Ingress controller that matches your network environment, operational requirements, and existing traffic management model. When the Registry uses multiple replicas with shared file storage such as NFS or another RWX StorageClass, configure session affinity by using the native mechanism of the selected Ingress controller.

   A single image push sends multiple POST, PATCH, PUT, HEAD, and manifest requests; those requests should reach the same Registry Pod. The Kubernetes Service sessionAffinity: ClientIP setting does not guarantee stickiness when the Ingress controller load-balances directly to Pod endpoints.

   For ingress-nginx, use upstream hashing by client address:

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

   If your environment exposes the Registry through ACP ALB, use source IP hash affinity:

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

   For other Ingress controllers or cloud load balancers, use the controller's equivalent source IP or hash-based session affinity policy. If the controller only supports cookie-based stickiness, verify push behavior with the OCI client used in production before running the Registry with multiple replicas; otherwise, use one Registry replica for that access path.

4. How to create a secret for S3 credentials:

   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

   Replace <S3-CREDENTIALS-SECRET> with the name of your S3 credentials secret.

5. Apply the configuration to your cluster:

   kubectl apply -f registry-plugin.yaml

#Configuration Reference

#Important Fields

When spec.config.s3storage.enabled is set to true, do not configure spec.config.persistence. The persistence block is used only for filesystem-backed storage.

#Verification

1. Check plugin:

   kubectl get clusterplugininstances image-registry -o yaml
2. Verify registry pods:

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

#Updating/Uninstalling Alauda Container Platform Registry

#Update

Execute the following command on the global cluster and update the values in the resource according to the parameter descriptions provided above to complete the update:

# <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)

#Uninstall

Execute the following command on the global cluster:

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