cloudnative-pg · itay-grudev · Jun 19, 2026 · Jun 20, 2026 · Jun 20, 2026 · Jun 20, 2026
@@ -42,6 +42,15 @@ jobs:
       - name: Deploy the operator
         uses: ./.github/actions/deploy-operator
 
+      - name: Install cert-manager
+        uses: ./.github/actions/deploy-cert-manager
+
+      - name: Install Barman CNPG-I plugin
+        run: |
+          helm upgrade --install plugin-barman-cloud \
+            --namespace cnpg-system \
+            ./charts/plugin-barman-cloud
+
       - name: Install Prometheus CRDs
         run: |
           helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

@@ -26,6 +26,42 @@ That being said, we welcome PRs that improve the chart, but please keep in mind
 single configuration that the operator provides and we may reject PRs that add too much complexity and maintenance
 difficulty to the chart.
 
+Migrating to the Barman Cloud Plugin
+------------------------------------
+
+> [!WARNING]  
+> Starting with version 1.26, native backup and recovery capabilities are
+> being **progressively phased out** of the core operator and moved to official
+> CNPG-I plugins. This transition aligns with CloudNativePG's shift towards a
+> **backup-agnostic architecture**, enabled by its extensible
+> interface—**CNPG-I**—which standardizes the management of **WAL archiving**,
+> **physical base backups**, and corresponding **recovery processes**.
+
+Migrating from the Built-in CloudNativePG Backup to the Barman Cloud CNPG-I 
+plugin is a straightforward, single step process, as the chart creates the 
+necessary `ObjectStore` resource as a helm hook before the cluster is updated.
+
+All you have to do is change the backup method from `barmanObjectStore` to 
+`plugin` and specify the plugin name. The same change should also be applied to
+your scheduled backups.
+
+```diff
+backups:
+  enabled: true
+- method: barmanObjectStore
++ method: plugin
++ pluginConfiguration:
++   name: barman-cloud.cloudnative-pg.io
+  scheduledBackups:
+    - name: daily-backup
+      schedule: "0 0 0 * * *"
+      backupOwnerReference: self
+-     method: barmanObjectStore
++     method: plugin
++     pluginConfiguration:
++       name: barman-cloud.cloudnative-pg.io
+```
+
 Getting Started
 ---------------
 
@@ -136,6 +172,9 @@ Kubernetes: `>=1.29.0-0`
 | backups.google.bucket | string | `""` |  |
 | backups.google.gkeEnvironment | bool | `false` |  |
 | backups.google.path | string | `"/"` |  |
+| backups.instanceSidecarConfiguration | object | `{}` | The configuration for the Barman Cloud Plugin sidecar that runs in the instance pods. See: https://cloudnative-pg.io/plugin-barman-cloud/docs/next/plugin-barman-cloud.v1/#instancesidecarconfiguration |
+| backups.method | string | `"barmanObjectStore"` | One of `barmanObjectStore` (default) or `plugin` |
+| backups.pluginConfiguration | object | `{}` |  |
 | backups.provider | string | `"s3"` | One of `s3`, `azure` or `google` |
 | backups.retentionPolicy | string | `"30d"` | Retention policy for backups |
 | backups.s3.accessKey | string | `""` |  |
@@ -145,8 +184,9 @@ Kubernetes: `>=1.29.0-0`
 | backups.s3.region | string | `""` |  |
 | backups.s3.secretKey | string | `""` |  |
 | backups.scheduledBackups[0].backupOwnerReference | string | `"self"` | Backup owner reference |
-| backups.scheduledBackups[0].method | string | `"barmanObjectStore"` | Backup method, can be `barmanObjectStore` (default) or `volumeSnapshot` |
+| backups.scheduledBackups[0].method | string | `"barmanObjectStore"` | Backup method, can be `barmanObjectStore` (default), `volumeSnapshot` or `plugin`. |
 | backups.scheduledBackups[0].name | string | `"daily-backup"` | Scheduled backup name |
