Skip to main content
Version: Dev

Installation

important

  1. The plugin must be installed in the same namespace as the CloudNativePG operator (typically cnpg-system).

  2. Keep in mind that the operator's listening namespaces may differ from its installation namespace. Double-check this to avoid configuration issues.

Verifying the Requirements​

Before installing the plugin, make sure the requirements are met.

CloudNativePG Version​

Ensure you're running a version of CloudNativePG that is compatible with the plugin. If installed in the default cnpg-system namespace, you can verify the version with:

kubectl get deployment -n cnpg-system cnpg-controller-manager \
  -o jsonpath="{.spec.template.spec.containers[*].image}"

Example output:

ghcr.io/cloudnative-pg/cloudnative-pg:1.30.1

The version must be 1.30 or newer.

cert-manager​

Use the cmctl tool to confirm that cert-manager is installed and available:

cmctl check api

Example output:

The cert-manager API is ready

Both checks are required before proceeding with the installation.

Installing the Barman Cloud Plugin​

The plugin can be installed using the provided Helm chart. This installs the latest published chart release; to test an unreleased development snapshot instead, switch to the Manifest (kubectl) tab.

helm repo add cnpg https://cloudnative-pg.github.io/charts --force-update
helm upgrade --install plugin-barman-cloud \
  --namespace cnpg-system \
  cnpg/plugin-barman-cloud

Example output:

Release "plugin-barman-cloud" does not exist. Installing it now.
NAME: plugin-barman-cloud
LAST DEPLOYED: Wed Jul  1 09:05:16 2026
NAMESPACE: cnpg-system
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
TEST SUITE: None

Finally, check that the deployment is up and running:

kubectl -n cnpg-system rollout status deploy/plugin-barman-cloud

Example output:

deployment "plugin-barman-cloud" successfully rolled out

This confirms that the plugin is deployed and ready to use.

Running Multiple Replicas​

The plugin Deployment can run with more than one replica for high availability. Every replica serves the gRPC interface used by the CloudNativePG operator, so the barman-cloud Service load-balances requests across all ready pods. The ObjectStore controller uses leader election, so only one replica reconciles ObjectStore resources at a time; the others take over automatically if the leader is lost.

To scale the plugin:

kubectl -n cnpg-system scale deploy/barman-cloud --replicas=2

The Deployment keeps the Recreate strategy: during an upgrade all replicas are replaced together, so the plugin is briefly unavailable regardless of the replica count. Multiple replicas protect against pod or node loss, not against upgrade downtime.

Restricting the Watched Namespaces​

By default the plugin operator works on every namespace. To limit it, set the WATCH_NAMESPACE environment variable on the plugin Deployment to a comma-separated list of namespaces:

kubectl -n cnpg-system set env deploy/barman-cloud WATCH_NAMESPACE=app1,app2

The plugin then only handles Cluster and ObjectStore resources in those namespaces. A Cluster in any other namespace fails with an error when it uses the plugin. When the variable is unset or empty, all namespaces are watched.

The variable does not change the RBAC rules that come with the installation. To drop the cluster-wide permissions, grant the plugin a namespaced Role and RoleBinding in each listed namespace. Without them in every listed namespace, the plugin cannot work.

Testing the latest development snapshot​

The kubectl install command above already applies the latest development snapshot from the main branch.