#Installation

This page covers installing the Alauda Data Services Relational Database E3 operator. Once the operator is installed, you can deploy your first PostgreSQL cluster by applying a Cluster CR (Functions guide coming in a later release).

#Prerequisites

• An Alauda Container Platform (ACP) cluster, version 4.1 to 4.4. This release was validated on ACP 4.1.6, 4.2.5, 4.3.2, 4.3.3 (arm64, IPv6-only) and 4.4.0. Before installing, run the image rewrite check below and add the rule if it prints RULE NEEDED.
• Cluster admin or platform admin access.
• The cloudnative-pg package downloaded for your version (.tgz) — typically installed via the platform catalog UI.
• A block-mode StorageClass available in the target cluster (e.g. global-topolvmsc).

#Check whether the cluster needs an image rewrite rule

The images of this release are published under registry-dev.alauda.io. On some ACP clusters, the platform's marketplace component rewrites such an image to <platform registry>/3rdparty/<path> when a pod is created, a path that does not exist in the platform registry, so the operator and database pods cannot start. Whether a cluster does this depends on the version of that component, not only on the ACP version: on 2026-10-30, the ACP 4.1.6 and 4.2.5 clusters needed the rule, while an ACP 4.3.2 cluster with an updated component, the ACP 4.3.3 cluster and the ACP 4.4.0 cluster did not. ACP 4.3.3 and later, and ACP 4.4, are not affected. On an affected cluster you see:

• the operator's CSV stays in Installing, or fails and retries;
• pod events show ErrImagePull or ImagePullBackOff for an image like <platform registry>/3rdparty/eco-oss/postgres/cloudnative-pg:<version>. The pull error can read x509: certificate signed by unknown authority: it means the image is not at that path, not a certificate problem.

Run the steps below on the cluster where the operator is installed (not the global cluster, unless the operator runs there), after the package has been pushed to that cluster and before you install or upgrade the operator. Pushing the package creates the cloudnative-pg ImageWhiteList that the rule needs.

1. Check whether the rule is needed. This only asks the admission webhook how it would rewrite one of the package's images (--dry-run=server); it creates nothing:

   REGISTRY=$(kubectl get cm -n kube-public global-info -o jsonpath='{.data.registryAddress}')
   IMG=$(kubectl -n cpaas-system get imagewhitelist cloudnative-pg -o jsonpath='{.spec.repoList[*]}' \
         | tr ' ' '\n' | grep '^registry-dev\.alauda\.io/' | head -1)
   WANT="$REGISTRY/${IMG#*/}"
   GOT=$(printf 'apiVersion: v1\nkind: Pod\nmetadata:\n  name: cnpg-rewrite-check\n  namespace: default\nspec:\n  containers:\n  - name: p\n    image: %s\n' "$IMG" \
         | kubectl create -f - --dry-run=server -o jsonpath='{.spec.containers[0].image}')
   if [ "$GOT" = "$WANT" ]; then echo "OK: no rule needed (or already in place)"; else echo "RULE NEEDED: $IMG -> $GOT"; fi

   If it prints OK, skip the rest of this section. If IMG is empty, the package has not been pushed to this cluster yet.

2. Add the rule. The script below is safe to run more than once: it does nothing if a rule for registry-dev.alauda.io already exists, and it appends to existing rules instead of replacing them. Do not use a merge patch for this field: it replaces the whole list.

   REGISTRY=$(kubectl get cm -n kube-public global-info -o jsonpath='{.data.registryAddress}')
   CUR=$(kubectl -n cpaas-system get imagewhitelist cloudnative-pg -o jsonpath='{.spec.rewriteRules}')
   RULE="{\"regexp\":\"registry-dev.alauda.io/(.*)\",\"replacement\":\"${REGISTRY}/\${1}\"}"
   if printf '%s' "$CUR" | grep -q 'registry-dev.alauda.io'; then
     echo "rule already present"
   elif [ -z "$CUR" ]; then
     kubectl -n cpaas-system patch imagewhitelist cloudnative-pg --type=json \
       -p "[{\"op\":\"add\",\"path\":\"/spec/rewriteRules\",\"value\":[${RULE}]}]"
   else
     kubectl -n cpaas-system patch imagewhitelist cloudnative-pg --type=json \
       -p "[{\"op\":\"add\",\"path\":\"/spec/rewriteRules/-\",\"value\":${RULE}}]"
   fi