+| backups.scheduledBackups[0].pluginConfiguration | object | `{}` |  |
 | backups.scheduledBackups[0].schedule | string | `"0 0 0 * * *"` | Schedule in cron format |
 | backups.secret.create | bool | `true` | Whether to create a secret for the backup credentials |
 | backups.secret.name | string | `""` | Name of the backup credentials secret |
@@ -182,6 +222,7 @@ Kubernetes: `>=1.29.0-0`
 | cluster.monitoring.prometheusRule.enabled | bool | `true` | Whether to enable the PrometheusRule automated alerts |
 | cluster.monitoring.prometheusRule.excludeRules | list | `[]` | Exclude specified rules |
 | cluster.monitoring.tls.enabled | bool | `false` | Whether to enable TLS on the metrics port. |
+| cluster.plugins | list | `[]` | Plugins When adding `barman-cloud.cloudnative-pg.io`, just specify the plugin name and set `isWALArchiver` to true. The chart will then provision an `ObjectStore` resource with the configuration from the `backups.barmanObjectStore` section. |
 | cluster.podSecurityContext | object | `{}` | Configure the Pod Security Context. See: https://cloudnative-pg.io/documentation/preview/security/ |
 | cluster.postgresGID | int | `-1` | The GID of the postgres user inside the image, defaults to 26 |
 | cluster.postgresUID | int | `-1` | The UID of the postgres user inside the image, defaults to 26 |
@@ -255,7 +296,8 @@ Kubernetes: `>=1.29.0-0`
 | recovery.import.source.sslRootCertSecret.name | string | `""` |  |
 | recovery.import.source.username | string | `""` |  |
 | recovery.import.type | string | `"microservice"` | One of `microservice` or `monolith.` See: https://cloudnative-pg.io/documentation/current/database_import/#how-it-works |
-| recovery.method | string | `"backup"` | Available recovery methods: * `backup` - Recovers a CNPG cluster from a CNPG backup (PITR supported) Needs to be on the same cluster in the same namespace. * `object_store` - Recovers a CNPG cluster from a barman object store (PITR supported). * `pg_basebackup` - Recovers a CNPG cluster viaa streaming replication protocol. Useful if you want to        migrate databases to CloudNativePG, even from outside Kubernetes. * `import` - Import one or more databases from an existing Postgres cluster. |
+| recovery.instanceSidecarConfiguration | object | `{}` | The configuration for the Barman Cloud Plugin sidecar that runs in the instance pods. See: https://cloudnative-pg.io/plugin-barman-cloud/docs/next/plugin-barman-cloud.v1/#instancesidecarconfiguration |
+| recovery.method | string | `"backup"` | Available recovery methods: * `backup` - Recovers a CNPG cluster from a CNPG backup (PITR supported) Needs to be on the same cluster in the same namespace. * `plugin` - Recovers a CNPG cluster from a backup taken with a CloudNativePG plugin (e.g. barman-cloud). * `object_store` - Recovers a CNPG cluster from a barman object store (PITR supported). * `pg_basebackup` - Recovers a CNPG cluster viaa streaming replication protocol. Useful if you want to        migrate databases to CloudNativePG, even from outside Kubernetes. * `import` - Import one or more databases from an existing Postgres cluster. |
 | recovery.owner | string | `""` | Name of the owner of the database in the instance to be used by applications. Defaults to the value of the `database` key. |
 | recovery.pgBaseBackup.database | string | `"app"` | Name of the database used by the application. Default: `app`. |
 | recovery.pgBaseBackup.owner | string | `""` | Name of the owner of the database in the instance to be used by applications. Defaults to the value of the `database` key. |
@@ -277,6 +319,7 @@ Kubernetes: `>=1.29.0-0`
 | recovery.pgBaseBackup.source.username | string | `""` |  |
 | recovery.pitrTarget | object | `{"time":""}` | Point in time recovery target. Specify one of the following: |
 | recovery.pitrTarget.time | string | `""` | Time in RFC3339 format |
