CNPG (CloudNativePG) : c'est quoi, et quand l'utiliser pour PostgreSQL sur Kubernetes

CNPG, ou CloudNativePG, fait tourner PostgreSQL sur Kubernetes : vous décrivez le cluster dans un fichier YAML, l'opérateur crée les pods, gère la réplication et promeut une réplique quand la primaire tombe. Voici quand le choisir, et ce qui reste à votre charge.

CloudNativePG, ou CNPG, fait tourner PostgreSQL sur Kubernetes. Vous décrivez le cluster dans un fichier YAML : l'opérateur crée les pods, les services et les disques, surveille la primaire et promeut une réplique quand elle tombe.

Pour une équipe qui exploite déjà Kubernetes, la base devient un manifeste comme les autres : versionnée dans Git, déployée par le même pipeline, surveillée avec les mêmes outils. Contrairement à un DBaaS (base managée vendue par le cloud), le cluster reste chez vous, sans moteur propriétaire ni licence. Sellsy a migré 50 000 bases sur CNPG, chez Scaleway : le modèle tient à l'échelle.

Quand l'utiliser

La variable de décision est la compétence infra, pas la taille de la base.

CNPG quand :

  • Vous avez déjà Kubernetes en production et une équipe qui sait l'exploiter.
  • Vous voulez plusieurs bases, sortir d'un DBaaS pour le coût, ou garder la main sur la version de PostgreSQL et les extensions.

Pas CNPG quand :

  • Personne ne peut intervenir sur une base en incident : prenez un DBaaS, quelle que soit la taille du parc. Une base reste un élément critique, même petite.
  • Il vous faut un SLA contractuel : CNPG n'en fournit pas, le managé si.
  • La charge est surtout analytique massive : un entrepôt ou un moteur colonne sera plus adapté.
  • L'équipe n'a aucune compétence PostgreSQL : les réglages et les incidents restent à votre charge.

L'unité de décision est le cluster : un Cluster par base. Douze bases font douze clusters.

Ce que CNPG automatise

CNPG est un opérateur : un programme qui tourne dans Kubernetes, lit une ressource Cluster (API postgresql.cnpg.io/v1) et la ramène à l'état décrit.

Une primaire accepte les écritures. Des répliques en hot standby (lecture seule, promouvables) la suivent, par réplication physique des WAL (journaux des transactions). Trois services exposent la primaire, les répliques et l'ensemble.

Chaque pod embarque un instance manager écrit en Go, à la place de Patroni. Pas de StatefulSet : l'opérateur pilote les PVC (PersistentVolumeClaim, la demande de disque de chaque pod).

CNPG gère la bascule (via un Lease Kubernetes), la réplication synchrone (spec.postgresql.synchronous), les sauvegardes et la restauration à un instant donné (PITR) via le plugin Barman Cloud, les mises à jour mineures en rolling update et les comptes applicatifs sans droits superuser.

Ce qui se configure, et ce qui reste à votre charge

La plupart des limites qu'on prête à CNPG sont des réglages.

Ce qui se règle :

  • Le stockage. Un PVC peut être très performant et agrandissable à chaud : il suffit de choisir une StorageClass adaptée (bloc cloud, Ceph, Longhorn) avec allowVolumeExpansion: true.
  • Le multi-AZ. L'anti-affinité est active par défaut, en preferred sur kubernetes.io/hostname : deux instances peuvent se retrouver sur le même nœud. Passez podAntiAffinityType à required, avec la zone comme clé de topologie et un nœud par zone : les instances se répartissent alors d'elles-mêmes, et restent en attente si une zone manque. La vigilance : c'est à vous de durcir ce réglage, et le trafic entre zones a un coût.
  • Les sauvegardes. Le plugin Barman Cloud et un bucket S3 suffisent à les mettre en place. La vigilance : les configurer, vérifier que la base backup et les WAL arrivent tous les deux, et tester une restauration.
  • Les WAL. Rétention, max_slot_wal_keep_size et archivage sont entièrement configurables. La vigilance : le défaut -1 (rétention illimitée) peut remplir le disque, et un slot invalidé force le reclonage de la réplique.

Ce qui reste à votre charge :

  • Le stockage et la supervision. À vous de choisir et dimensionner les volumes, de surveiller leur remplissage et d'alerter quand une réplique décroche.
  • Les Secrets. Les sauvegardes PostgreSQL n'incluent pas les Secrets Kubernetes (mots de passe, certificats) : sauvegardez-les à part.
  • La mise à jour majeure. Elle est hors ligne : arrêt du cluster, pg_upgrade --link (migration par liens durs), reclonage des répliques. Elle est irréversible, il n'y a pas de downgrade : le seul retour arrière est une restauration PITR testée avant.
  • Le failover inter-cluster automatique, le sharding et le SLA contractuel : CNPG ne les fournit pas.

Coût : le calcul, sur des tarifs publics

Périmètre : une base de 2 vCPU et 8 Go de RAM, en haute disponibilité, sur OVHcloud, avec 160 Go de stockage par instance (le minimum inclus dans le managé pour ce gabarit, pour comparer à stockage équivalent). Les deux colonnes sont au même fournisseur, aux tarifs publics HT, hors remises. La base de calcul est de 730 h par mois, celle qu'utilise OVH pour ses mensualités.

CNPG sur nœuds bruts PostgreSQL managé
Ce que vous payez des nœuds, mutualisables entre plusieurs bases un service, une base
Instance 3 × b3-8 : 2 vCPU, 8 Go de RAM, 50 Go de SSD local Advanced B3-8 : 2 vCPU, 8 Go de RAM
Nœuds 3 3
Prix unitaire 0,0512 €/h par instance 0,2404 €/h par nœud
Compute mensuel 0,1536 €/h, soit ≈ 112 € HT 0,7212 €/h, soit ≈ 526 € HT
Stockage 50 Go de stockage local par nœud, facturé à part depuis le 1er octobre 2026 : 0,00729 €/h inclus (de 160 Gio à 800 Gio pour ce gabarit)
Adresse IPv4 publique 3 × 0,0027 €/h, facturée à part : 1,97 € par nœud incluse
Block storage (PVC) 3 volumes de 160 Go, ≈ 42 € HT inclus (160 Go minimum pour ce gabarit)
Total mensuel, une base ≈ 176 € HT (134 € de nœuds + 42 € de volumes) ≈ 526 € HT
Une base de plus ≈ 42 € de volumes si elle cohabite sur les nœuds existants, sinon ≈ 45 € de plus pour un nœud équipé qui en portera plusieurs +526 €
Licence 0 € (PostgreSQL) incluse dans le service
Facturation au nœud au service, par base

Grille tarifaire : OVHcloud Public Cloud.

Sur une base seule, l'écart est de 526 − 176, soit environ 350 €/mois HT. Le total CNPG compte trois nœuds équipés (compute, stockage local et adresse IPv4 publique) et trois volumes de block storage de 160 Go, pour comparer à stockage équivalent. Le managé, lui, inclut le stockage, de 160 Gio à 800 Gio pour ce gabarit. Le chiffre qui compte en pratique est ailleurs. Une base de données standard cohabite très souvent sur les nœuds qui font déjà tourner l'application : vous payez ces nœuds de toute façon, et la base ne coûte alors que ses volumes, environ 42 € par mois. En managé, au contraire, vous payez les ressources de la base en permanence, qu'elle soit chargée ou non. C'est ce qui fait la différence en pratique bien plus que l'écart sur le papier.

Installer CNPG

Prérequis :

  • Un cluster Kubernetes joignable (kubectl get nodes).
  • kubectl et une StorageClass qui honore WaitForFirstConsumer (le volume se crée quand un pod le réclame).
  • Le plugin kubectl cnpg, sur la même mineure que l'opérateur (1.30.1 ici), sinon kubectl cnpg status échoue.

Le plugin kubectl cnpg est l'utilitaire qui interroge l'opérateur depuis votre poste. C'est un point fort de CNPG : sans lui, il faut fouiller les ressources Kubernetes à la main pour retrouver le primaire, le retard des répliques ou l'état de la sauvegarde.

kubectl krew install cnpg

Cette commande prend la dernière version. Pour figer la 1.30.1 et rester aligné sur l'opérateur, installez le paquet de la release :

wget https://github.com/cloudnative-pg/cloudnative-pg/releases/download/v1.30.1/kubectl-cnpg_1.30.1_linux_x86_64.deb --output-document kube-plugin.deb
sudo dpkg -i kube-plugin.deb

