#Install by Using YAML

#Use Cases

Use YAML installation for:

• Advanced users with Kubernetes expertise who prefer a manual approach.
• Deployments that require externally managed storage, such as NAS, S3-compatible object storage, or Ceph.
• Environments needing fine-grained control over TLS and ingress.
• Full YAML customization for advanced configurations.

#Prerequisites

• Install the 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, such as registry.example.com. For domain configuration, see Create a Domain.
• Provide valid NAS storage, such as NFS.
• Optional: Provide valid S3-compatible storage.

#Install Registry Using YAML

#Procedure

1. Create a ClusterPluginInstance manifest 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
       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. 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
       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. 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.

4. Optional: enable registry push limits for image size and tag count.

   This capability is provided by the built-in Registry proxy.

   To enable it:

   • Set spec.config.registryLimitConfig.enabled to true.
   • Set spec.config.registryLimitConfig.configMapName to the name of a ConfigMap that you create manually in the Registry namespace.

   Example:

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

   Notes:

   • The ConfigMap is not created by the Registry plugin.
   • For new deployments, the recommended ConfigMap name is image-registry-limit-config.
   • The runtime still accepts the legacy ConfigMap name registry-gateway-config for backward compatibility.
   • For detailed ConfigMap examples, rule behavior, and verification steps, see Configure Registry Push Limits.

   When this feature is enabled, apply the ConfigMap before proceeding to step 5:

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

5. Apply the Registry plugin manifest to your cluster.

   This command creates or updates the ClusterPluginInstance resource named image-registry, which installs or updates the Registry cluster plugin.

   If you enabled registryLimitConfig, apply the limit ConfigMap described in Configure Registry Push Limits before this step.

   kubectl apply -f registry-plugin.yaml

#Configuration Reference

#Common Fields

#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

#Update Or Uninstall 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