Erreurs courantes des ReplicaSets Kubernetes et correctifs avec exemples pratiques

Introduction

Les ReplicaSets Kubernetes garantissent qu'un nombre spécifié de réplicas de pods s'exécute à tout moment. Bien qu'ils fonctionnent souvent silencieusement sous les Deployments, un ReplicaSet mal configuré peut entraîner des interruptions de service, des échecs de mise à l'échelle ou des pods incontrôlés. Le défi est que les messages d'erreur ne sont pas toujours évidents : un pod peut être bloqué en Pending, le ReplicaSet peut signaler 0 désiré sans raison apparente, ou un déploiement peut rester bloqué indéfiniment.

Cet article passe en revue les erreurs de ReplicaSet les plus courantes rencontrées par les opérateurs, avec des exemples concrets, des commandes et des correctifs. Nous couvrirons l'inventaire de version et d'environnement, la configuration sécurisée, la vérification et le diagnostic, les modes de défaillance et la récupération, ainsi qu'une liste de contrôle opérationnelle. Chaque section comprend des exemples concrets et les commandes kubectl exactes pour identifier et résoudre le problème.

Nous supposons que vous avez kubectl installé et accès à un cluster Kubernetes (version 1.19 ou ultérieure). Tous les exemples utilisent un espace de noms appelé default, mais vous pouvez le remplacer par votre propre espace de noms.

Inventaire de version et d'environnement

Avant de résoudre tout problème de ReplicaSet, vous devez avoir une vision claire de votre cluster et de l'état actuel du ReplicaSet. Commencez par des commandes en lecture seule pour éviter de modifier quoi que ce soit pendant le diagnostic.

Vérifier la version de Kubernetes

L'API ReplicaSet est stable dans Kubernetes v1.9 et versions ultérieures, mais les versions plus récentes peuvent avoir un comportement ou des valeurs par défaut différents. Pour vérifier votre version de serveur :

kubectl version --short

Sortie attendue (exemple) :

Client Version: v1.25.3
Server Version: v1.25.3

Si la version du serveur est antérieure à v1.9, le ReplicaSet peut ne pas être disponible ou se comporter différemment. La plupart des clusters modernes sont corrects, mais il est bon de confirmer.

Lister les ReplicaSets et les pods

Utilisez kubectl get pour voir les ReplicaSets actuels et leur nombre de pods :

kubectl get replicasets
kubectl get pods -o wide

Exemple de sortie pour un ReplicaSet nommé nginx-rs :

NAME        DESIRED   CURRENT   READY   AGE
nginx-rs   3         3         0       10m

Dans cet exemple, le ReplicaSet veut 3 pods, en a créé 3, mais 0 sont prêts. Cela indique un problème de préparation des pods, souvent dû à des erreurs d'extraction d'image, une configuration manquante ou des contrôles de santé en échec.

Décrire le ReplicaSet

Pour voir les événements et conditions :

kubectl describe replicaset nginx-rs

Recherchez des messages comme FailedCreate ou SuccessfulCreate dans la section Events. Par exemple :

Events:
  Type     Reason        Age   From                   Message
  ----     ------        ----  ----                   -------
  Warning  FailedCreate  5m    replicaset-controller  Error creating: pods "nginx-rs-xxxxx" is forbidden: unable to validate against any pod security policy

Cela vous indique pourquoi les pods ne sont pas créés.

Inspecter le modèle de pod

Parfois, le problème se situe dans la spécification du pod. Affichez le YAML du ReplicaSet :

kubectl get replicaset nginx-rs -o yaml

Vérifiez spec.template pour des noms d'image valides, des limites de ressources et des montages de volumes. Une faute de frappe courante comme image: nginx:latestt provoquerait ImagePullBackOff sur tous les pods.

Vérifier les ressources des nœuds

Si des pods sont bloqués en Pending, vérifiez la capacité des nœuds et les ressources allouées :

kubectl describe nodes

Sous Allocated resources, assurez-vous qu'il y a suffisamment de CPU et de mémoire. Vérifiez également les taints et tolérances :

