Get started

CloudNativePG  is a Kubernetes operator that covers the full lifecycle of a PostgreSQL database cluster with a primary/standby architecture, using native streaming replication.

Before exploring the chart characteristics, let’s start by deploying the default configuration:

helm install <release-name> oci://dp.apps.rancher.io/charts/cloudnative-pg \
    --namespace cnpg-system --create-namespace \
    --set global.imagePullSecrets={application-collection}

Chart overview

The CloudNativePG Helm chart distributed in the Application Collection deploys the CloudNativePG operator, which introduces Custom Resource Definitions (CRDs) for managing PostgreSQL clusters.

By default, the chart sets up a single-replica operator as a cluster-wide controller, along with its required mutating and validating webhooks, RBAC roles, and service accounts.

Chart configuration

To view the supported configuration options and documentation, run:

helm show values oci://dp.apps.rancher.io/charts/cloudnative-pg

To view the contents of the Helm chart’s README file, run:

helm show readme oci://dp.apps.rancher.io/charts/cloudnative-pg

Operator scope

By default, the operator watches for PostgreSQL resources across all namespaces (clusterWide: true). If you want to restrict the operator to watch only specific namespaces, you can customize the config parameters in the values file on installation:

config:
  clusterWide: false
  data:
    WATCH_NAMESPACE: "my-database-namespace"

helm install <release-name> oci://dp.apps.rancher.io/charts/cloudnative-pg \
    --namespace cnpg-system \
    --set global.imagePullSecrets={application-collection} \
    --values scope.yaml

Deploy a PostgreSQL cluster

Unlike traditional database Helm charts, the CloudNativePG chart deploys a Kubernetes operator. Once the operator is running, you provision PostgreSQL databases by applying a Cluster Custom Resource (CR).

Below is a baseline example of a Cluster manifest that creates a PostgreSQL cluster with three replicas (one primary and two streaming replicas) and provisions a 1Gi persistent volume per replica:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
  namespace: default
spec:
  instances: 3
  storage:
    size: 1Gi

Apply the manifest to your cluster to spin up the database:

kubectl apply -f cluster.yaml

You can monitor the provisioning status and health of your cluster by querying the custom resource:

kubectl get cluster cluster-example

To connect to the database, you can use the credentials automatically generated by the operator, which are stored in a Kubernetes Secret named <cluster-name>-app:

export PGPASSWORD=$(kubectl get secret cluster-example-app -o jsonpath='{.data.password}' | base64 -d)
 
kubectl run -it --rm pg-client \
    --env="PGPASSWORD=$PGPASSWORD" \
    --restart=Never \
    --image=dp.apps.rancher.io/containers/postgresql:18.4-13.4 \
    -- psql -h cluster-example-rw -U app -d app

Metrics

CloudNativePG provides robust observability natively. The Helm chart can automatically deploy a PodMonitor for Prometheus scraping and configure Grafana dashboards. It also automatically generates a ConfigMap containing default Prometheus monitoring queries for PostgreSQL backends, replication slots, bgwriter, and checkpointer statistics.

To enable Prometheus scraping and create the Grafana dashboard, provide the following values:

monitoring:
  podMonitorEnabled: true
  grafanaDashboard:
    create: true
    namespace: monitoring
    labels:
      grafana_dashboard: "1"

Container Images

The operator automatically manages the lifecycle of PostgreSQL clusters and PgBouncer connection poolers. The default container images for these components are managed by the operator but can be overridden globally in the chart values if you require specific application versions:

images:
  postgresql:
    registry: dp.apps.rancher.io
    repository: containers/postgresql
    tag: 18.4-13.4
  pgbouncer:
    registry: dp.apps.rancher.io
    repository: containers/pgbouncer
    tag: 1.25.2-10.2

High availability

The operator relies heavily on mutating and validating admission webhooks to validate Custom Resources upon creation or update. For production environments, it is recommended to scale the operator deployments for high availability by increasing the replicaCount.

replicaCount: 3

helm install <release-name> oci://dp.apps.rancher.io/charts/cloudnative-pg \
    --namespace cnpg-system \
    --set global.imagePullSecrets={application-collection} \
    --values ha.yaml

Operations

Upgrade the chart

In-place upgrades of the CloudNativePG operator can be performed using the standard Helm upgrade workflow:

helm upgrade <release-name> oci://dp.apps.rancher.io/charts/cloudnative-pg \
    --namespace cnpg-system --reuse-values

Uninstall the chart

Removing the installed CloudNativePG Helm chart release is simple:

helm uninstall <release-name> --namespace cnpg-system