Skip to content

3. Barman Cloud Plugin

Goal: install the Barman Cloud Plugin, the component that gives CloudNativePG its backup and restore capabilities against object storage. This is why we needed cert-manager.

Why a plugin at all?

Older CloudNativePG versions had object-store backups built in, configured under .spec.backup.barmanObjectStore in the Cluster. That in-tree support is deprecated since 1.26 and is being removed in 1.30. The replacement is the Barman Cloud Plugin, built on CNPG-I (the CloudNativePG plugin interface). We use the plugin so this guide stays valid past 1.30.

flowchart LR
    cl["Cluster"] -->|references by name| os["ObjectStore (R2)"]
    cl -->|plugin: barman-cloud.cloudnative-pg.io| plg["Barman Cloud Plugin"]
    plg -->|barman-cloud uploads| r2[("R2")]
    cm["cert-manager"] -->|issues TLS certs| plg
    op["CNPG operator"] <-->|mTLS over CNPG-I| plg

The plugin runs alongside the operator and uses the barman-cloud tool suite to push base backups and WAL to S3-compatible storage, and to restore them.

Step 3.1 — Confirm prerequisites

The plugin requires CloudNativePG ≥ 1.26 (we have 1.29.1) and a working cert-manager (installed in Layer 1).

# Operator version (must be ≥ 1.26)
kubectl get deployment -n cnpg-system cnpg-controller-manager \
  -o jsonpath='{.spec.template.spec.containers[*].image}'

# cert-manager API reachable
kubectl get crd | grep cert-manager.io

Same namespace as the operator

The plugin must be installed in the same namespace as the operator (cnpg-system by default). Installing it elsewhere leads to confusing failures.

Step 3.2 — Install the plugin (pinned)

kubectl apply -f \
  https://github.com/cloudnative-pg/plugin-barman-cloud/releases/download/v0.12.0/manifest.yaml

This registers the ObjectStore CRD (barmancloud.cnpg.io) and deploys the plugin into cnpg-system.

Step 3.3 — Verify

kubectl get pods -n cnpg-system            # a barman-cloud plugin pod is Running
kubectl get crd | grep barmancloud.cnpg.io # objectstores.barmancloud.cnpg.io

If the plugin pod is stuck waiting on certificates, cert-manager was not ready — revisit Layer 1.

How the Cluster will use it (preview)

You do not configure backups here. Later, the Cluster will reference the plugin and an ObjectStore like this (full version in The PostgreSQL Cluster):

  plugins:
    - name: barman-cloud.cloudnative-pg.io
      isWALArchiver: true
      parameters:
        barmanObjectName: pg-r2-store   # ← an ObjectStore resource

What could go wrong

  • cert-manager missing/not ready → plugin certificates never issue, plugin pod not Ready. Fix cert-manager first.
  • Plugin in the wrong namespace → the operator cannot find it; keep it in cnpg-system.
  • Version skew → use a plugin release compatible with your operator; with CNPG 1.29.1, plugin 0.12.0 is appropriate. Track both on their release pages.

Where to go deeper

Next: Image catalog — pinning the Postgres image.