kubectl describe node <node-name> | grep Taints

Si un nœud a une taint et que vos pods n'ont pas de tolérances correspondantes, ils ne seront pas planifiés.

Petit test local

Avant de faire des modifications, entraînez-vous dans un espace de noms local ou un cluster de test. Appliquez un manifeste de ReplicaSet simple et observez le comportement. Par exemple, créez test-rs.yaml :

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: test-rs
spec:
  replicas: 2
  selector:
    matchLabels:
      app: test
  template:
    metadata:
      labels:
        app: test
    spec:
      containers:
      - name: busybox
        image: busybox
        command: ["sleep", "3600"]

Appliquez-le et vérifiez l'état :

kubectl apply -f test-rs.yaml
kubectl get rs test-rs

Si tout fonctionne, vous pouvez être sûr que vos modifications sont correctes avant de les appliquer en production.

Chemin de configuration sécurisé

Les erreurs de configuration des ReplicaSets sont courantes, surtout avec les sélecteurs et les modèles. Suivez un chemin sûr : observez, changez une chose, vérifiez et revenez en arrière si nécessaire.

Erreur courante : discordance de sélecteur

L'une des erreurs les plus fréquentes est un sélecteur qui ne correspond pas aux libellés du modèle de pod. Le contrôleur de ReplicaSet utilise le sélecteur pour déterminer quels pods il gère. Si les libellés ne correspondent pas, le contrôleur peut soit créer trop de pods, soit aucun.

Exemple :

Supposons que vous ayez ce ReplicaSet :

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: web-rs
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web-frontend   # Discordance : le sélecteur attend app=web
    spec:
      containers:
      - name: nginx
        image: nginx

Lorsque vous appliquez cela, le ReplicaSet crée des pods, mais il ne peut pas les gérer car les libellés ne correspondent pas au sélecteur. Vous pouvez voir le nombre de pods dépasser les réplicas désirés, et le ReplicaSet signale FailedCreate ou crée continuellement de nouveaux pods.

Pour diagnostiquer :

kubectl describe rs web-rs

Recherchez des événements comme :

Warning  FailedCreate  2m (x15 over 10m)  replicaset-controller  Error creating: Pod "web-rs-xxxxx" is invalid: spec.template.metadata.labels: Invalid value: map[string]string{"app":"web-frontend"}: `selector` does not match template `labels`

Correctif : Alignez le sélecteur et les libellés du modèle. Soit changez le sélecteur en app: web-frontend, soit changez le libellé du modèle en app: web. Ensuite, appliquez le manifeste corrigé.

Pratique de changement sûr : un élément à la fois

Lors de la modification d'un ReplicaSet, ne changez qu'un seul champ à la fois. Par exemple, si vous devez mettre à jour l'image et augmenter les réplicas, faites-le dans des opérations kubectl apply ou kubectl edit séparées. De cette façon, si quelque chose casse, vous savez exactement quel changement l'a causé.

Après chaque changement, vérifiez :

kubectl rollout status deployment/<deployment-name>   # si vous utilisez un Deployment
kubectl get rs <rs-name>
kubectl describe rs <rs-name> | tail -20

Pour les ReplicaSets non gérés par un Deployment, vous pouvez vérifier l'état des pods :

kubectl get pods -l app=web
kubectl describe pod <pod-name>

Gardez les tests locaux petits

Utilisez kubectl port-forward pour tester la connectivité sans exposer un service en externe :

kubectl port-forward rs/web-rs 8080:80

Puis accédez à http://localhost:8080 dans votre navigateur. Pour les services, utilisez kubectl port-forward svc/web-service 8080:80.

Si vous devez tester dans un environnement cloud, envisagez d'utiliser un service NodePort ou une entrée avec un nom d'hôte temporaire avant de passer à un équilibreur de charge de production.

Vérification et diagnostics

Une fois qu'un ReplicaSet est en cours d'exécution, vous devez vérifier qu'il fait réellement son travail : maintenir le bon nombre de pods sains.

