Bahriya Tersane

Documentation / cloudnative-pg

CloudNativePG

The first step of running PostgreSQL with Bahriya Tersane: install this chart once per cluster, then create any number of PostgreSQL clusters with the postgresql chart, in any namespace.

It installs the CloudNativePG operator, which runs PostgreSQL on Kubernetes, and its Barman Cloud plugin, which takes backups of PostgreSQL to S3-compatible object storage and restores from them. It runs no database itself. The operator manages each PostgreSQL cluster continuously: it creates the instances, keeps a replica streaming from the primary, promotes a replica when the primary fails, switches the primary over before a rolling update, and rebuilds an instance whose node or volume is lost.

The chart installs CloudNativePG’s own Helm charts, unchanged, under the names operator and barmanCloud, with settings for a production cluster on your own premises:

  • every image from the Mamluk registry, pinned by digest;
  • two operator replicas, spread across nodes, with a PodDisruptionBudget, so that a cluster can fail over while a node is drained;
  • the pull secret copied by the operator into the namespace of every PostgreSQL cluster, so that no secret needs creating there;
  • CPU and memory requests and limits on every container;
  • every Pod meeting the restricted Pod Security Standard;
  • custom resource definitions kept on uninstall, so that removing the operator never deletes a database.

Prerequisites

  • Kubernetes 1.34 or later.
  • cert-manager, ready before this chart is installed. It is included with the Bahriya Kubernetes Engine; on other Kubernetes, install cert-manager first. Any release cert-manager still supports will do: the chart uses only its cert-manager.io/v1 resources, and is tested with cert-manager 1.21. The operator and the Barman Cloud plugin authenticate each other with certificates that cert-manager issues from a self-signed issuer this chart creates. The chart does not install cert-manager.
  • One operator per cluster. Its webhooks and custom resources are cluster-wide; do not install a second release, in any namespace.
  • A namespace of its own, conventionally cnpg-system. The postgresql chart’s NetworkPolicy admits the operator from this namespace; if you choose another, set networkPolicy.operatorNamespace in each PostgreSQL release.
  • A pull secret for 1x.ax named 1x-ax in that namespace, created from an image token as described in the access documentation.

Installation

helm install cnpg tersane/cloudnative-pg \
  --namespace cnpg-system --create-namespace \
  --version <chart version>

Check that the operator and the plugin are ready:

kubectl --namespace cnpg-system get deployments

Then create PostgreSQL clusters with the postgresql chart.

The pull secret

The operator copies the secret named in operator.config.data.PULL_SECRET_NAME (1x-ax) from its own namespace into the namespace of each PostgreSQL cluster, as <cluster>-pull, and every Pod of that cluster pulls with it.

To use a secret of another name, set both operator.imagePullSecrets and barmanCloud.imagePullSecrets, and operator.config.data.PULL_SECRET_NAME.

High availability

The operator runs two replicas. One leads and acts; the other waits and takes over if the leader stops. The PostgreSQL clusters keep running while no operator is running, but they cannot fail over, so the PodDisruptionBudget keeps one replica through a node drain.

The Barman Cloud plugin runs a single replica: CloudNativePG supports it only with the Recreate strategy. While it restarts, WAL archiving continues, because each PostgreSQL Pod’s sidecar archives its own WAL; base backups that fall due wait until it is back.

Upgrades

Upgrade the operator before the postgresql releases that need a newer one. The custom resource definitions are part of the chart’s templates, so helm upgrade updates them as well.

The operator’s image also carries the instance manager that runs in every PostgreSQL Pod. After an operator upgrade, the operator therefore restarts the instances of each PostgreSQL cluster with the new instance manager: the replicas one at a time, then the primary after a switchover to an updated replica. Applications see the same brief interruption as in any switchover. Upgrade the operator at a time that suits the databases.

Uninstalling

Remove every PostgreSQL cluster first, with helm uninstall of each postgresql release, and then:

helm uninstall cnpg --namespace cnpg-system

The custom resource definitions are kept. A PostgreSQL cluster left in place keeps running, without failover and without backups, until an operator is installed again. To remove CloudNativePG completely, delete its custom resource definitions afterwards; this deletes every PostgreSQL cluster still in the cluster, with its data:

kubectl get crd -o name | grep -E '\.(postgresql|barmancloud)\.cnpg\.io$' \
  | xargs kubectl delete

Metrics

The operator serves Prometheus metrics on port 8080 of its Pods. Each PostgreSQL instance serves its own on port 9187; see the postgresql chart.

Pod Security

Every Pod the chart creates meets the Kubernetes restricted Pod Security Standard, and so does every Pod the operator creates for a PostgreSQL cluster. Each runs as a user other than root, cannot escalate its privileges, drops all Linux capabilities and runs under the container runtime’s default seccomp profile. Install it in a namespace that enforces restricted.

Parameters

Values under operator are passed to CloudNativePG’s operator chart, and values under barmanCloud to its plugin chart. Those below are set by this chart; any other value of those charts may be set as well, at your own discretion.

Operator

Parameter Description Default
operator.replicaCount Operator replicas 2
operator.fullnameOverride The operator’s resource names. Do not change it. cnpg-controller-manager
operator.image.repository Operator image 1x.ax/tersane/core/cloudnative-pg/cloudnative-pg
operator.image.tag Operator image tag and digest Set in each release
operator.imagePullSecrets Pull secrets of the operator [{name: 1x-ax}]
operator.config.data.PULL_SECRET_NAME The pull secret copied into each PostgreSQL cluster’s namespace 1x-ax
operator.config.data.POSTGRES_IMAGE_NAME The PostgreSQL image of a cluster that names none the release’s
operator.resources Operator requests and limits 100m/256Mi, limits 1000m/512Mi
operator.topologySpreadConstraints Spread of the operator replicas across nodes by hostname
podDisruptionBudget.enabled Keep minAvailable operator replicas through a drain true
podDisruptionBudget.minAvailable Operator replicas kept 1

Barman Cloud plugin

Parameter Description Default
barmanCloud.image.registry Plugin image registry 1x.ax/tersane/core/cloudnative-pg
barmanCloud.image.tag Plugin image tag and digest Set in each release
barmanCloud.sidecarImage.registry Sidecar image registry 1x.ax/tersane/core/cloudnative-pg
barmanCloud.sidecarImage.tag Sidecar image tag and digest Set in each release
barmanCloud.imagePullSecrets Pull secrets of the plugin [{name: 1x-ax}]
barmanCloud.resources Plugin requests and limits 50m/64Mi, limits 500m/256Mi

The sidecar’s own resources are set per PostgreSQL cluster, by the postgresql chart’s backup.sidecarResources.