+| recovery.pluginConfiguration | object | `{}` |  |
 | recovery.provider | string | `"s3"` | One of `s3`, `azure` or `google` |
 | recovery.s3.accessKey | string | `""` |  |
 | recovery.s3.bucket | string | `""` |  |

@@ -75,6 +75,14 @@ Configuration
   {{- $image = $image.imageName -}}
 {{- end }}
 
+{{- $backupPlugin := "" -}}
+{{- if eq .Values.backups.method "plugin" -}}
+  {{- $backupPlugin = (get (include "helpers.fetchKeyValue" (list .Values.cluster.plugins (list (list "isWALArchiver" true))) | fromYaml) "name") -}}
+  {{- if and (empty $backupPlugin)  (eq (include "cluster.barmanPluginRequired" .) "true") -}}
+  {{- $backupPlugin = "barman-cloud.cloudnative-pg.io" -}}
+  {{- end -}}
+{{- end }}
+
 ╭───────────────────┬──────────────────────────────────────────────────────────╮
 │ Configuration     │ Value                                                    │
 ┝━━━━━━━━━━━━━━━━━━━┿━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┥
@@ -87,7 +95,7 @@ Configuration
 │ Instances         │ {{ include (printf "%s%s" "cluster.color-" $redundancyColor) (printf "%-56s" (toString .Values.cluster.instances)) }} │
 │ Backups           │ {{ include (printf "%s%s" "cluster.color-" (ternary "ok" "error" .Values.backups.enabled)) (printf "%-56s" (ternary "Enabled" "Disabled" .Values.backups.enabled)) }} │
 {{- if .Values.backups.enabled }}
-│ Backup Provider   │ {{ printf "%-56s" (title .Values.backups.provider) }} │
+│ Backup Provider   │ {{ printf "%-56s" (cat (title .Values.backups.method) (empty $backupPlugin | ternary "" (printf "(%s)" $backupPlugin))) }} │
 │ Scheduled Backups │ {{ printf "%-56s" $scheduledBackups }} │
 {{- end }}
 │ Storage           │ {{ printf "%-56s" .Values.cluster.storage.size }} │

@@ -1,5 +1,5 @@
 {{- define "cluster.backup" -}}
-{{- if .Values.backups.enabled }}
+{{- if and .Values.backups.enabled ((eq .Values.backups.method "barmanObjectStore")) }}
 backup:
   target: "prefer-standby"
   retentionPolicy: {{ .Values.backups.retentionPolicy }}

@@ -91,6 +91,8 @@ bootstrap:
       name: {{ .Values.recovery.backupName }}
     {{- else if eq .Values.recovery.method "object_store" }}
     source: objectStoreRecoveryCluster
+    {{- else if eq .Values.recovery.method "plugin" }}
+    source: pluginRecoveryCluster
     {{- end }}
   {{- end }}
 {{- else if eq .Values.mode "replica" }}

@@ -1,7 +1,9 @@
 {{- define "cluster.externalClusters" -}}
 {{- if eq .Values.mode "standalone" }}
 {{- else }}
+{{- if not (and (eq .Values.mode "recovery") (eq .Values.recovery.method "backup")) }}
 externalClusters:
+{{- end }}
 {{- if eq .Values.mode "recovery" }}
   {{- if eq .Values.recovery.method "pg_basebackup" }}
   - name: pgBaseBackupSource
@@ -15,6 +17,17 @@ externalClusters:
       serverName: {{ .Values.recovery.clusterName }}
       {{- $d := dict "chartFullname" (include "cluster.fullname" .) "scope" .Values.recovery "secretPrefix" "recovery" -}}
       {{- include "cluster.barmanObjectStoreConfig" $d | nindent 4 }}