3. Wait about 15 seconds (the webhook caches the rules), then run step 1 again: it must print OK.

4. If the operator was already installed and its pods are failing, delete the cnpg-controller-manager and barman-cloud pods in cnpg-system so that they are recreated with the rewritten images:

   kubectl -n cnpg-system delete pod -l app.kubernetes.io/name=cloudnative-pg
   kubectl -n cnpg-system delete pod -l app=barman-cloud

   Delete a PostgreSQL instance pod only if it is itself stuck in ImagePullBackOff; never restart running instances for this.

The rule belongs to the cloudnative-pg ImageWhiteList and applies only to the images that list names: another product's registry-dev.alauda.io images are not rewritten by it, and that product needs its own rule. It is cluster configuration created by you, not by the package: add it again if the cluster is rebuilt or the ImageWhiteList is recreated, and remove it after the platform is upgraded to ACP 4.3.3 or later, or ACP 4.4, if you want (it is then harmless either way).

The rule does not apply to Kubernetes image volumes (.spec.postgresql.extensions[].image): ACP does not rewrite those at all. See the release notes for the references to use there.

#Install via the platform catalog (recommended)

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: cloudnative-pg
  namespace: cnpg-system
spec:
  channel: stable
  installPlanApproval: Automatic
  name: cloudnative-pg
  source: platform
  sourceNamespace: cpaas-system

apiVersion: v1
kind: Namespace
metadata:
  name: cnpg-system
---
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: cnpg-system-og
  namespace: cnpg-system
spec: {}

kubectl wait csv -l operators.coreos.com/cloudnative-pg.cnpg-system='' -n cnpg-system \
  --for=jsonpath='{.status.phase}'=Succeeded --timeout=5m

#Verify the install

After CSV is Succeeded:

kubectl get csv -n cnpg-system
kubectl get deploy cnpg-controller-manager -n cnpg-system
kubectl get pods -n cnpg-system

Expected:

• One CSV cloudnative-pg.<version> with phase Succeeded.
• Deployment cnpg-controller-manager with 1/1 ready replicas.
• One operator pod cnpg-controller-manager-<hash> Running.

Check the operator's environment for the ACP-specific defaults:

kubectl get deploy cnpg-controller-manager -n cnpg-system \
  -o jsonpath='{.spec.template.spec.containers[0].env}' | python3 -c "
import json,sys
[print(e['name'], '=', e.get('value','')) for e in json.load(sys.stdin)
 if e['name'] in ('ENABLE_IMAGE_REWRITE_TOLERANCE','POSTGRES_IMAGE_NAME','PGBOUNCER_IMAGE_NAME')]"

You should see:

• ENABLE_IMAGE_REWRITE_TOLERANCE = true
• POSTGRES_IMAGE_NAME = registry-dev.alauda.io/eco-oss/postgres/cnpg/postgresql:18.6-202610260653-standard-trixie
• PGBOUNCER_IMAGE_NAME = registry-dev.alauda.io/eco-oss/postgres/cnpg/pgbouncer:1.25.2-202610260735-trixie

If ENABLE_IMAGE_REWRITE_TOLERANCE is missing, you are on a pre-v1.29.0-acp.1 build. See Upgrade for the remediation procedure.

#Next

• Architecture — operator + Cluster CR model.
• Upgrade — patch/minor version upgrade procedure.
• Release Notes — per-version changes.

A "Create a Cluster" walkthrough and Troubleshooting reference are scheduled for a future docs release. For now, the architecture page covers the Cluster CR model and the upgrade page includes diagnostic procedures for common install issues.

#Trademark Notice

CloudNativePG™ is a trademark of The Linux Foundation.

PostgreSQL® is a registered trademark of the PostgreSQL Community Association of Canada.

Alauda is an independent vendor. This product is not affiliated with, endorsed by, or sponsored by The Linux Foundation, PostgreSQL Community Association of Canada. All trademarks are the property of their respective owners and are used here for identification purposes only.