Déployer PostgreSQL sur Kubernetes : guide pas à pas

PostgreSQL est un SGBDR (RDBMS) populaire offrant des fonctionnalités de haute disponibilité comme la réplication en flux (streaming replication), la réplication logique et des solutions de bascule (failover). Le déploiement de PostgreSQL sur Kubernetes permet de construire des systèmes résilients garantissant une disponibilité des données et un temps d’arrêt minimal.

Avec les StatefulSets Kubernetes, vous pouvez faire évoluer votre déploiement PostgreSQL selon la demande.

Préparation de l’environnement Kubernetes

Copier le lien

Assurez-vous de disposer des éléments suivants :

• Cluster Kubernetes (cloud ou local) : vous pouvez créer un cluster Kubernetes sur Hostman en quelques minutes. Pour un cluster local, utilisez k3s, minikube, microk8s ou kind.

• kubectl : l’outil pour interagir avec le cluster. Il a besoin d’un fichier de configuration YAML contenant les détails du cluster (fourni par votre fournisseur cloud).

Depuis le tableau de bord Hostman, téléchargez ce fichier en un clic, puis exportez la variable d’environnement :

Pour vous connecter, vous devez définir la variable d’environnement KUBECONFIG en conséquence.

export KUBECONFIG=/absolute/path/to/file/k8s-cluster-config.yaml

• Helm : la CLI Helm est nécessaire pour installer des charts. Helm v3 est requis.

Déployer PostgreSQL avec un chart Helm

Copier le lien

Helm est un gestionnaire de paquets pour Kubernetes (à la manière de apt pour Ubuntu/Debian). Plutôt que de créer manuellement plusieurs YAML (Pods, Services, PV, Secrets, etc.), un chart Helm permet un déploiement en une commande.

Étape 1 : Ajouter le dépôt Helm

Copier le lien

helm repo add bitnami https://charts.bitnami.com/bitnami

Pour synchroniser votre référentiel Helm local avec celui distant :

helm repo update

Étape 2 : Gérer la persistance des données

Copier le lien

PostgreSQL nécessite un stockage persistant pour préserver les données lors d’un crash de pod ou d’un rescheduling.

Créez un PersistentVolume local (démo/lab) — fichier postgres-local-pv.yaml :

apiVersion: v1
kind: PersistentVolume
metadata:
  name: postgresql-local-pv
spec:
  capacity:
      storage: 5Gi
  accessModes:
      - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: manual
  hostPath:
      path: /mnt/data/postgresql

⚠️ Attention : hostPath pointe vers un dossier local du nœud. Si le nœud devient indisponible, les données le deviennent aussi. En production, privilégiez un stockage cloud-native (Ceph, Portworx, OpenEBS, Gluster, etc.) pour la fiabilité et l’évolutivité.

Créez la PVC — fichier postgres-local-pvc.yaml :

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgresql-local-pvc
spec:
  accessModes:
      - ReadWriteOnce
  resources:
      requests:
          storage: 5Gi
  storageClassName: manual

ReadWriteOnce signifie qu’un seul nœud peut monter le volume en lecture/écriture à la fois. Passer en ReadWriteMany n’apporte pas de HA automatique pour PostgreSQL et peut engendrer des corruptions/concurrences d’accès.

Appliquez :

kubectl apply -f postgres-local-pv.yaml
kubectl apply -f postgres-local-pvc.yaml

Étape 3 : Installer le chart PostgreSQL

Copier le lien

helm install tutorial-db bitnami/postgresql --set auth.username=bhuwan \
  --set auth.password=”AeSeigh2gieshe” \
  --set auth.database=k8s-tutorial \
  --set auth.postgresPassword=”Ze4hahshez6dop9vaing” \
  --set primary.persistence.existingClaim=postgresql-local-pvc \
  --set volumePermissions.enabled=true 

Vérifiez après quelques minutes :

kubectl get all

Étape 4 : Tester et se connecter

Copier le lien

Récupérez le mot de passe depuis le Secret et lancez un pod client temporaire :

export POSTGRES_PASSWORD=$(kubectl get secret --namespace default tutorial-db-postgresql -o jsonpath="{.data.password}" | base64 -d)

kubectl run tutorial-db-postgresql-client --rm --tty -i --restart='Never' \
 --image docker.io/bitnami/postgresql:17.2.0-debian-12-r6 \
 --env="PGPASSWORD=$POSTGRES_PASSWORD" \
 --command -- psql --host tutorial-db-postgresql \
 -U bhuwan -d k8s-tutorial -p 5432

Le pod sera supprimé automatiquement grâce à --rm.

👉 Si vous avez modifié le Release name, l’utilisateur ou le nom de DB, adaptez les commandes.

Déployer PostgreSQL sur Kubernetes « from scratch »

Copier le lien

Un StatefulSet est la ressource adaptée aux applications avec état comme PostgreSQL: noms réseau stables et volumes persistants par pod.

Commencez par nettoyer et recréer le PV et la PVC :

helm delete tutorial-db
kubectl delete pvc postgresql-local-pvc
kubectl delete pv postgresql-local-pv

kubectl apply -f postgres-local-pv.yaml -f postgres-local-pvc.yaml

Créez postgres-statefulset.yaml :

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres-statefulset
  labels:
    app: postgres
spec:
  serviceName: "postgresql-headless-svc"
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:17.2
          envFrom:
            - secretRef:
                name: postgresql-secret
          ports:
            - containerPort: 5432
              name: postgresdb
          volumeMounts:
            - name: pv-data
              mountPath: /var/lib/postgresql/db
      volumes:
        - name: pv-data
          persistentVolumeClaim:
            claimName: postgresql-local-pvc

Créez le Secret des informations sensibles (mot de passe) :

kubectl create secret generic postgresql-secret --from-literal=POSTGRES_PASSWORD=Ze4hahshez6dop9vaing

kubectl apply -f postgres-statefulset.yaml

Si le pod reste Pending, créez une StorageClass manuelle :

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: manual
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer

Diagnostiquer un problème :

kubectl describe pod postgres-statefulset-0

Exposez PostgreSQL via un Headless Service (accès interne) — postgres-service.yaml :

apiVersion: v1
kind: Service
metadata:
  name: postgresql-headless-svc
spec:
  type: ClusterIP
  selector:
	app: postgres
  ports:
  	- port: 5432
    	targetPort: 5432
  clusterIP: None

Test de connexion :

kubectl run tutorial-db-postgresql-client --rm --tty -i --restart='Never'  \
--image docker.io/bitnami/postgresql:17.2.0-debian-12-r6 \
--env="PGPASSWORD=Ze4hahshez6dop9vaing"  \
--command -- psql --host postgres-statefulset-0.postgresql-headless-svc  \
-U postgres  -p 5432

Mise à l’échelle, réplication et sauvegardes

Copier le lien

Scaler un StatefulSet :

kubectl scale statefulset postgres-statefulset --replicas=3 

•  Grâce au Headless Service, vous pouvez joindre un pod en particulier, par ex. postgres-statefulset-1.postgresql-headless-svc.

• Sauvegardes : créez un CronJob utilisant pg_dump. Vous pouvez aussi envisager les VolumeSnapshots si votre stockage le supporte.

Bonnes pratiques

Copier le lien

• Requests/Limits : définissez des demandes et des limites CPU/Mémoire appropriées pour éviter la sous/sur-allocation.

• Backups réguliers : CronJobs + snapshots si possible.

• Supervision & logs : Prometheus + Grafana pour les métriques PostgreSQL (perf des requêtes, espace disque, statut de la réplication).

• Pod Disruption Budgets (PDB) : évitent trop d’indisponibilités simultanées (rolling updates, etc.).

Conclusion

Copier le lien

Le chart Helm est la méthode recommandée pour les déploiements complexes et production-ready. Il automatise la gestion de versions et masque la complexité de la configuration des composants Kubernetes. Avec helm template, vous pouvez rendre les manifests en local et les adapter.

Kubernetes offre scalabilité, flexibilité et automatisation pour PostgreSQL. En utilisant StatefulSets, PVCs, PDBs et la gestion des Secrets, vous adaptez PostgreSQL aux exigences d’un environnement de production.