+  {{- else if and (eq .Values.recovery.method "plugin") (eq .Values.recovery.pluginConfiguration.name "barman-cloud.cloudnative-pg.io") }}
+  - name: pluginRecoveryCluster
+    plugin:
+      {{- omit .Values.recovery.pluginConfiguration "parameters" | toYaml | nindent 6 }}
+      parameters:
+        {{- $pluginConfigurationParameters := omit (coalesce .Values.recovery.pluginConfiguration.parameters dict) "barmanObjectName" "serverName" -}}
+        {{ with $pluginConfigurationParameters }}
+        {{- toYaml . | nindent 8 -}}
+        {{ end }}
+        barmanObjectName: {{ include "cluster.fullname" . }}-recovery
+        serverName: {{ .Values.recovery.clusterName }}
   {{- end }}
 {{- else if eq .Values.mode "replica" }}
   - name: originCluster

@@ -144,3 +144,99 @@ Postgres GID
     {{- 26 -}}
   {{- end -}}
 {{- end -}}
+
+
+{{/*
+Check if a list of objects has a set key value pairs
+*/}}
+{{- /* Usage: {{ include "helpers.hasKeyValue" (list .Values.list (list (list "key" "value"))) }} */}}
+{{- /* Returns the string true if the list has an item matching the key value pairs */}}
+{{- define "helpers.hasKeyValue" -}}
+  {{- $list := index . 0 }}
+  {{- $kvPairs := index . 1 }}
+
+  {{- range $list }}
+    {{- $item := . }}
+    {{- $valid := true }}
+    {{- range $kvPairs }}
+      {{- $key := index . 0 -}}
+      {{- $value := index . 1 -}}
+      {{- if or (not (hasKey $item $key)) (not (eq (get $item $key) $value)) -}}
+        {{- $valid = false -}}
+        {{- break -}}
+      {{- end -}}
+    {{- end -}}
+    {{- if $valid -}}
+      {{- "true" -}}
+      {{- break -}}
+    {{- end -}}
+  {{- end -}}
+{{- end -}}
+
+{{/*
+Similar to the omit function, returns a list of items that do not match the key value pairs
+*/}}
+{{- /* Usage: {{ include "helpers.omitKeyValue" (list .Values.list (list (list "key" "value"))) }} */}}
+{{- /* Returns a YAML list without the items matching the key value pairs */}}
+{{- define "helpers.omitKeyValue" -}}
+  {{- $list := index . 0 }}
+  {{- $kvPairs := index . 1 }}
+  {{- $newList := list }}
+
+  {{- range $list }}
+    {{- $item := . }}
+    {{- $shouldOmit := false }}
+    {{- range $kvPairs }}
+      {{- $key := index . 0 -}}
+      {{- $value := index . 1 -}}
+      {{- if and (hasKey $item $key) (eq (get $item $key) $value) -}}
+        {{- $shouldOmit = true -}}
+      {{- end -}}
+    {{- end -}}
+    {{- if not $shouldOmit -}}
+      {{- $newList = append $newList $item -}}
+    {{- end -}}
+  {{- end -}}
+  {{- $newList | toYaml }}
+{{ end -}}
+
+
+{{/*
+Given a list of objects, returns the first item that matches the key value pairs specified
+*/}}
+{{- /* Usage: {{ include "helpers.fetchKeyValue" (list .Values.list (list (list "key" "value"))) }} */}}
+{{- /* Returns a YAML object of the first item in the list has an item matching the key value pairs */}}
+{{- define "helpers.fetchKeyValue" -}}
+  {{- $list := index . 0 }}
+  {{- $kvPairs := index . 1 }}
+  {{- range $list }}
+    {{- $item := . }}
+    {{- $valid := true }}
+    {{- range $kvPairs }}
+      {{- $key := index . 0 -}}
+      {{- $value := index . 1 -}}
+      {{- if or (not (hasKey $item $key)) (not (eq (get $item $key) $value)) -}}
+        {{- $valid = false -}}
+        {{- break -}}
+      {{- end -}}
+    {{- end -}}
+    {{- if $valid -}}
+      {{- toYaml $item -}}
+      {{- break -}}
+    {{- end -}}
+  {{- end -}}
+{{- end -}}
+
+{{- define "cluster.barmanPluginEnabled" -}}
+  {{- eq (include "helpers.hasKeyValue" (list .Values.cluster.plugins (list (list "name" "barman-cloud.cloudnative-pg.io") (list "isWALArchiver" true)))) "true" -}}
+{{- end -}}
+
+{{- define "cluster.barmanPluginRequired" -}}
+  {{- $required := false -}}
+  {{- if and .Values.backups.enabled (eq .Values.backups.method "plugin") -}}
+    {{- if eq .Values.backups.pluginConfiguration.name "barman-cloud.cloudnative-pg.io" -}}
+      {{- $required = true -}}
+    {{- end -}}
+  {{- end -}}
+  {{- $required -}}
+{{- end -}}
@@ -0,0 +1,36 @@
+{{- if eq (include "cluster.barmanPluginRequired" .) "true" }}
+apiVersion: barmancloud.cnpg.io/v1
+kind: ObjectStore
+metadata:
+  name: {{ include "cluster.fullname" . }}-backups
+  namespace: {{ include "cluster.namespace" . }}
+  annotations:
+    "helm.sh/hook": pre-install,pre-upgrade,pre-rollback
+    {{- with .Values.cluster.annotations }}
+      {{- toYaml . | nindent 4 }}
+    {{- end }}
+  labels:
+  {{- include "cluster.labels" . | nindent 4 }}
+  {{- with .Values.cluster.additionalLabels }}
+    {{ toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  retentionPolicy: {{ .Values.backups.retentionPolicy }}
+  configuration:
+    wal:
+      compression: {{ .Values.backups.wal.compression }}
+      {{- if .Values.backups.wal.encryption }}
+      encryption: {{ .Values.backups.wal.encryption }}
+      {{- end }}
+      maxParallel: {{ .Values.backups.wal.maxParallel }}
+    data:
+      compression: {{ .Values.backups.data.compression }}
+      {{- if .Values.backups.data.encryption }}
+      encryption: {{ .Values.backups.data.encryption }}
+      {{- end }}
+      jobs: {{ .Values.backups.data.jobs }}
+    {{- $d := dict "chartFullname" (include "cluster.fullname" .) "scope" .Values.backups "secretPrefix" "backup" }}
+    {{- include "cluster.barmanObjectStoreConfig" $d | nindent 2 }}
+  instanceSidecarConfiguration:
+    {{- .Values.backups.instanceSidecarConfiguration | toYaml | nindent 4 }}
+{{- end }}
@@ -1,3 +1,4 @@
+{{- if and .Values.backups.enabled (or ((eq .Values.backups.method "barmanObjectStore")) (eq (include "cluster.barmanPluginEnabled" .) "true")) }}
 {{- if .Values.backups.endpointCA.create }}
 apiVersion: v1
 kind: Secret
@@ -7,3 +8,4 @@ metadata:
 data:
   {{ .Values.backups.endpointCA.key | default "ca-bundle.crt" | quote }}: {{ .Values.backups.endpointCA.value }}
 {{- end }}
+{{- end }}
@@ -56,6 +56,9 @@ spec:
 
   primaryUpdateMethod: {{ .Values.cluster.primaryUpdateMethod }}
   primaryUpdateStrategy: {{ .Values.cluster.primaryUpdateStrategy }}
+  {{- with .Values.cluster.stopDelay }}
+  stopDelay: {{ . }}
+  {{- end }}
   logLevel: {{ .Values.cluster.logLevel }}
   {{- with .Values.cluster.certificates }}
   certificates:
@@ -148,6 +151,28 @@ spec:
     {{- end }}
     tls:
       enabled: {{ .Values.cluster.monitoring.tls.enabled }}
-  {{ include "cluster.bootstrap" . | nindent 2 }}
-  {{ include "cluster.externalClusters" . | nindent 2 }}
-  {{ include "cluster.backup" . | nindent 2 }}
+
+  {{ include "cluster.bootstrap" . | nindent 2 -}}
+  {{ include "cluster.externalClusters" . | nindent 2 -}}
+  {{ include "cluster.backup" . | nindent 2 -}}
+
+  {{- if or (gt (len .Values.cluster.plugins) 0) (eq (include "cluster.barmanPluginRequired" .) "true") }}
+  plugins:
+    {{ $pluginsWithoutBarman := include "helpers.omitKeyValue" (list .Values.cluster.plugins (list (list "name" "barman-cloud.cloudnative-pg.io"))) | fromYamlArray }}
+    {{- range $pluginsWithoutBarman -}}
+    - {{ toYaml . | indent 6 | trim }}
+    {{- end }}
+    {{- if or (eq (include "cluster.barmanPluginEnabled" .) "true") (eq (include "cluster.barmanPluginRequired" .) "true") }}
+    {{- $barmanPlugin := include "helpers.fetchKeyValue" (list .Values.cluster.plugins (list (list "name" "barman-cloud.cloudnative-pg.io"))) | fromYaml }}
+    - name: barman-cloud.cloudnative-pg.io
+      enabled: {{ eq $barmanPlugin.enabled nil | ternary (eq (include "cluster.barmanPluginRequired" .) "true") $barmanPlugin.enabled }}
+      isWALArchiver: {{ eq $barmanPlugin.isWALArchiver nil | ternary (eq (include "cluster.barmanPluginRequired" .) "true") $barmanPlugin.isWALArchiver }}
+      parameters:
+        {{- $parameters := (coalesce $barmanPlugin.parameters dict) -}}
+        {{- $parametersWithoutObjectName := (omit $parameters "barmanObjectName") }}
+        {{ with $parametersWithoutObjectName }}
+          {{- toYaml . | indent 8 | trim }}
+        {{- end }}
+        barmanObjectName: {{ $parameters.barmanObjectName | default (printf "%s-backups" (include "cluster.fullname" .)) }}
+    {{- end }}
+  {{- end }}
@@ -0,0 +1,23 @@
+{{- if and (eq .Values.mode "recovery") (eq .Values.recovery.method "plugin") (eq .Values.recovery.pluginConfiguration.name "barman-cloud.cloudnative-pg.io") }}
+apiVersion: barmancloud.cnpg.io/v1
+kind: ObjectStore
+metadata:
+  name: {{ include "cluster.fullname" . }}-recovery
+  namespace: {{ include "cluster.namespace" . }}
+  annotations:
+    "helm.sh/hook": pre-install,pre-upgrade,pre-rollback
+    {{- with .Values.cluster.annotations }}
+      {{- toYaml . | nindent 4 }}
+    {{- end }}
+  labels:
+  {{- include "cluster.labels" . | nindent 4 }}
+  {{- with .Values.cluster.additionalLabels }}
+    {{ toYaml . | nindent 4 }}
+  {{- end }}
+spec:
+  configuration:
+    {{- $d := dict "chartFullname" (include "cluster.fullname" .) "scope" .Values.recovery "secretPrefix" "recovery" -}}
+    {{- include "cluster.barmanObjectStoreConfig" $d | indent 2 }}
+  instanceSidecarConfiguration:
+    {{- .Values.recovery.instanceSidecarConfiguration | toYaml | nindent 4 }}
+{{- end }}
@@ -1,4 +1,4 @@
-{{- if and (eq .Values.mode "recovery" ) (eq .Values.recovery.method "object_store") (eq .Values.recovery.provider "s3") (not .Values.recovery.s3.inheritFromIAMRole) .Values.recovery.secret.create }}
+{{- if and (eq .Values.mode "recovery" ) (eq .Values.recovery.provider "s3") (not (has .Values.recovery.method (list "backup" "import" "pg_basebackup"))) (not .Values.recovery.s3.inheritFromIAMRole) .Values.recovery.secret.create }}
 apiVersion: v1
 kind: Secret
 metadata: