Kubernetes PersistentVolumes, StorageClasses et PVC : guide pratique

Introduction

Démarrer des conteneurs est simple ; les exploiter durablement l'est moins. Le stockage persistant en est un bon exemple. Ce guide pratique explique comment s'articulent Kubernetes PersistentVolume (PV), Kubernetes PVC (PersistentVolumeClaim) et StorageClass, comment prouver que votre configuration fonctionne, et à quoi ressemblent les échecs typiques. L'objectif est opérationnel : comprendre les pièces mobiles, tester localement, puis réutiliser le même schéma en CI/CD et dans un environnement proche de la production.

Nous relierons le sujet principal à des thèmes concrets de K8s storage et de PersistentVolumeClaim troubleshooting. Les décisions de stockage influencent aussi les Kubernetes Deployments, le debugging, la sauvegarde et les rollbacks ; gardez cette interdépendance à l'esprit.

Vue d'ensemble du flux de travail

Approchez le stockage persistant comme un cycle court et vérifiable :

Identifier la ressource cible (PV, PVC, StorageClass, Pod/Deployment).
Décrire la modification de configuration qui l'affecte (par exemple, la StorageClass utilisée par le PVC).
Exécuter une commande qui apporte la preuve de bon fonctionnement.

Bonnes pratiques de vérification :

Démarrer large : kubectl get pods -o wide.
Plonger dans le détail : kubectl describe pod <nom> pour voir le scheduling et les Events.
Examiner les redémarrages : kubectl logs <nom> --previous pour les crash loops.
Valider un déploiement : kubectl rollout status deployment/<nom>.
Garder le test local : appliquez un seul manifest, inspectez ce qu'il génère, puis utilisez kubectl port-forward ou un Service local avant d'impliquer un LoadBalancer/Ingress.

Faites émerger vos hypothèses implicites (chemins locaux, tags d'image, noms réseau, fichiers d'environnement, limites de ressources, permissions). Ce qui marche sur un laptop peut se comporter différemment sur un runner CI ou un nœud de prod.

Concepts clés : PV, PVC, StorageClass