Vérifier la préparation des pods

Un pod est considéré comme prêt lorsque ses sondes de préparation (le cas échéant) réussissent et que ses conteneurs sont en cours d'exécution. Si un pod est en cours d'exécution mais pas prêt, le ReplicaSet le compte toujours comme disponible, mais il ne recevra pas de trafic d'un Service.

Utilisez kubectl get pods pour voir la colonne READY :

NAME              READY   STATUS    RESTARTS   AGE
web-rs-abc123     0/1     Running   0          5m
web-rs-def456     1/1     Running   0          5m

Le premier pod n'est pas prêt. Pour savoir pourquoi :

kubectl describe pod web-rs-abc123

Regardez la section Conditions et Events. Par exemple :

Conditions:
  Type              Status
  Ready            False
  ContainersReady  False
Events:
  Type     Reason     Age   From               Message
  ----     ------     ----  ----               -------
  Warning  Unhealthy  3m    kubelet            Readiness probe failed: HTTP probe failed with statuscode: 503

Cela indique que la sonde de préparation échoue. Corrigez la sonde ou l'application sous-jacente.

Vérifier les journaux des conteneurs

Pour les boucles de crash ou les statuts d'erreur, les journaux sont précieux :

kubectl logs web-rs-abc123
# pour l'instance précédente du conteneur
kubectl logs web-rs-abc123 --previous

Si le conteneur plante à cause d'une mauvaise commande, les journaux montreront la sortie d'erreur.

Vérifier l'état du ReplicaSet avec describe

kubectl describe rs fournit un résumé de l'état du ReplicaSet, y compris des événements comme SuccessfulCreate ou FailedCreate. Si des pods sont expulsés ou supprimés, les événements montreront la raison.

Confirmer les réplicas désirés vs actuels

Parfois, spec.replicas d'un ReplicaSet n'est pas ce que vous pensez. Par exemple, si vous avez modifié directement le ReplicaSet et qu'un Deployment l'a redimensionné, le nombre désiré peut changer. Vérifiez :

kubectl get rs web-rs -o jsonpath='{.spec.replicas}{"\n"}'
kubectl get rs web-rs -o jsonpath='{.status.replicas}{"\n"}'

Si le désiré est 0, le ReplicaSet ne créera aucun pod. Cela peut arriver si un Deployment réduit l'échelle ou si vous avez accidentellement défini replicas: 0.

Utiliser kubectl rollout status pour les Deployments

Si votre ReplicaSet est géré par un Deployment, utilisez rollout status pour suivre la progression du déploiement :

kubectl rollout status deployment/web-deployment

Cela affichera un message comme Waiting for deployment "web-deployment" rollout to finish: 1 out of 3 new replicas have been updated... et finalement deployment "web-deployment" successfully rolled out ou une erreur.

Modes de défaillance et récupération

Les ReplicaSets peuvent échouer de diverses manières. Voici les modes de défaillance les plus courants et comment récupérer.

Défaillance 1 : ImagePullBackOff

Symptôme : Les pods sont bloqués en ImagePullBackOff ou ErrImagePull.

Diagnostic :

kubectl get pods
kubectl describe pod <pod-name>

Les événements montreront :

Warning  Failed     2m (x4 over 5m)    kubelet            Failed to pull image "nginx:latestt": rpc error: code = NotFound desc = failed to pull and unpack image "docker.io/library/nginx:latestt": failed to resolve reference "docker.io/library/nginx:latestt": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed

Cause : Le nom ou l'étiquette de l'image est incorrect, ou l'authentification au registre est manquante.

Récupération :

• Corrigez le nom de l'image dans la spécification du ReplicaSet (nginx:latestt -> nginx:latest).
• Si vous utilisez un registre privé, assurez-vous qu'un imagePullSecret est défini dans la spécification du pod et que le secret existe dans l'espace de noms.
• Vérifiez la connectivité réseau vers le registre depuis les nœuds.