Des paquets .rpm et un script d'installation sont dans la doc du plugin. kubectl cnpg version donne la version du plugin : comparez-la à celle de l'opérateur.

L'installation de l'opérateur tient en une commande :

kubectl apply --server-side -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.30/releases/cnpg-1.30.1.yaml
kubectl rollout status deployment/cnpg-controller-manager -n cnpg-system --timeout=180s

L'opérateur est prêt en environ 14 s. Le Cluster se déclare avec ce manifeste, commandes.yaml :

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: commandes
spec:
  instances: 3
  storage:
    size: 1Gi
kubectl apply -f commandes.yaml
kubectl wait --for=condition=Ready cluster/commandes --timeout=300s

Le Cluster est prêt 79,2 s après son application (95 s avec l'opérateur) : trois pods, trois services, trois PVC de 1 Gi, le Lease commandes et quatre Secrets (commandes-app, -ca, -replication, -server).

Sans imageName dans le manifeste, l'opérateur choisit l'image PostgreSQL de sa version : ici ghcr.io/cloudnative-pg/postgresql:18.6-system-trixie. Cette valeur change à chaque release. Pour figer la version, ajoutez imageName sous spec avec une image minimal ou standard de votre version de PostgreSQL : les images system sont dépréciées. La doc CNPG indique la variante recommandée.

Le statut, après installation :

Cluster Summary
Name                     default/commandes
System ID:               7709517033667006488
PostgreSQL Image:        ghcr.io/cloudnative-pg/postgresql:18.6-system-trixie
Primary instance:        commandes-1
Primary promotion time:  2026-11-18 14:23:39 +0000 UTC (1m0s)
Status:                  Cluster in healthy state 
Instances:               3
Ready instances:         3
Size:                    128M
Current Write LSN:       0/6058528 (Timeline: 1 - WAL File: 000000010000000000000006)

Continuous Backup not configured

Streaming Replication status
Replication Slots Enabled
Name         Sent LSN   Write LSN  Flush LSN  Replay LSN  Write Lag  Flush Lag  Replay Lag  State      Sync State  Sync Priority  Replication Slot
----         --------   ---------  ---------  ----------  ---------  ---------  ----------  -----      ----------  -------------  ----------------
commandes-2  0/6058528  0/6058528  0/6058528  0/6058528   00:00:00   00:00:00   00:00:00    streaming  async       0              active
commandes-3  0/6058528  0/6058528  0/6058528  0/6058528   00:00:00   00:00:00   00:00:00    streaming  async       0              active

Instances status
Name         Current LSN  Replication role  Status  QoS         Manager Version  Node
----         -----------  ----------------  ------  ---         ---------------  ----
commandes-1  0/6058528    Primary           OK      BestEffort  1.30.1           même nœud
commandes-2  0/6058528    Standby (async)   OK      BestEffort  1.30.1           même nœud
commandes-3  0/6058528    Standby (async)   OK      BestEffort  1.30.1           même nœud

« Continuous Backup not configured » : CNPG ne sauvegarde rien sans le plugin Barman Cloud.

Lire l'état du cluster

kubectl cnpg status commandes : la commande à connaître. En une seule sortie, elle donne qui est primaire et depuis quand, la timeline WAL, le retard de chaque réplique et l'état de la sauvegarde continue. C'est le « Cluster Summary » ci-dessus.

kubectl get pods -l cnpg.io/cluster=commandes : les trois instances. Le numéro du pod ne dit pas le rôle, commandes-1 peut être une réplique.

kubectl get svc,ep -l cnpg.io/cluster=commandes : les trois services et leurs endpoints. -rw n'a qu'une seule IP, celle du primaire ; -ro pointe sur les répliques ; -r sur les trois. Votre application vise commandes-rw : l'endpoint suit la promotion, elle écrit toujours au bon endroit.

kubectl get pvc : un volume par instance. kubectl get lease : le verrou qui désigne le primaire. kubectl get secrets : dont commandes-app, celui que consomme l'application.

La chaîne de connexion de l'application :

kubectl get secret commandes-app -o jsonpath='{.data.uri}' | base64 -d

Elle porte déjà host=commandes-rw.

Entrer dans la base sans port-forward

kubectl cnpg psql commandes

Ouvre une session psql sur le primaire, comme si vous étiez dans le pod : aucune redirection de port à monter, aucun nom de pod à trouver. enableSuperuserAccess vaut false par défaut : kubectl exec fonctionne aussi, mais il faut d'abord identifier le primaire. Sur le primaire, select(pg_is_in_recovery()) renvoie f ; sur une réplique, t.

Quand ça va mal

kubectl cnpg report cluster commandes

Ramasse tout l'état du cluster : composants, configuration, instances, événements. --logs y ajoute les journaux des pods. C'est ce qu'on joint à un ticket.

Provoquer une bascule

Supprimez le pod primaire :

kubectl delete pod commandes-1

La commande rend la main en 1,98 s. Ensuite, vérifiez le nouveau primaire :

  • kubectl get cluster commandes -o jsonpath='{.status.currentPrimary}' renvoie commandes-2 ;
  • kubectl get lease commandes -o jsonpath='{.spec.holderIdentity}' renvoie commandes-2 ;
  • kubectl cnpg status commandes annonce une promotion : la timeline passe de 1 à 2, et 2 instances sur 3 sont prêtes ;
  • kubectl get endpoints commandes-rw change d'IP et pointe sur le nouveau primaire.

Le pod commandes-1 est recréé. Il revient en Standby (async), et le cluster repasse healthy à 3 instances.

Deux cas se comportent autrement. Un crash du primaire sur un nœud sain attend l'expiration du bail (leaseDurationSeconds, 15 s par défaut). Une panne de nœud ajoute le délai de détection du nœud par Kubernetes (node-monitor-grace-period, 40 s par défaut) avant que le pod soit marqué en échec.

Une bascule propre se fait sans suppression de pod. La commande désigne l'instance à promouvoir, par son nom ou son numéro :

kubectl cnpg promote commandes commandes-3

L'ancien primaire libère le Lease et redevient une réplique : aucune réplique n'attend l'expiration du bail. C'est la façon de changer de primaire pour une maintenance planifiée ou pour tester une bascule. .spec.switchoverDelay règle le délai de fast shutdown lors de cette bascule. Supprimer le pod reste le moyen de vérifier que la bascule automatique se déclenche quand personne n'intervient.

La reconnexion de l'application (pool, DNS, retry) reste à votre charge.

Avant la production

L'installation prend 95 secondes. Ce qui prend du temps, c'est ce qui vient après : brancher les sauvegardes sur un S3 et vérifier qu'elles arrivent, mettre la supervision en place, tester une restauration, migrer les données.

Sauvegardes. Une base backup sans WAL, ou des WAL sans base backup, ne servent à rien : il faut les deux dans le S3, et une restauration testée régulièrement. Vous planifiez les base backups (ScheduledBackup) ; l'archivage WAL est continu.

  • RPO : proche de zéro si l'archivage WAL réussit ; s'il échoue, la perte couvre toute la fenêtre depuis le dernier WAL archivé.
  • RTO : restauration d'une base backup plus le rejeu des WAL ; il augmente avec la taille de la base.

Lire l'article sur les sauvegardes et l'article sur la restauration.

Supervision. Seuils recommandés :

Signal Où le lire Recommandation
Retard des répliques kubectl cnpg status Retard qui grandit, ou réplique hors streaming
WAL en attente d'archivage kubectl cnpg status Compteur qui ne redescend pas
Échec de sauvegarde kubectl get backups Tout backup en échec
Espace disque du PVC Métriques de volume Au-delà de 80 %

Partager ce guide

scale-app.cloud/guides/cnpg-cest-quoi

Pour qui ce n'est pas adapté

  • Une équipe qui n'a personne pour intervenir sur une base en incident : sans compétence PostgreSQL, un DBaaS reste le bon choix, quelle que soit la taille du parc.
  • Un projet qui exige un SLA contractuel ou un primaire réparti automatiquement sur plusieurs clusters : CNPG ne fournit ni l'un ni l'autre, et il ne faut pas le lui demander.
← Voir tous les guides

Commençons par 30 minutes

Nous faisons le point sur votre situation. Si un audit a du sens, nous vous proposons un périmètre et un prix fixe.