PersistentVolume (PV) : ressource de cluster qui représente un volume déjà provisionné ou provisionnable. Elle annonce des capacités (taille), un accessMode (par ex. ReadWriteOnce, ReadOnlyMany, ReadWriteMany) et un volumeMode (Filesystem ou Block).
PersistentVolumeClaim (PVC) : demande exprimée par un espace de noms pour un volume correspondant (capacité requise, modes d'accès, éventuellement StorageClass). Un PVC lié devient montable par un Pod via un volume et un volumeMount.
StorageClass : décrit « comment » provisionner (paramètres du provisioner, classes de performance, mode de liaison). Avec une StorageClass par défaut, les PVC sans classe explicite déclenchent un provisionnement dynamique.

Relation : un Pod référence un PVC ; le PVC s'appaire à un PV (soit existant, soit créé dynamiquement via la StorageClass). Cet appariement est la liaison (binding). Sans PVC Bound, le Pod reste Pending.

Points d'attention classiques :

Modes d'accès : un PVC demandé en ReadWriteMany ne peut pas se lier à un PV n'offrant que ReadWriteOnce.
volumeMode : FileSystem vs Block doivent correspondre.
Capacité : un PV doit au moins couvrir la demande du PVC.
Espace de noms : les PVC sont namespaced, les PV non.

Liaison et provisionnement

Il existe deux approches :

Provisionnement statique : l'administrateur crée des PV à l'avance. Les PVC se lient à un PV compatible.
Provisionnement dynamique : un provisioner associé à une StorageClass crée un PV à la demande lorsque le PVC est appliqué.

Le mode de liaison (Binding) peut être immédiat ou WaitForFirstConsumer. Avec WaitForFirstConsumer, la création effective du PV attend qu'un Pod réclame ce volume, permettant d'aligner les contraintes (zone, topologie) avec le scheduling réel.

Scénario de test minimal :

Vérifier la StorageClass par défaut : kubectl get storageclass (repérer (default)).
Appliquer un PVC simple qui demande, par exemple, 1 Gi avec cette StorageClass : kubectl apply -f pvc.yaml.
Observer : kubectl get pvc, puis kubectl describe pvc <nom> pour suivre les Events et confirmer l'état Bound.
Monter le PVC dans un Pod ou un Deployment ; vérifier que le Pod atteint Running et que le volume est monté (dans describe pod).

Prouver que ça marche :

Le PVC passe à Bound.
Un PV correspondant est visible avec kubectl get pv (généré si dynamique).
Le Pod montre un Mounted at dans ses volumeMounts et lit/écrit sans erreur.

Politiques de récupération (reclaim)

La politique de récupération détermine ce qu'il advient du PV après suppression du PVC :

Delete : le volume sous-jacent est supprimé avec le PV.
Retain : le PV passe en état Released et les données persistent, nécessitant une action manuelle pour réutilisation ou nettoyage.

Choisir Delete pour des environnements jetables ou de tests. Préférer Retain quand la conservation des données est critique. Vérifiez la politique :

kubectl get pv <nom> -o jsonpath='{.spec.persistentVolumeReclaimPolicy}'

Changer prudemment si nécessaire :

kubectl patch pv <nom> -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'

Assurez-vous de bien comprendre l'impact sur la suppression des données.

Plan pilote local

Gardez le pilote local minime et vérifiable :

Appliquer un seul manifest à la fois (par exemple un PVC et un Pod/Deployment qui le consomme).
Inspection immédiate :

kubectl get pvc pour l'état (Pending/Bound).
kubectl describe pvc <nom> pour les raisons d'échec éventuelles (Events).
kubectl get pv pour voir le volume associé.

Vérifier l'exécution applicative :

kubectl get pods -o wide pour le statut et le nœud.
kubectl describe pod <nom> pour confirmer le montage.
kubectl logs <nom> --previous si le conteneur a redémarré.

Tester le trafic sans sur-ingénierie : kubectl port-forward vers le Pod/Service pour confirmer la lecture/écriture sur le volume.
Documenter : notez la StorageClass, la capacité demandée, le mode d'accès, la politique de reclaim et la commande de preuve.

Ce rituel réduit les surprises lors du passage en CI/CD ou en environnement proche de la production.

Vérifications et dépannage

Quelques symptômes fréquents et pistes de PersistentVolumeClaim troubleshooting :

PVC bloqué en Pending :
kubectl describe pvc <nom> : cherchez des Events sur l'absence de StorageClass, une capacité introuvable ou un accessMode incompatible.
Vérifiez la StorageClass par défaut : kubectl get storageclass. Si elle manque, spécifiez-en une dans le PVC.
Pod Pending avec message « unbound immediate PersistentVolumeClaims » :
Le PVC n'est pas Bound. Résolvez le problème du PVC avant d'investiguer le Pod.
Conflits de modes d'accès (RWO vs RWX) :
Assurez-vous que le PV expose le bon mode. Adaptez la demande dans le PVC ou la classe de stockage utilisée.
Problèmes de permissions dans le conteneur :
Les erreurs EACCES/Eperm peuvent indiquer un décalage d'UID/GID. Ajustez securityContext (runAsUser/runAsGroup/fsGroup) du Pod/Deployment.
Incohérences de volumeMode :
Un PVC en Block ne se lie pas à un PV FileSystem. Alignez les deux.
Topologie et WaitForFirstConsumer :
Avec ce mode, le PV n'apparaît pas tant qu'un Pod consommateur n'est pas programmé. Inspectez describe pod pour voir les contraintes de nœud/zone.
Nettoyage des ressources :
Avec Retain, supprimer le PVC ne supprime pas les données. Planifiez le nettoyage manuel si nécessaire.
Déploiement supposé réussi alors qu'un conteneur boucle :
kubectl rollout status deployment/<nom> pour confirmer, puis kubectl logs <nom> --previous pour les erreurs de montage ou d'E/S.

Commandes utiles de synthèse :

Vue d'ensemble : kubectl get pv, pvc, storageclass, pods -o wide
Détails : kubectl describe pv <nom> et kubectl describe pvc <nom>
Événements récents : kubectl get events --sort-by=.lastTimestamp

Conclusion

La réussite avec Kubernetes PersistentVolumes, StorageClasses et PVC vient d'une approche testable : de petits exemples, des preuves concrètes via kubectl, et une documentation claire de vos hypothèses. Avant d'ajouter d'autres services ou de l'automatisation, confirmez le comportement attendu localement et rapprochez-le de la production.

Prochaine étape : choisissez un service et décrivez précisément les commandes pour le construire, l'exécuter, l'inspecter, l'arrêter et le recréer. Comparez ensuite avec vos Kubernetes Deployments et vos pratiques de Kubernetes debugging pour assurer la cohérence de l'ensemble. Une chaîne fiable rend l'échec visible : logs accessibles, données persistantes après redéploiement, et un K8s storage prévisible qui évite les mauvaises surprises en aval.