plugin-barman-cloud/web/docs/usage.md

sidebar_position
30

Using the Barman Cloud Plugin

After installing the plugin in the same namespace as the CloudNativePG operator, enabling your PostgreSQL cluster to use the Barman Cloud Plugin involves just a few steps:

• Defining the object store containing your WAL archive and base backups, using your preferred provider
• Instructing the Postgres cluster to use the Barman Cloud Plugin

From that moment, you’ll be able to issue on-demand backups or define a backup schedule, as well as rely on the object store for recovery operations.

The rest of this page details each step, using MinIO as object store provider.

Defining the ObjectStore

An ObjectStore resource must be created for each object store used in your PostgreSQL architecture. Here's an example configuration using MinIO:

apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
  name: minio-store
spec:
  configuration:
    destinationPath: s3://backups/
    endpointURL: http://minio:9000
    s3Credentials:
      accessKeyId:
        name: minio
        key: ACCESS_KEY_ID
      secretAccessKey:
        name: minio
        key: ACCESS_SECRET_KEY
    wal:
      compression: gzip

The .spec.configuration schema follows the same format as the in-tree barman-cloud support. Refer to the CloudNativePG documentation for additional details.

:::important The serverName parameter in the ObjectStore resource is retained solely for API compatibility with the in-tree barmanObjectStore and must always be left empty. When needed, use the serverName plugin parameter in the Cluster configuration instead. :::

Configuring WAL Archiving

Once the ObjectStore is defined, you can configure your PostgreSQL cluster to archive WALs by referencing the store in the .spec.plugins section:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
spec:
  instances: 3
  imagePullPolicy: Always
  plugins:
  - name: barman-cloud.cloudnative-pg.io
    isWALArchiver: true
    parameters:
      barmanObjectName: minio-store
  storage:
    size: 1Gi

This configuration enables both WAL archiving and data directory backups.

By default, the plugin uses the Cluster name as the serverName archive namespace under the ObjectStore destinationPath. You can override it with the serverName plugin parameter. See Parameters for details.

Archive path separation for PostgreSQL major upgrades

The Barman Cloud Plugin does not automatically separate archives when you perform a PostgreSQL major version upgrade. If you keep the same serverName, the upgraded cluster continues to write backups and WAL files into the same object-store path used before the upgrade.

That is unsafe because pg_upgrade creates a new database system with a new System ID and resets the PostgreSQL timeline to 1. Reusing the same archive path can:

• overwrite or collide with previous timeline 1 history files
• mix backups and WAL files from different PostgreSQL majors in one archive
• cause timeline/history conflicts for replicas restoring from that archive

:::warning Point-in-time recovery (PITR) is not supported across major PostgreSQL version boundaries. Pre-upgrade backups cannot recover to a point in time after the upgrade. Take a new base backup as soon as possible after upgrading. :::

Recommended practice

Change the Cluster plugin serverName when you change imageName for the major upgrade. Existing backups and WAL files remain available under the old serverName path. New backups and WAL archives go to the new path.

Before upgrade (PostgreSQL 16):

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
spec:
  imageName: ghcr.io/cloudnative-pg/postgresql:16
  plugins:
    - name: barman-cloud.cloudnative-pg.io
      isWALArchiver: true
      parameters:
        barmanObjectName: prod-store
        serverName: cluster-pg16

After upgrade (PostgreSQL 18) — update both imageName and serverName together:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-example
spec:
  imageName: ghcr.io/cloudnative-pg/postgresql:18
  plugins:
    - name: barman-cloud.cloudnative-pg.io
      isWALArchiver: true
      parameters:
        barmanObjectName: prod-store
        serverName: cluster-pg18

With this configuration:

• pre-upgrade backups remain under serverName: cluster-pg16
• the upgraded cluster archives to serverName: cluster-pg18
• you can still recover the pre-upgrade cluster by pointing recovery externalClusters plugin parameters at the old serverName

For the full CloudNativePG major-upgrade procedure, including backup and WAL archive considerations, see the PostgreSQL major upgrades documentation.

Performing a Base Backup

Once WAL archiving is enabled, the cluster is ready for backups. Backups can be created either declaratively (with YAML manifests) or imperatively (with the cnpg plugin).

Declarative approach (YAML manifest)

Create a backup resource by applying a YAML manifest:

apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
  name: backup-example
