CloudNativePG Helm Installation

Install Operator

References

• CloudNativePG / Installation and upgrades
• CloudNativePG Helm Charts
• CloudNativePG Operator Chart

CloudNativePG is installed as a Kubernetes operator. The Helm chart installs the operator, CRDs, RBAC, webhook service, and controller deployment. It does not create a PostgreSQL cluster by itself.

The official chart repository is https://cloudnative-pg.github.io/charts. As of CloudNativePG 1.29, the operator chart supports only the latest point release of the CloudNativePG operator.

As of 2026-05-18, the operator chart README lists chart 0.28.2 with app version 1.29.1 and Kubernetes >=1.29.0-0. Recheck the chart repository before pinning a version in production.

helm repo add cnpg https://cloudnative-pg.github.io/charts
helm repo update cnpg

Check available chart versions before pinning a release:

helm search repo cnpg/cloudnative-pg --versions

Inspect the default values:

helm show values cnpg/cloudnative-pg \
  --version 0.28.2 \
  > cloudnative-pg-values.yaml

Use a values file for local overrides:

cloudnative-pg-values.yaml

replicaCount: 1

resources: {}

monitoring:
  podMonitorEnabled: false
  grafanaDashboard:
    create: false

Install the operator:

helm upgrade --install cnpg cnpg/cloudnative-pg \
  --kube-context <context> \
  --namespace cnpg-system \
  --create-namespace \
  --history-max 5 \
  --version 0.28.2 \
  -f cloudnative-pg-values.yaml

Verify

When installed through Helm, the default controller deployment name is cnpg-cloudnative-pg.

kubectl --context <context> rollout status deployment \
  -n cnpg-system \
  cnpg-cloudnative-pg

kubectl --context <context> get pods \
  -n cnpg-system

kubectl --context <context> get crd \
  clusters.postgresql.cnpg.io

Single Namespace

By default, the operator watches the whole Kubernetes cluster. To restrict the operator to the namespace where it is installed, set config.clusterWide=false:

helm upgrade --install cnpg cnpg/cloudnative-pg \
  --kube-context <context> \
  --namespace cnpg-system \
  --create-namespace \
  --history-max 5 \
  --version 0.28.2 \
  --set config.clusterWide=false \
  -f cloudnative-pg-values.yaml

Do not run a single-namespace operator and a cluster-wide operator against the same watched namespace. They can collide while reconciling CloudNativePG resources.

Upgrade

Read the CloudNativePG release notes before upgrading. Operator upgrades can trigger rolling updates of managed PostgreSQL instances because the instance manager in each PostgreSQL pod is updated after the controller is updated.

helm repo update cnpg
helm search repo cnpg/cloudnative-pg --versions

helm upgrade cnpg cnpg/cloudnative-pg \
  --kube-context <context> \
  --namespace cnpg-system \
  --history-max 5 \
  --version <chart-version> \
  -f cloudnative-pg-values.yaml

Uninstall Operator

Uninstalling the Helm release removes the operator deployment and chart-managed resources. Check existing PostgreSQL clusters and backup requirements before removing the operator from a production environment.

kubectl --context <context> get clusters.postgresql.cnpg.io --all-namespaces

helm uninstall cnpg \
  --kube-context <context> \
  --namespace cnpg-system

GKE Webhook Port

On GKE, admission webhook traffic from the control plane to nodes may be blocked unless the webhook port is allowed. CloudNativePG documents port 9443 as the webhook port involved in this failure mode.