Après correction, supprimez les pods en échec pour forcer la recréation, ou mettez à jour le modèle du ReplicaSet pour déclencher un déploiement.

kubectl delete pod <pod-name>
# ou si vous utilisez un Deployment, kubectl rollout restart deployment/<name>

Défaillance 2 : CrashLoopBackOff

Symptôme : Les pods sont en état CrashLoopBackOff, redémarrant continuellement.

Diagnostic :

kubectl get pods
kubectl logs <pod-name> --previous
kubectl describe pod <pod-name>

Regardez le code de sortie et les journaux. Les causes courantes sont une mauvaise configuration de l'application, des variables d'environnement manquantes ou des commandes de démarrage en échec.

Récupération :

• Corrigez l'application ou la configuration.
• Si le pod redémarre rapidement, vous devrez peut-être mettre à jour la spécification du ReplicaSet.
• Pour un arrêt temporaire, réduisez l'échelle du ReplicaSet : kubectl scale rs <name> --replicas=0 (mais cela peut être automatisé par un contrôleur supérieur).

Défaillance 3 : Pods en attente (non planifiables)

Symptôme : Les pods restent en Pending.

Diagnostic :

kubectl describe pod <pod-name>

Les événements montreront :

Warning  FailedScheduling  3m    default-scheduler  0/3 nodes are available: 3 Insufficient cpu.

Cause : Ressources insuffisantes, taints de nœuds, règles d'affinité/anti-affinité, ou revendications de volume persistant impossibles à satisfaire.

Récupération :

• Réduisez les demandes/limites de ressources dans la spécification du pod.
• Augmentez l'échelle des nœuds ou activez l'autoscaling du cluster.
• Supprimez ou ajustez les taints/tolérances.
• Vérifiez les sélecteurs de nœuds et les affinités.

Défaillance 4 : ReplicaSet ne crée pas de pods (désiré 0)

Symptôme : kubectl get rs montre DESIRED=0, mais vous attendez des pods.

Cause : spec.replicas du ReplicaSet a été mis à 0, ou un Deployment l'a réduit.

Diagnostic :

kubectl get rs <name> -o yaml | grep replicas

Récupération :

• Si le ReplicaSet est autonome, augmentez son échelle : kubectl scale rs <name> --replicas=3.
• S'il est géré par un Deployment, augmentez l'échelle du Deployment : kubectl scale deployment <name> --replicas=3. Le Deployment mettra à jour le ReplicaSet.

Défaillance 5 : Pods supprimés de manière inattendue

Symptôme : Les pods sont terminés et recréés fréquemment, ou le ReplicaSet signale moins de pods prêts que désiré.

Diagnostic :

kubectl describe rs <name>
kubectl get events --sort-by=.metadata.creationTimestamp

Recherchez des événements comme Killing ou Evicted. Les pods peuvent être expulsés en raison de la pression sur les ressources du nœud (disque, mémoire) ou supprimés par un contrôleur.

Récupération :

• En cas d'expulsion, résolvez la pression sur les ressources du nœud (nettoyez le disque, ajoutez de la mémoire).
• En cas de suppression par un autre contrôleur, réconciliez la propriété. Assurez-vous que les libellés des pods correspondent uniquement au sélecteur d'un seul ReplicaSet ; sinon, deux contrôleurs peuvent se disputer les pods.

Vérification de la récupération

Après tout correctif, vérifiez que le ReplicaSet converge vers l'état désiré :

kubectl get rs <name> -w

Cela surveille le ReplicaSet et met à jour l'état. Attendez que DESIRED = CURRENT = READY.

Ensuite, testez la fonctionnalité de l'application, en utilisant port-forward ou les points de terminaison du service.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle lors de l'exploitation des ReplicaSets pour éviter les pièges courants et assurer une récupération fluide.

Contrôles de santé quotidiens/hebdomadaires

• Exécutez kubectl get rs -A pour lister tous les ReplicaSets dans tous les espaces de noms. Recherchez ceux avec DESIRED=0 de manière inattendue ou READY inférieur à DESIRED.
• Exécutez kubectl get pods --field-selector=status.phase=Pending pour trouver les pods bloqués.
• Exécutez kubectl get events --sort-by=.metadata.creationTimestamp | tail -50 pour repérer les avertissements récents.