spec:
  cluster:
    name: cluster-example
  method: plugin
  pluginConfiguration:
    name: barman-cloud.cloudnative-pg.io

Imperative approach (using the cnpg plugin)

The quickest way to trigger an on-demand backup is with the cnpg plugin:

kubectl cnpg backup -n <namespace> <cluster-name> \
  --method=plugin \
  --plugin-name=barman-cloud.cloudnative-pg.io

:::note Migration from in-tree backups If you are migrating from the in-tree backup system, note the change in syntax:

# Old command (in-tree backup)
kubectl cnpg backup -n <namespace> <cluster-name> --method=barmanObjectStore

# New command (plugin-based backup)
kubectl cnpg backup -n <namespace> <cluster-name> \
  --method=plugin \
  --plugin-name=barman-cloud.cloudnative-pg.io

:::

Restoring a Cluster

To restore a cluster from an object store, create a new Cluster resource that references the store containing the backup. Below is an example configuration:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-restore
spec:
  instances: 3
  imagePullPolicy: IfNotPresent
  bootstrap:
    recovery:
      source: source
  externalClusters:
  - name: source
    plugin:
      name: barman-cloud.cloudnative-pg.io
      parameters:
        barmanObjectName: minio-store
        serverName: cluster-example
  storage:
    size: 1Gi

:::important The above configuration does not enable WAL archiving for the restored cluster. :::

To enable WAL archiving for the restored cluster, include the .spec.plugins section alongside the externalClusters.plugin section, as shown below:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-restore
spec:
  instances: 3
  imagePullPolicy: IfNotPresent
  bootstrap:
    recovery:
      source: source
  plugins:
  - name: barman-cloud.cloudnative-pg.io
    isWALArchiver: true
    parameters:
      # Backup Object Store (push, read-write)
      barmanObjectName: minio-store-bis
  externalClusters:
  - name: source
    plugin:
      name: barman-cloud.cloudnative-pg.io
      parameters:
        # Recovery Object Store (pull, read-only)
        barmanObjectName: minio-store
        serverName: cluster-example
  storage:
    size: 1Gi

The same object store may be used for both transaction log archiving and restoring a cluster, or you can configure separate stores for these purposes.

Configuring Replica Clusters

You can set up a distributed topology by combining the previously defined configurations with the .spec.replica section. Below is an example of how to define a replica cluster:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: cluster-dc-a
spec:
  instances: 3
  primaryUpdateStrategy: unsupervised

  storage:
    storageClass: csi-hostpath-sc
    size: 1Gi

  plugins:
  - name: barman-cloud.cloudnative-pg.io
    isWALArchiver: true
    parameters:
      barmanObjectName: minio-store-a

  replica:
    self: cluster-dc-a
    primary: cluster-dc-a
    source: cluster-dc-b

  externalClusters:
  - name: cluster-dc-a
    plugin:
      name: barman-cloud.cloudnative-pg.io
      parameters:
        barmanObjectName: minio-store-a

  - name: cluster-dc-b
    plugin:
      name: barman-cloud.cloudnative-pg.io
      parameters:
        barmanObjectName: minio-store-b

Configuring the plugin instance sidecar

The Barman Cloud Plugin runs as a sidecar container next to each PostgreSQL instance pod. It manages backup, WAL archiving, and restore processes.

Configuration comes from multiple ObjectStore resources:

1. The one referenced in the .spec.plugins section of the Cluster. This is the object store used for WAL archiving and base backups.
2. The one referenced in the external cluster used in the .spec.replica.source section of the Cluster. This is used by the log-shipping designated primary to get the WAL files.
3. The one referenced in the .spec.bootstrap.recovery.source section of the Cluster. Used by the initial recovery job to create the cluster from an existing backup.

You can fine-tune sidecar behavior in the .spec.instanceSidecarConfiguration of your ObjectStore. These settings apply to all PostgreSQL instances that use this object store. Any updates take effect at the next Cluster reconciliation, and could generate a rollout of the Cluster.

apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
  name: minio-store
spec:
  configuration:
  # [...]
  instanceSidecarConfiguration:
    retentionPolicyIntervalSeconds: 1800
    resources:
      requests:
        memory: "XXX"
        cpu: "YYY"
      limits:
        memory: "XXX"
        cpu: "YYY"

:::note If more than one ObjectStore applies, the instanceSidecarConfiguration of the one set in .spec.plugins has priority. :::