Une sauvegarde CNPG exploitable envoie deux flux vers un stockage objet, via le plugin Barman Cloud :
- l'archivage continu des WAL ;
- des base backups physiques réguliers.
La chaîne tient en cinq gestes :
- installer le plugin dans le namespace de l'opérateur ;
- déclarer un
ObjectStore; - brancher le
Clusterdessus ; - créer un
Backup; - créer un
ScheduledBackup.
Configuration validée avec CNPG 1.30.1, plugin Barman Cloud 0.16.0 et PostgreSQL 17.6. Adaptez identifiants S3, StorageClass et noms à votre cluster. Un Backup terminé et des WAL présents prouvent que l'envoi fonctionne. Ils ne prouvent pas que vous savez restaurer : la dernière section y revient.
Comment fonctionnent les backups CNPG avec Barman Cloud ?
CNPG sauvegarde PostgreSQL en physique :
- un base backup : copie de
PGDATAprise à chaud ; - l'archive continue des WAL, le journal des transactions.
Un base backup à chaud n'est pas cohérent seul. Les WAL écrits pendant sa prise corrigent ses incohérences à la restauration. Les WAL suivants permettent d'avancer jusqu'à l'instant voulu (PostgreSQL 17). L'archive WAL sans base backup ne sert à rien (CNPG, Backup). La réplication n'est pas une sauvegarde : un DROP TABLE se propage au standby.
Deux objectifs guident les réglages :
- le RPO, la quantité de données perdues après un sinistre, dépend de l'archivage des WAL ;
- le RTO, la durée d'indisponibilité acceptable, dépend de la taille du dernier base backup et du nombre de WAL à rejouer. La fréquence des base backups joue donc sur lui.
CNPG fixe archive_timeout à 5min. Sous activité, PostgreSQL force alors la rotation du segment WAL courant au bout de 5 minutes (WAL archiving). Le transfert vers le bucket vient ensuite, sans garantie de délai. Ce n'est pas un RPO garanti : un transfert lent ou en échec laisse des WAL non archivés.
Le plugin Barman Cloud (CNPG-I) est la voie à suivre. Le support natif .spec.backup.barmanObjectStore est déprécié depuis CNPG 1.26. Le calendrier de retrait a changé d'une annonce à l'autre : lisez les notes de version de la version que vous déployez avant de planifier une migration.
Quels prérequis installer pour utiliser le plugin Barman Cloud ?
Il faut CNPG 1.30 ou plus, le plugin dans le même namespace que l'opérateur, et un TLS entre les deux. Ce tutoriel utilise cert-manager, voie recommandée par la documentation 0.16.0. Vous pouvez aussi fournir vos propres certificats.
Prévoyez :
kubectlet Helm sur votre poste ;- un cluster Kubernetes où vous avez les droits d'administration (namespaces, CRD, ClusterRole) ;
- un accès réseau aux dépôts de charts (
charts.jetstack.io,cloudnative-pg.github.io,bedag.github.io) et aux registres d'images (quay.io,ghcr.io, Docker Hub) ; - une StorageClass pour le volume PostgreSQL (
kubectl get storageclass). Les exemples utilisentlocal-path: remplacezstorageClassdans le Cluster par la vôtre ; - un S3 préconfiguré : un bucket créé, accessible depuis le cluster, et une clé d'accès. Depuis Barman Cloud 3.16, le bucket n'est plus créé automatiquement ;
- un namespace pour le Cluster, l'
ObjectStoreet le Secret :donneesdans les exemples.
Versions déployées :
| Composant | Version |
|---|---|
| Kubernetes | v1.37.1+k3s1 |
| kubectl | v1.37.2 |
| CNPG | 1.30.1 (chart 0.29.1) |
| Plugin Barman Cloud | v0.16.0 (chart 0.9.0), sidecar v0.16.0 |
| barman-cloud-backup | 3.20.1 |
| cert-manager | v1.21.3 (chart et images) |
| PostgreSQL | 17.6 (ghcr.io/cloudnative-pg/postgresql:17.6) |
Chart Helm raw (Bedag) |
2.0.2 |
Les matrices de support se recoupent ainsi :
- les charts acceptent Kubernetes 1.29 ou plus ;
- CNPG 1.30 supporte Kubernetes 1.34 à 1.36 ;
- cert-manager 1.21 supporte Kubernetes 1.33 à 1.36.
Prenez une version présente dans les deux matrices, par exemple 1.36. La version observée, 1.37, est hors de ces matrices. Lisez aussi la documentation versionnée du plugin : la page non versionnée affichait « CNPG ≥ 1.26 », la 0.16.0 exige 1.30. Sources : CNPG 1.30.1, cert-manager.
Installation, versions épinglées :
helm upgrade --install cert-manager cert-manager --repo https://charts.jetstack.io --version v1.21.3 --namespace cert-manager --create-namespace --set crds.enabled=true --wait --timeout 180s
helm upgrade --install cnpg cloudnative-pg --repo https://cloudnative-pg.github.io/charts --version 0.29.1 --namespace cnpg-system --create-namespace --wait --timeout 180s
helm upgrade --install plugin-barman-cloud plugin-barman-cloud --repo https://cloudnative-pg.github.io/charts --version 0.9.0 --namespace cnpg-system --wait --timeout 180s
kubectl get deployments -A -o wide
kubectl -n cnpg-system get services -o yaml
Tous les déploiements sont à 1/1. Trois points à retenir :
- le nom du plugin dans le Cluster (
barman-cloud.cloudnative-pg.io) doit correspondre au labelcnpg.io/pluginNamedu servicebarman-cloud, dans le namespace de l'opérateur ; - le plugin, installé après l'opérateur, s'est enregistré à chaud, sans redémarrage :
status.pluginStatusdu Cluster affiche ensuite la version 0.16.0 ; - avec
cnpgcomme nom de release, le déploiement de l'opérateur s'appellecnpg-cloudnative-pg, pascnpg-controller-managercomme dans la documentation.
Comment configurer le stockage objet et l'archivage WAL ?
Il faut un Secret d'accès, un ObjectStore qui décrit le bucket, puis un Cluster qui référence cet ObjectStore avec isWALArchiver: true. Le bucket S3 est un prérequis : il existe avant le Cluster.
Secret, ObjectStore et Cluster
Créez le namespace, puis le Secret avec les identifiants de votre S3 :
kubectl create namespace donnees
kubectl -n donnees create secret generic stockage --from-literal=ACCESS_KEY_ID=<ACCESS_KEY_ID> --from-literal=ACCESS_SECRET_KEY=<ACCESS_SECRET_KEY>
kubectl -n donnees label secret stockage cnpg.io/reload=true
Le label cnpg.io/reload demande aux instances de recharger le Secret quand il change (documentation du plugin).
Deux règles pour l'ObjectStore :
- la rétention s'y déclare, plus dans le Cluster comme avec le support natif ;
serverNamereste vide.
Remplacez <BUCKET>, endpointURL et le Secret par les valeurs de votre S3. Le chart raw de Bedag déploie la liste resources telle quelle dans le namespace de la release. Les fichiers YAML ci-dessous, passés avec -f, adaptent la configuration validée sous une forme lisible. Fichier commandes.yaml :
resources:
- apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: sauvegardes
spec:
retentionPolicy: 7d
configuration:
destinationPath: s3://<BUCKET>/
endpointURL: https://s3.example.com # exemple à adapter
s3Credentials:
accessKeyId: {name: stockage, key: ACCESS_KEY_ID}
secretAccessKey: {name: stockage, key: ACCESS_SECRET_KEY}
wal: {compression: gzip}
data: {compression: gzip}
- apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: commandes
spec:
instances: 1
imageName: ghcr.io/cloudnative-pg/postgresql:17.6
bootstrap:
initdb: {database: app, owner: app}
storage: {size: 1Gi, storageClass: local-path}
plugins:
- name: barman-cloud.cloudnative-pg.io
isWALArchiver: true
parameters:
barmanObjectName: sauvegardes
helm upgrade --install commandes raw --repo https://bedag.github.io/helm-charts --version 2.0.2 --namespace donnees -f commandes.yaml
kubectl -n donnees wait --for=condition=Ready cluster/commandes --timeout=180s
kubectl -n donnees get cluster commandes -o yaml
Les deux ressources partent dans le même appel. Un seul plugin à la fois peut être WAL archiver. Le Cluster affiche ContinuousArchiving=True. Le pod commandes-1 est en 2/2 : le sidecar du plugin tourne dans le pod PostgreSQL.
Avec un autre fournisseur, destinationPath et l'authentification changent. Selon le cas, il faut aussi :
- annoter le ServiceAccount du Cluster (
serviceAccountTemplate, pour IRSA ou Workload Identity) ; - référencer une CA privée avec
endpointCA; - ajouter des variables d'environnement dans
instanceSidecarConfiguration.envpour certains S3-compatibles.
Détails par fournisseur : documentation du plugin.
Prouver qu'un WAL est archivé
ContinuousArchiving=True ne suffit pas. Écrivez des données identifiables, notez le segment courant, forcez sa fermeture, puis cherchez-le dans le bucket :
kubectl -n donnees exec commandes-1 -c postgres -- psql -U postgres -d app -c 'CREATE TABLE preuve_sauvegarde AS SELECT generate_series(1,1000) AS id, clock_timestamp() AS cree_le'
kubectl -n donnees exec commandes-1 -c postgres -- psql -U postgres -d app -c "SELECT version(), current_setting('archive_mode') AS archive_mode, current_setting('archive_timeout') AS archive_timeout, current_setting('archive_command') AS archive_command"
kubectl -n donnees exec commandes-1 -c postgres -- psql -U postgres -d app -c 'SELECT count(*) AS lignes, pg_walfile_name(pg_current_wal_lsn()) AS segment_a_archiver FROM preuve_sauvegarde'
kubectl -n donnees exec commandes-1 -c postgres -- psql -U postgres -d app -c 'SELECT pg_switch_wal()'
kubectl -n donnees exec commandes-1 -c postgres -- psql -U postgres -d app -c 'SELECT archived_count, last_archived_wal, last_archived_time, failed_count, last_failed_wal, last_failed_time FROM pg_stat_archiver'
kubectl -n donnees logs commandes-1 -c plugin-barman-cloud --tail=25
Ensuite, cherchez l'objet avec votre client S3 :
- la clé est
commandes/wals/<PREFIXE>/<SEGMENT>.gz; commandesest le nom du Cluster ;<SEGMENT>estsegment_a_archiver, renvoyé par la troisième requête ;<PREFIXE>reprend les 16 premiers caractères du segment.
Si l'objet manque juste après pg_switch_wal(), réessayez quelques secondes plus tard. Sans pg_switch_wal(), un segment peu rempli attend la rotation par archive_timeout, soit 5 minutes sous activité, puis son transfert. Au-delà, lisez le log du sidecar plutôt que d'attendre.
Résultats observés :
- 1000 lignes écrites, segment
000000010000000000000002, clécommandes/wals/0000000100000000/000000010000000000000002.gz; archive_mode=on,archive_timeout=5min,archive_commandappelant/controller/manager wal-archive;pg_switch_wal()renvoie0/203CAB8. Ici, il force la fermeture du segment sans attendrearchive_timeout;- l'objet fait 76 642 octets, de type
application/gzip, créé le 12 novembre 2026 à 23:47:45 (UTC). Le log du sidecar afficheArchived WAL filepour ce segment ; pg_stat_archiver:failed_count=0. Sonarchived_countcompte aussi les fichiers.backup, pas seulement des segments.
Comment déclencher et planifier les sauvegardes CNPG ?
Un Backup avec method: plugin lance une sauvegarde immédiate. Un ScheduledBackup avec le même champ la planifie. Sans method: plugin, la méthode par défaut reste le support natif déprécié. La sauvegarde échoue alors avec « cannot proceed with the backup as the cluster has no backup section ».
La sauvegarde manuelle
Fichier sauvegarde-manuelle.yaml :
resources:
- apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
name: commandes-manuelle
spec:
cluster: {name: commandes}
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
helm upgrade --install sauvegarde-manuelle raw --repo https://bedag.github.io/helm-charts --version 2.0.2 --namespace donnees -f sauvegarde-manuelle.yaml
kubectl -n donnees wait --for=jsonpath='{.status.phase}'=completed backup/commandes-manuelle --timeout=180s
kubectl -n donnees get backup commandes-manuelle -o yaml
Le wait est borné à 180 s. S'il expire, lisez status.error et le log du sidecar.
Ensuite, listez commandes/ dans le bucket avec votre client S3. status.backupId, visible dans le get backup -o yaml, est le nom du répertoire sous commandes/base/. Ce répertoire contient backup.info : status doit valoir DONE.
Résultats observés :
phase=completed,method=plugin,online=true;backupId=20261112T234746, de 23:47:46 à 23:47:56 (UTC) ;beginWal=endWal=000000010000000000000004;commandes/base/20261112T234746/contientbackup.info(1432 octets,status=DONE, mêmesystemidque le Cluster) etdata.tar.gz(4 144 353 octets).
Le ScheduledBackup
Le champ schedule est un cron à 6 champs, secondes comprises. 0 0 0 * * * signifie minuit tous les jours. Le crontab Unix n'en a que 5.
Pour prouver qu'une exécution part du calendrier, et pas d'un déclenchement immédiat, on crée d'abord un calendrier à la minute avec immediate: false. Fichier calendrier.yaml :
resources:
- apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
name: commandes-quotidienne
spec:
cluster: {name: commandes}
method: plugin
pluginConfiguration:
name: barman-cloud.cloudnative-pg.io
schedule: "0 * * * * *"
immediate: false
suspend: false
backupOwnerReference: self
helm upgrade --install calendrier raw --repo https://bedag.github.io/helm-charts --version 2.0.2 --namespace donnees -f calendrier.yaml
kubectl -n donnees get scheduledbackup commandes-quotidienne -o yaml
kubectl -n donnees wait --for=jsonpath='{.status.lastScheduleTime}' scheduledbackup/commandes-quotidienne --timeout=120s
kubectl -n donnees get backups -o wide
kubectl -n donnees wait --for=jsonpath='{.status.phase}'=completed backup/<BACKUP_ENFANT> --timeout=180s
kubectl -n donnees get backup <BACKUP_ENFANT> -o yaml
L'échéance tombe à la minute suivante : le wait de 120 s suffit en général. S'il expire, lisez les événements du ScheduledBackup et le log de l'opérateur. Prenez <BACKUP_ENFANT> dans get backups -o wide : préfixe commandes-quotidienne- suivi de l'horodatage UTC de l'échéance.
Créé à 23:48:17, le calendrier devait déclencher à 23:49:00 (UTC). Ce qui prouve le déclenchement par le calendrier :
status.lastScheduleTimevaut 23:49:00 ;- un Backup enfant
commandes-quotidienne-20261112234900est créé à 23:49:00, avec les labelscnpg.io/scheduled-backup=commandes-quotidienneetcnpg.io/immediateBackup=false; - son
ownerReferencespointe vers l'UID du ScheduledBackup ; phase=completedde 23:49:00 à 23:49:06,backupId=20261112T234900,data.tar.gzde 4 145 499 octets.
Un immediate: true créerait un Backup à la création, ce qui ne prouverait rien sur le calendrier. Avec backupOwnerReference: self, supprimer le ScheduledBackup supprime ses objets Backup dans Kubernetes. Les fichiers du bucket restent : ils dépendent de la rétention et du cycle de vie du stockage.
Passer au calendrier quotidien
Dans calendrier.yaml, remplacez schedule par "0 0 0 * * *". Relancez ensuite la commande complète : même objet, même UID.
helm upgrade --install calendrier raw --repo https://bedag.github.io/helm-charts --version 2.0.2 --namespace donnees -f calendrier.yaml
kubectl -n donnees get scheduledbackup commandes-quotidienne -o yaml
kubectl -n cnpg-system logs deployment/cnpg-cloudnative-pg --tail=8
kubectl -n donnees get backups -o wide
Ici, minuit est calculé en UTC. Vérifiez le fuseau de votre cluster avant de placer la sauvegarde hors des pics de charge.
Sur la fréquence :
- la documentation CNPG indique qu'un base backup hebdomadaire suffit souvent ;
- il est rare d'en planifier plus d'un par jour ;
- rapprochez la fréquence du volume de WAL produit entre deux sauvegardes et du temps de restauration visé.
Après le changement de cron :
metadata.generationpasse à 2 : le nouveauspec.scheduleest enregistré ;- le log de l'opérateur indique la prochaine échéance : 13 novembre 2026 à 00:00:00 UTC ;
status.nextScheduleTimereste pourtant à 23:50:00, et unkubectl waitsur la nouvelle valeur a expiré après 90 s.
Recoupez donc spec.schedule, le log de l'opérateur et la liste des Backups. L'échéance de minuit est calculée mais pas encore exécutée. La preuve d'exécution par le calendrier est celle de l'étape à la minute.
Que vérifier avant de compter sur ces sauvegardes en production ?
Quatre signaux disent si la chaîne tourne : le Cluster, l'archiveur PostgreSQL, les Backups et le contenu du bucket.
kubectl -n donnees get cluster commandes -o jsonpath='{.status.conditions}'
kubectl -n donnees exec commandes-1 -c postgres -- psql -U postgres -d app -c 'SELECT archived_count, last_archived_wal, last_archived_time, failed_count FROM pg_stat_archiver'
kubectl -n donnees get backups -o wide
kubectl -n donnees logs commandes-1 -c plugin-barman-cloud --tail=25
À la fin, le Cluster est Ready=True, ContinuousArchiving=True et LastBackupSucceeded=True. Le failed_count vaut 0 et commandes-1 est en 2/2 sans redémarrage. Dans un cluster à plusieurs instances, ciblez le primaire.
| Symptôme | Cause probable | Action |
|---|---|---|
requested plugin is not available: barman-cloud.cloudnative-pg.io |
Nom mal écrit, plugin absent ou non enregistré | Comparer spec.plugins[].name au label cnpg.io/pluginName du service, vérifier le déploiement du plugin et status.pluginStatus |
cannot proceed with the backup as the cluster has no backup section |
method: plugin absent |
Ajouter method: plugin et pluginConfiguration.name |
panic caught: assignment to entry in nil map |
ObjectStore mal configuré : référence de Secret manquante, faute de frappe | Relire s3Credentials et les clés du Secret |
AccessDenied, NoSuchBucket, timeout, SSL certificate problem |
Droits, bucket ou endpoint erroné, réseau, CA | Contrôler Secret, destinationPath, endpointURL, règles réseau, endpointCA |
Lisez les logs dans cet ordre :
- le sidecar (
-c plugin-barman-cloud) ; - le plugin (
deployment/plugin-barman-cloudavec Helm) ; - l'opérateur.
Source : troubleshooting 0.16.0.
Sur les redémarrages :
- ni l'opérateur ni le Cluster n'ont eu besoin d'être redémarrés ;
- la documentation 0.16.0 n'en prescrit pas de façon générale ;
- les modifications de
instanceSidecarConfigurationdans l'ObjectStore(ressources, variables d'environnement, intervalle de rétention) sont prises en compte à la réconciliation suivante du Cluster. Elles peuvent provoquer un rollout : planifiez-les ; - le sidecar partage les ressources du pod PostgreSQL : le redémarrer impose de redémarrer le pod (usage 0.16.0).
Surveiller les WAL et l'espace disque
Si l'archivage échoue, PostgreSQL garde les segments dans pg_wal/ jusqu'à ce qu'ils partent. Un volume plein provoque un arrêt PANIC. Aucune transaction validée n'est perdue, mais la base reste hors ligne tant que de l'espace n'est pas libéré (PostgreSQL 17). Alertez sur :
- un Backup
failed, l'absence de Backupcompletedrécent, une échéance en retard ; ContinuousArchivingdégradé, unfailed_countqui augmente, unlast_archived_timeancien alors que la base reçoit des écritures ;- les métriques
cnpg_collector_pg_wal_archive_status(fichiers.ready) etcnpg_collector_pg_wal(monitoring CNPG), et l'espace libre du volume.
Si un changement d'ObjectStore ou de Cluster casse l'archivage, revenez à la dernière configuration qui archivait :
helm -n donnees history commandes
helm -n donnees rollback commandes <révision>
Avec GitOps, revenez au commit précédent (Helm). Gardez isWALArchiver: true. Ne supprimez aucun WAL, ni dans pg_wal/ ni dans le bucket. Couper l'archivage, par exemple avec un archive_command vide, fait aussi s'accumuler les WAL.
Rétention et coûts
retentionPolicy: 7d est une fenêtre de récupération :
- le point de recouvrabilité est l'heure courante moins 7 jours ;
- le dernier backup valide terminé avant ce point reste, avec les WAL nécessaires : le bucket conserve donc en général plus de 7 jours d'historique ;
- le sidecar applique la politique à intervalle régulier :
retentionPolicyIntervalSeconds, 1800 s par défaut (API 0.16.0, rétention).
Le coût dépend de :
- la taille de la base : chaque base backup est une copie complète, sans incrémental ;
- le volume de WAL et la compression ;
- la fréquence des base backups et la fenêtre de rétention ;
- les versions supplémentaires gardées par le versioning et l'object lock ;
- le trafic sortant et les requêtes facturés par le fournisseur, surtout entre régions, restauration comprise ;
- le CPU et la mémoire du sidecar, pris sur le pod PostgreSQL.
Durcir la configuration
- Stockage indépendant du cluster : un stockage hébergé dans le cluster disparaît avec lui. Autre fournisseur, autre région ou, au minimum, autre compte.
- TLS sur l'
endpointURL, avecendpointCAsi le certificat est interne. - Accès minimaux : une identité dédiée (IRSA, Workload Identity, identité managée) ou une clé limitée à ce bucket.
- Protection contre l'effacement : versioning et object lock.
- Cycle de vie : laissez Barman gérer les objets courants. Ne supprimez ni le backup d'ancrage ni les WAL nécessaires, même plus anciens que 7 jours. Les règles pour les versions non courantes sont distinctes.
- Chiffrement côté serveur, ou SSE-C avec
sseCustomerKey. Gardez cette clé hors du stockage objet : sa perte rend les backups irrécupérables. - Secrets Kubernetes : les backups CNPG ne les contiennent pas (utilisateurs
postgreset applicatif, identifiants du bucket). Couvrez-les avec la sauvegarde de votre cluster.
Planifiez enfin des tests de restauration réguliers, sur un nouveau cluster, et mesurez la durée pour fixer votre RTO. La procédure est détaillée dans notre guide pour restaurer un backup CNPG.
Checklist avant mise en production
| Contrôle | Commande ou point de vérification |
|---|---|
| Versions dans les matrices de support | CNPG, cert-manager, Kubernetes |
| Plugin enregistré, dans le namespace de l'opérateur | kubectl -n cnpg-system get deployments, status.pluginStatus |
| Bucket S3 créé et accessible avant le Cluster | Client S3 |
| Archivage actif | isWALArchiver: true, WAL présent dans le bucket |
Backup completed, method: plugin partout |
kubectl get backup, backup.info à DONE |
| Déclenchement par le calendrier | Backup enfant avec immediateBackup=false |
| Alertes sur Backups, WAL et espace disque | Supervision |
| Restauration testée régulièrement | Test chronométré |