Pour restaurer un backup CloudNativePG, vous créez un nouveau Cluster. Il démarre depuis un base backup physique, puis rejoue les WAL archivés. Le cluster source n'est pas modifié.
Ce guide part d'un principe simple : vous avez déjà un backup CNPG dans un stockage objet et vous voulez en tirer une base utilisable, sans toucher à la source. Il couvre la restauration dans une cible isolée. Il ne traite pas la bascule d'une application après un incident.
Pour mettre en place les sauvegardes, voyez l'article configurer les sauvegardes CNPG.
Ce qu'il faut avoir avant de commencer
- Un opérateur CloudNativePG et le plugin Barman Cloud compatibles entre eux. La restauration physique passe par ce plugin.
- Une image PostgreSQL de la même version majeure que la source : une source en PostgreSQL 17 se restaure avec une image 17.x encore maintenue.
- Un stockage objet accessible qui contient le base backup et les WAL de la source, avec l'identité sous laquelle ils ont été écrits.
- Un StorageClass qui fournit un volume par instance, dimensionné sur la taille de la source.
Les Secrets Kubernetes ne sont pas dans le backup PostgreSQL. Préparez-les dans le namespace cible, qui doit déjà exister : identifiants S3 et mot de passe du rôle applicatif. Vérifiez la compatibilité de votre version Kubernetes avec la release CloudNativePG avant la production.
Le principe : base backup et WAL
- Le base backup est une copie physique du répertoire de données, prise pendant que la base fonctionne. Seule, cette copie n'est pas cohérente.
- Les WAL sont le journal des écritures. Ceux qui couvrent la durée du base backup rendent la copie cohérente. Les suivants permettent de rejouer les écritures jusqu'au dernier état archivé.
Les écritures non archivées ne font pas partie de la restauration.
Barman Cloud est l'outil qui sauvegarde et restaure une base PostgreSQL vers un stockage objet. Il s'est d'abord intégré directement à l'opérateur CloudNativePG, par la configuration native barmanObjectStore du Cluster. Cette intégration historique est aujourd'hui dépréciée ; les sauvegardes déjà écrites restent exploitables. Barman Cloud continue d'être utilisé, sous forme de plugin séparé : installé à côté de l'opérateur, il prend en charge les sauvegardes, l'archivage des WAL et la restauration. C'est ce plugin que ce tutoriel met en œuvre, avec un ObjectStore et un externalClusters en plugin (documentation Recovery).
Les types de restauration
Deux usages à ne pas confondre.
Jusqu'au dernier état archivé. C'est le chemin principal. La cible rejoue tout ce que l'archive contient : le dernier base backup disponible, puis tous les WAL archivés depuis. Vous récupérez l'état le plus récent que l'archive a su conserver, pas forcément les dernières écritures de la production.
Restauration à un instant précis (PITR). Vous visez un instant donné, par exemple juste avant une opération destructrice. La cible rejoue les WAL jusqu'à cet instant, puis s'arrête. Ce qui a été écrit après n'est pas repris.
Dans les deux cas, le point récupéré se détermine par le rejeu des WAL, pas par la date du base backup. Un base backup plus ancien ne limite pas la restauration : tant que les WAL qui le suivent sont continus, le rejeu va jusqu'à l'état voulu. Ne confondez donc pas la date de création d'un base backup avec l'instant récupéré.
Vérifier l'état des sauvegardes avant de restaurer
Avant de restaurer, vérifiez trois points dans le namespace de la source. Si l'un échoue, corrigez la source d'abord : une restauration ne compense pas une archive incomplète.
- Le Backup est en phase
completed. - Les conditions
LastBackupSucceededetContinuousArchivingdu cluster source valentTrue. - L'archive contient le base backup et les WAL qui suivent sa fin.
kubectl get backups.postgresql.cnpg.io -n donnees
NAME AGE CLUSTER METHOD PHASE ERROR
commandes-reference 6m46s commandes plugin completed
kubectl get cluster -n donnees commandes -o jsonpath='{.status.conditions[?(@.type=="ContinuousArchiving")]}'
{"lastTransitionTime":"2026-11-16T16:26:15Z","message":"Continuous archiving is working","reason":"ContinuousArchivingSuccess","status":"True","type":"ContinuousArchiving"}
Pour l'archive, listez le bucket avec votre client S3. Vous devez y trouver le dossier des base backups et celui des WAL, sous l'identité de la source.
Créer le cluster restauré, étape par étape
La restauration tient en deux objets Kubernetes, réunis dans un seul fichier restauration.yaml :
- un ObjectStore, qui donne à la cible un accès en lecture à l'archive ;
- un Cluster, la nouvelle base, dont la section
bootstrap.recoverydésigne la source.
Fixez d'abord les deux valeurs qui servent dans les commandes de ce guide :
# Valeurs de cet exemple, à adapter aux vôtres
NS=restauration # namespace de la nouvelle base
NOUVELLE_BASE=commandes-restauree # nom de la nouvelle base (Cluster)
kubectl ne substitue aucune variable : $NS et $NOUVELLE_BASE doivent aussi être écrits en clair dans le manifeste, metadata.namespace des deux objets et metadata.name du Cluster. Les autres valeurs, endpoint S3, chemin de l'archive, noms des Secrets, image, StorageClass, capacité, base et propriétaire, sont des champs du YAML, à recopier littéralement sans ${VAR}.
Vérifiez que le namespace cible existe, et créez-le seulement s'il manque. Ni kubectl apply -n ni metadata.namespace ne créent un namespace (namespaces Kubernetes) :
kubectl get namespace "$NS"
kubectl create namespace "$NS" # uniquement si la commande précédente ne renvoie rien
Trois noms doivent correspondre :
source, dansbootstrap.recovery, reprend lenamede l'externalCluster;barmanObjectNamereprend le nom de l'ObjectStore de lecture ;serverNameest l'identité de la source dans l'archive, icicommandes. Ce n'est pas forcément le nom du cluster source, et ce n'est jamais le nom de la nouvelle base.
Si serverName ne correspond pas au dossier de l'archive, le bootstrap ne trouve pas de base backup.
Préparez les Secrets dans le namespace cible avec votre gestionnaire de secrets habituel :
archives-s3(typeOpaque), avec les clésACCESS_KEY_IDetACCESS_SECRET_KEY;commandes-restauree-app(typekubernetes.io/basic-auth), pour le rôle applicatif existantapp, avecusernameetpassword.
Le fichier restauration.yaml réunit les deux objets, séparés par --- :
apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
name: archives-lecture
namespace: restauration
spec:
configuration:
destinationPath: s3://archives/
endpointURL: <endpoint-S3>
s3Credentials:
accessKeyId:
name: archives-s3
key: ACCESS_KEY_ID
secretAccessKey:
name: archives-s3
key: ACCESS_SECRET_KEY
wal:
compression: gzip
---
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
name: commandes-restauree
namespace: restauration
spec:
instances: 1
imageName: ghcr.io/cloudnative-pg/postgresql:17.6
storage:
size: 1Gi
storageClass: local-path
bootstrap:
recovery:
source: source-archive
database: app
owner: app
secret:
name: commandes-restauree-app
externalClusters:
- name: source-archive
plugin:
name: barman-cloud.cloudnative-pg.io
parameters:
barmanObjectName: archives-lecture
serverName: commandes
Quelques champs sont à adapter à votre environnement : endpointURL, l'endpoint de votre stockage S3 ; imageName, une version de la même majeure que la source, encore maintenue ; storageClass et size ; et, dans bootstrap.recovery, database et owner. La cible ne déclare aucun spec.plugins d'archivage : elle ne fait que lire l'archive source.
Appliquez le fichier, puis attendez le statut Ready :
kubectl apply -n "$NS" -f restauration.yaml
kubectl wait -n "$NS" --for=condition=Ready "cluster/$NOUVELLE_BASE" --timeout=240s
Quand la condition est remplie, wait rend la main (résultat attendu) :
cluster.postgresql.cnpg.io/commandes-restauree condition met
Si le bootstrap échoue, lisez les événements du Cluster. La récupération tourne dans un pod temporaire dont le nom porte le suffixe full-recovery : repérez-le et lisez son conteneur full-recovery. Le pod principal commandes-restauree-1, conteneur postgres, n'existe qu'une fois la récupération terminée.
Vérifier la restauration
Un cluster Ready ne prouve pas que les données sont bonnes. La vérification se fait en trois temps, du plus technique au plus métier.
1. L'état technique et la connexion. Le Cluster est Ready, le pod principal tourne, et vous arrivez à vous connecter en TCP avec le rôle applicatif app et son Secret. Une connexion qui aboutit écarte déjà les problèmes de bootstrap, de réseau et d'authentification.
2. Les structures. La base app est là, les tables attendues aussi, et les migrations sont appliquées. Comparez la liste des bases et des tables à ce que vous attendez.
3. Le contenu métier au point visé. Vérifiez quelques enregistrements connus et leur contenu, ainsi que les volumes de lignes par table. Comparez la cible à la source au point de référence visé, pas à la source actuelle qui a continué d'écrire depuis : une différence sur les écritures postérieures à la cible est normale.
Variante PITR : restaurer à un instant précis
Pour viser un instant précis, copiez restauration.yaml en restauration-pitr.yaml. Le PITR ne change que le nom de la cible et ajoute un bloc recoveryTarget ; tout le reste est identique.
Trois conditions doivent être vraies (recovery CloudNativePG) :
- le base backup est terminé avant la cible ;
- les WAL sont continus et contiennent une transaction postérieure à la cible : le rejeu doit pouvoir la dépasser, pas seulement l'atteindre ;
- la valeur de
targetTimeporte un fuseau explicite.
Fusionnez ce fragment dans l'objet Cluster du fichier copié :
metadata:
name: commandes-pitr
spec:
bootstrap:
recovery:
recoveryTarget:
targetTime: '2026-06-01T10:00:00+02:00'
Remplacez targetTime par l'instant visé, avec son fuseau. Appliquez ce fichier distinct et attendez la cible sous son nom PITR, sans réutiliser $NOUVELLE_BASE, qui désigne encore la restauration complète :
kubectl apply -n "$NS" -f restauration-pitr.yaml
kubectl wait -n "$NS" --for=condition=Ready "cluster/commandes-pitr" --timeout=240s
Points d'attention
- Ne réécrivez jamais dans l'archive source. La cible ne fait que la lire. Une cible devenue production doit recevoir sa propre destination d'archivage, distincte de celle de la source.
- Le contrôle d'une destination non vide ne concerne que l'archivage en écriture. L'archive source est non vide par nature : c'est normal. Si vous activez un archivage pour la cible et que sa destination est déjà utilisée, ne la vidangez pas pour continuer.
- Le
serverNamen'est pas le nom de la nouvelle base. C'est la première erreur à écarter. - Donnez à la cible des identifiants S3 en lecture seule si votre stockage le permet : elle n'a rien à écrire dans l'archive.
Diagnostic rapide
| Symptôme | Ce qu'il faut vérifier |
|---|---|
| Le bootstrap ne trouve pas d'archive | serverName et chemin S3 de l'ObjectStore |
| Erreur d'accès à l'archive | Secrets S3 dans le namespace cible |
| WAL manquants après le base backup | Archivage WAL de la source, présence des fichiers dans le bucket |
| Archive de destination non vide | Destination d'écriture de la cible, distincte de celle de la source |
| Table ou données absentes | Droits du rôle et point temporel visé |
Tester la restauration régulièrement
Une sauvegarde jamais restaurée ne prouve pas qu'elle servira. Automatisez le parcours de ce guide dans un CronJob ou un job CI, sans intervention humaine. Chaque exécution contrôle trois critères, et l'échec de l'un déclenche une alerte :
- Durée : le statut
Readyarrive avant un timeout fixé au-dessus de votre durée habituelle. C'est un repère distinct de la vérification du contenu :Readyne veut pas dire copie contrôlée. - Fraîcheur : pour une restauration jusqu'au dernier état, comparez l'ancienneté du dernier état récupéré à l'ancienneté maximale que vous acceptez, votre objectif de reprise ; pour un PITR, comparez au point de référence visé, pas à l'heure courante. Ne vous fiez pas à la date d'un segment WAL : une source inactive n'écrit pas de nouveau WAL, ce qui ne prouve pas que l'archive est en retard.
- Contenu : les structures et les enregistrements connus correspondent, comme dans la section précédente.
Conservez pour chaque exécution le nom du base backup, le point restauré, les résultats et les logs du bootstrap. Le rythme dépend de votre objectif de reprise. Relancez aussi le test après chaque changement de version de PostgreSQL, de CloudNativePG ou du plugin.
Un précédent montre le risque. Le 31 janvier 2017, GitLab a perdu des données après un incident de base de données. La restauration a reposé sur un instantané LVM pris à la main environ six heures plus tôt, plus récent que l'instantané quotidien disponible. pg_dump échouait pour une incompatibilité de version, les alertes étaient rejetées et la réplication était cassée (postmortem GitLab).
Récapitulatif
- Restaurez dans un nouveau Cluster, avec
bootstrap.recovery, jamais dans la source. - Avant de restaurer, vérifiez le Backup
completed,ContinuousArchivinget les WAL qui suivent la fin du base backup. serverNamedésigne la source dans l'archive, pas la nouvelle base.- Créez explicitement les Secrets ; les droits du rôle applicatif sont restaurés tels quels, vérifiez ceux que vous attendez au lieu de les recréer.
- Contrôlez l'état technique, les structures et le contenu au point visé, pas seulement
Ready. - Automatisez la restauration régulièrement.