Avant de faire des modifications

1. Enregistrez l'état actuel :

   kubectl get rs <name> -o yaml > rs-backup.yaml
   kubectl get pods -l <selector> -o yaml > pods-backup.yaml

1. Confirmez que vous comprenez la portée de l'impact. Ce ReplicaSet est-il géré par un Deployment ? Si oui, les modifications du ReplicaSet peuvent être écrasées. Modifiez plutôt le Deployment.
2. Faites un changement à la fois et documentez-le.

Après avoir fait des modifications

1. Surveillez le déploiement :

   kubectl rollout status deployment/<name>
   # ou pour un ReplicaSet autonome, utilisez kubectl get rs -w

1. Vérifiez les journaux des pods et la préparation pour les nouveaux pods.
2. Testez la connectivité du service.
3. Si quelque chose échoue, revenez en arrière en utilisant le YAML de sauvegarde ou kubectl rollout undo deployment/<name> si vous utilisez un Deployment.

Pièges courants et comment les éviter

À éviter : Modifiez toujours le Deployment, pas son ReplicaSet. Utilisez kubectl edit deployment <name> ou kubectl apply -f deployment.yaml.

• Piège : Modifier directement un ReplicaSet géré par un Deployment. Le contrôleur de Deployment annulera vos modifications.

À éviter : Vérifiez la propriété : kubectl get rs <name> -o jsonpath='{.metadata.ownerReferences}'. S'il a un propriétaire, il est géré ; ne le supprimez pas directement.

• Piège : Supprimer un ReplicaSet encore nécessaire. Cela peut causer des interruptions si aucun contrôleur supérieur ne le recrée.

À éviter : Si vous devez changer le sélecteur, supprimez d'abord l'ancien ReplicaSet (ce qui ne supprimera pas les pods), créez-en un nouveau avec le nouveau sélecteur, puis supprimez manuellement les pods orphelins au besoin. Ou mieux, utilisez un Deployment pour gérer la transition.

• Piège : Changer le sélecteur d'un ReplicaSet avec des pods en cours d'exécution. Les pods existants seront orphelins et de nouveaux pods peuvent être créés, entraînant des pods en double.

À éviter : Définissez toujours les demandes et limites de ressources dans le modèle de pod.

• Piège : Ne pas définir les demandes/limites de ressources. Cela peut conduire à l'expulsion des pods ou à une surallocation des nœuds.

À éviter : Vérifiez kubectl get pdb et planifiez la maintenance en conséquence.

• Piège : Ignorer les budgets de perturbation des pods. Si vous avez un PDB (Pod Disruption Budget), supprimer manuellement des pods peut le violer.

Propriété responsable

Pour chaque tâche opérationnelle majeure, attribuez un seul propriétaire pour éviter la confusion. Par exemple :

Cela garantit la responsabilité et des révisions en temps opportun.

Conclusion

Les erreurs de ReplicaSet Kubernetes sont généralement simples à corriger une fois que vous savez où chercher. En suivant l'approche structurée de cet article—commencer par l'inventaire de l'environnement, passer par la configuration sécurisée, vérifier avec les diagnostics et récupérer des défaillances courantes—vous pouvez résoudre la plupart des problèmes rapidement.

N'oubliez pas de toujours observer avant de changer, de limiter la portée de l'impact, d'utiliser des espaces réservés et des sauvegardes, de vérifier les résultats et de documenter les étapes de récupération. Un flux de travail fiable rend les défaillances visibles et la récupération prévisible.

Comme prochaine étape, choisissez une vérification à faible risque de cet article, exécutez-la sur votre cluster et enregistrez la sortie. Ensuite, si nécessaire, appliquez l'un des correctifs et confirmez que le ReplicaSet atteint l'état désiré. Avec la pratique, ces procédures deviennent une seconde nature.