Dépannage des Kustomization Kubernetes : guide pratique de terrain

Introduction

Le dépannage des Kustomization Kubernetes exige une approche structurée et fondée sur des preuves. Lorsqu'une Kustomization ne s'applique pas ou se comporte de manière inattendue, la différence entre une correction rapide et une indisponibilité prolongée dépend souvent de la rigueur avec laquelle vous observez, diagnostiquez et vérifiez. Ce guide fournit un manuel de terrain destiné aux développeurs, aux consultants DevOps et aux équipes techniques de startups qui doivent résoudre les problèmes de Kustomization en toute confiance.

Nous relierons les schémas d'erreurs du monde réel à des commandes kubectl spécifiques, à des techniques d'analyse de journaux et à des procédures de récupération sûres. Chaque recommandation est délimitée par version et réversible lorsque cela est possible. L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier le résultat et documenter les chemins de récupération avant qu'un incident ne vous force la main.

Avant de plonger dans les pannes spécifiques, établissez l'inventaire de votre environnement. Confirmez la version de Kubernetes, le binaire Kustomize ou l'intégration kubectl, et le composant exact inspecté. Par exemple, si vous utilisez kubectl v1.27 avec Kustomize v5.0.1, vérifiez avec :

kubectl version --short
kubectl kustomize --version

Si kubectl kustomize n'est pas disponible, utilisez le binaire autonome kustomize. Des versions incohérentes entre votre outillage local et le cluster peuvent introduire des bogues subtils. Une fois votre base claire, vous pouvez passer de l'observation à l'intervention ciblée.

Inventaire des versions et de l'environnement

Commencez toute session de dépannage de Kustomization en capturant l'état actuel et les horodatages. Ne présumez jamais que vous connaissez la configuration ; inspectez-la directement. La première commande doit toujours être une observation en lecture seule :

kubectl get kustomizations -A

Cela liste toutes les ressources Kustomization dans tous les espaces de noms, en indiquant leur statut, leur âge et leurs conditions éventuelles. Si vous utilisez Flux ou Argo CD, la sortie inclura des colonnes supplémentaires comme READY et STATUS. Par exemple :

NAMESPACE   NAME          READY   STATUS                              AGE
default     my-app        False   Applied revision: main@sha1:abc123   5m

Si la Kustomization n'est pas prête, l'étape suivante consiste à inspecter ses détails :

kubectl describe kustomization my-app -n default

Cela révèle les événements, tels que les échecs de réconciliation, les références manquantes ou les erreurs RBAC. Prêtez attention à la section Events: ; elle contient souvent le message d'erreur exact.

Ensuite, vérifiez que les ressources référencées existent et sont accessibles. Une Kustomization pointe généralement vers une source (par exemple, un dépôt Git ou une ConfigMap). Vérifiez la source associée :

kubectl get gitrepositories -n default
kubectl describe gitrepository my-app-source -n default

Si la source est saine, inspectez les ressources générées. Vous pouvez prévisualiser les manifestes localement sans les appliquer au cluster :

kubectl kustomize ./overlays/production

Cela génère le YAML final. Comparez cette sortie avec vos attentes. Si la sortie est vide ou contient des erreurs, le problème se situe probablement dans la configuration de la Kustomization elle-même (par exemple, des patchs manquants, des chemins de ressources incorrects).

Documentez tout : l'état actuel, les horodatages pertinents et les messages d'erreur exacts. Utilisez un format de note structuré :

Heure d'observation : 2025-04-10T14:30:00Z
Cluster : staging-cluster
Espace de noms : default
Kustomization : my-app
Statut : False
Raison : Applying manifests failed
Message : CustomResourceDefinition apiextensions.k8s.io/v1 is not available

Cet enregistrement devient inestimable pour l'examen post-incident et la reconnaissance de modèles.

Chemin de configuration sûr

Les fichiers de Kustomization mal configurés sont la source d'erreurs la plus courante. Plutôt que de deviner, suivez un chemin de configuration sûr qui minimise les risques. Testez toujours les modifications localement d'abord, puis appliquez-les à un environnement hors production, et enfin promouvez-les en production avec un plan de retour en arrière.

Erreurs de configuration courantes

1. Chemins de ressources incorrects : Dans votre kustomization.yaml, assurez-vous que le champ resources pointe vers des fichiers ou répertoires existants. Par exemple :

# kustomization.yaml
resources:
  - ./deployment.yaml
  - ./service.yaml

Si deployment.yaml est manquant, Kustomize échouera avec :

Error: accumulating resources: accumulating resources from 'deployment.yaml': evalsymlink failure on 'deployment.yaml' : lstat ./deployment.yaml: no such file or directory

1. Non-concordance de la cible du patch : Les patchs doivent correspondre à la ressource qu'ils sont censés modifier. Une erreur courante consiste à utiliser un patch avec un nom ou un espace de noms qui n'existe pas. Par exemple, si vous avez un Deployment nommé webapp mais que le patch cible web, le patch ne fait rien en silence. Vérifiez toujours avec kubectl kustomize et assurez-vous que le patch apparaît dans la sortie.

1. Générateurs de secrets et de ConfigMaps : Lorsque vous utilisez secretGenerator ou configMapGenerator, assurez-vous que le champ behavior est correctement défini (create, replace ou merge). Si vous modifiez le contenu sans spécifier behavior: replace, Kustomize peut créer une nouvelle ressource avec un hachage différent et laisser l'ancienne orpheline.

Procédure de test sûre

1. Rendu local : Exécutez toujours kubectl kustomize localement pour voir la sortie complète. Cela détecte les erreurs de syntaxe et les fichiers manquants sans toucher au cluster.

kubectl kustomize ./overlays/dev > rendered.yaml

1. Apply en simulation (dry-run) : Utilisez kubectl apply --dry-run=client ou --dry-run=server pour voir les modifications qui seraient apportées sans les rendre persistantes.

kubectl apply -k ./overlays/dev --dry-run=client

1. Test dans un espace de noms bac à sable : Créez un espace de noms séparé pour les tests et appliquez-y les manifestes rendus. Cela isole le rayon d'impact.

kubectl create namespace test-kustomize
kubectl apply -k ./overlays/dev -n test-kustomize
kubectl get all -n test-kustomize

1. Vérification avec port-forward : Avant d'exposer via un équilibreur de charge, vérifiez le service localement :

kubectl port-forward svc/my-app 8080:80 -n test-kustomize
curl localhost:8080/healthz

Si le contrôle de santé retourne 200, l'application répond au sein du cluster.

Avancé : Utilisation des overlays et des composants

Pour les déploiements multi-environnements, utilisez des overlays pour éviter de dupliquer les configurations de base. Une structure typique :

base/
  kustomization.yaml
  deployment.yaml
  service.yaml
overlays/
  dev/
    kustomization.yaml
    patch-replicas.yaml
  prod/
    kustomization.yaml
    patch-resources.yaml

Le kustomization.yaml de l'overlay référence la base et applique les patchs :

# overlays/dev/kustomization.yaml
resources:
  - ../../base
patches:
  - target:
      kind: Deployment
      name: my-app
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 2

Cette séparation réduit le risque de contamination entre environnements et facilite le dépannage car les modifications de chaque environnement sont explicites.

Vérification et diagnostics

Une fois qu'une Kustomization est appliquée, la vérification n'est pas facultative ; c'est le cœur du dépannage. Appuyez-vous sur des commandes kubectl qui fournissent des signaux clairs de succès ou d'échec.

Vérifications des pods et des déploiements

Commencez par une vue d'ensemble puis affinez :

kubectl get pods -o wide -n default

Recherchez les pods dans les états CrashLoopBackOff, Pending ou Error. Si un pod n'est pas Running, décrivez-le :

kubectl describe pod <pod-name> -n default

La section Events montrera pourquoi le pod ne peut pas démarrer. Les raisons courantes incluent :

• FailedScheduling : ressources insuffisantes, tolerations ou sélecteurs de nœuds.
• ImagePullBackOff : nom d'image incorrect ou authentification au registre.
• CrashLoopBackOff : l'application se termine immédiatement après le démarrage.

Pour les boucles de crash, récupérez les journaux de l'instance précédente :

kubectl logs <pod-name> --previous -n default

Vérifiez toujours les journaux précédents car le conteneur actuel peut ne pas avoir produit de sortie avant de planter.

Les déploiements gérés par Kustomize doivent atteindre un état stable. Vérifiez avec :

kubectl rollout status deployment/my-app -n default

Sortie réussie :

deployment "my-app" successfully rolled out

Si le déploiement est bloqué, enquêtez avec :

kubectl rollout history deployment/my-app -n default
kubectl rollout undo deployment/my-app -n default

La commande undo revient à la révision précédente, offrant une récupération rapide si la nouvelle version est défectueuse.

Journaux du contrôleur de Kustomization (pour Flux)

Si vous utilisez Flux, les journaux du contrôleur de Kustomization sont inestimables. Accédez-y avec :

kubectl logs -n flux-system deployment/kustomize-controller

Recherchez les erreurs de validation des webhooks, les échecs d'authentification Git ou les conflits d'application des manifestes. Par exemple, un webhook d'admission peut rejeter un manifeste en raison de violations de politique. Le journal affichera :

{
  "level": "error",
  "msg": "Reconciliation failed",
  "kustomization": "default/my-app",
  "error": "failed to apply manifests: admission webhook \"validation.gatekeeper.sh\" denied the request: Container image 'my-app:latest' is not allowed"
}

Cette erreur précise vous indique de modifier l'étiquette de l'image ou de mettre à jour la politique.

Surveillance en temps réel

Pour une vérification continue, utilisez kubectl wait pour bloquer jusqu'à ce qu'une condition soit remplie :

kubectl wait --for=condition=Ready pod -l app=my-app -n default --timeout=60s

Cela est utile dans les scripts et les pipelines CI.

Modes de défaillance et récupération

Les défaillances de Kustomization se répartissent en catégories prévisibles. Comprendre ces modes accélère la résolution.

1. Erreurs de syntaxe de configuration

Comme discuté, un YAML malformé ou des directives Kustomize invalides provoquent des échecs immédiats. La récupération est simple : corrigez la configuration et réappliquez. Effectuez toujours un rendu local avant de pousser vers un dépôt partagé.

Exemple d'erreur :

Error: accumulating resources: accumulating resources from 'deployment.yaml': yaml: line 10: could not find expected ':'

Corrigez l'indentation ou le deux-points manquant et refaites le rendu.

2. Conflits de ressources et propriété

Les ressources générées par Kustomize peuvent entrer en conflit avec des ressources existantes si les noms se chevauchent ou si les ressources sont gérées par un autre contrôleur. L'application côté serveur (Server-Side Apply) ajoute des champs comme kubectl.kubernetes.io/last-applied-configuration ; si vous mélangez les applications côté client et côté serveur, des conflits surviennent.

Pour diagnostiquer, inspectez les métadonnées de la ressource :

kubectl get deployment my-app -n default -o yaml | grep -A5 'last-applied'

Récupération : utilisez kubectl apply -k de manière cohérente, ou définissez force: true dans la spécification de la Kustomization si vous utilisez Flux (mais comprenez les implications).

3. Défaillances de dépendances

Une Kustomization peut référencer une ConfigMap, un Secret ou une CRD qui n'existe pas encore. Par exemple, si vous déployez une ressource personnalisée avant que sa CRD ne soit installée, l'application échoue avec :

Error from server (NotFound): the server could not find the requested resource (post mycrds.example.com)

Vérifiez l'ordre des ressources. Dans le kustomization.yaml, listez la CRD en premier, puis les ressources personnalisées :

resources:
  - crd.yaml
  - my-resource.yaml

Sinon, déployez la CRD dans une Kustomization séparée qui s'exécute en premier.

4. Échecs de patch

Les patchs qui ne s'appliquent pas peuvent ne pas produire d'erreur immédiatement. Utilisez kubectl kustomize et recherchez le changement attendu. Supposons que vous souhaitiez ajouter une variable d'environnement à un Deployment :

patches:
  - target:
      kind: Deployment
      name: my-app
    patch: |-
      - op: add
        path: /spec/template/spec/containers/0/env/-
        value:
          name: DEBUG
          value: "true"

Si le rendu n'affiche pas DEBUG: "true" dans l'environnement du conteneur, la cible du patch peut être erronée. Vérifiez le chemin à l'aide de kubectl explain ou d'une expression de chemin JSON.

5. Échecs de tirage d'image

Si les pods échouent avec ImagePullBackOff, vérifiez le nom et l'étiquette de l'image dans le manifeste rendu. Kustomize permet des transformations d'images :

images:
  - name: my-app
    newName: registry.example.com/my-app
    newTag: v1.2.3

Si l'étiquette est manquante ou incorrecte, le tirage échoue. Confirmez que l'image existe avec docker pull ou crane manifest.

Modèles de récupération

• Retour en arrière : Pour les modifications de Deployment, utilisez kubectl rollout undo.
• Suppression sélective : Si une ressource est orpheline et provoque des conflits, supprimez uniquement cette ressource, puis réappliquez la Kustomization. Mais soyez prudent : la suppression d'une ressource gérée par Kustomize peut déclencher une recréation si le contrôleur est actif. Envisagez de suspendre la réconciliation (par exemple, flux suspend kustomization my-app) avant les interventions manuelles.
• Capture instantanée et restauration : Avant d'apporter des modifications, exportez l'état actuel :

kubectl get kustomization my-app -n default -o yaml > my-app-backup.yaml

Si un changement tourne mal, vous pouvez restaurer la définition d'origine, mais vous devez également résoudre le problème sous-jacent.

Liste de contrôle opérationnelle

Une liste de contrôle disciplinée garantit que rien n'est manqué pendant le dépannage. Voici une liste prête à l'emploi avec des exemples concrets.

Avant de commencer

• [ ] Confirmez l'accès au cluster et le contexte : kubectl config current-context doit retourner staging-cluster. Sinon, basculez avec kubectl config use-context staging-cluster.
• [ ] Enregistrez la version et le statut de la Kustomization : kubectl get kustomization my-app -n default -o yaml > pre-incident-state.yaml.
• [ ] Identifiez l'espace de noms pertinent : kubectl get namespaces | grep my-app pour vous assurer que l'espace de noms existe.

Phase d'observation

• [ ] Exécutez kubectl get kustomization -n default et notez le statut READY. Attendu : True pour une Kustomization saine. Si False, poursuivez.
• [ ] Exécutez kubectl describe kustomization my-app -n default et capturez les messages d'événements. Exemple : Unable to clone repository: authentication required.
• [ ] Exécutez kubectl get pods -n default -l app=my-app -o wide et vérifiez les états des pods. Exemple : trois pods en CrashLoopBackOff.
• [ ] Collectez les journaux : kubectl logs deployment/my-app -n default --tail=50 et kubectl logs <pod-name> --previous -n default.

Diagnostic

• [ ] Corrélez les erreurs observées avec la spécification de la Kustomization. Ouvrez kubectl get kustomization my-app -n default -o yaml et examinez les champs spec (chemin, sourceRef, patchs).
• [ ] Rendu des manifestes : kubectl kustomize ./overlays/production > /tmp/rendered.yaml. Inspectez les changements inattendus ou les ressources manquantes.
• [ ] Comparez avec le dernier état connu bon : faites un diff du YAML rendu par rapport à une sauvegarde d'une application réussie précédente.
• [ ] Si vous utilisez Flux, vérifiez les journaux du contrôleur : kubectl logs -n flux-system deployment/kustomize-controller | grep my-app.

Intervention (minimale et réversible)

• [ ] Choisissez un changement à la fois. Par exemple, si l'étiquette de l'image est incorrecte, ne mettez à jour que cela dans le kustomization.yaml et refaites le rendu.
• [ ] Appliquez avec une simulation d'abord : kubectl apply -k ./overlays/production --dry-run=client.
• [ ] Appliquez réellement : kubectl apply -k ./overlays/production et exécutez immédiatement kubectl rollout status deployment/my-app -n default.
• [ ] Si le déploiement stagne, envisagez un retour en arrière : kubectl rollout undo deployment/my-app -n default.

Vérification et documentation

• [ ] Vérifiez que tous les pods sont sains : kubectl get pods -n default -l app=my-app doit afficher Running et Ready.
• [ ] Testez le point de terminaison du service : kubectl port-forward svc/my-app 8080:80 -n default et curl localhost:8080/health doit retourner 200 OK.
• [ ] Documentez l'incident : cause racine, actions entreprises et étapes de vérification. Stockez dans un emplacement partagé comme un wiki ou un outil de gestion des incidents.
• [ ] Examinez si la prévention peut être automatisée : ajoutez une étape CI pour exécuter kubectl kustomize comme vérification de lint.

En suivant cette liste de contrôle, vous réduisez les conjectures et assurez un dépannage cohérent entre les équipes.

Conclusion

Le dépannage des Kustomization Kubernetes est une compétence qui s'améliore avec la pratique et un état d'esprit systématique. Les techniques de ce guide — inventaire de l'environnement, chemins de configuration sûrs, vérification approfondie, compréhension des modes de défaillance et liste de contrôle opérationnelle disciplinée — fournissent une base pour résoudre efficacement les problèmes.

N'oubliez pas que chaque recommandation doit être délimitée par version, observable et réversible lorsque la technologie le permet. Copier des commandes sans comprendre les prérequis et la sortie attendue n'est pas une procédure opérationnelle ; c'est un pari. Au lieu de cela, traitez chaque session de dépannage comme une occasion d'affiner vos procédures.

Comme prochaine étape, choisissez une vérification à faible risque de ce guide — comme le rendu local d'une Kustomization ou une application en simulation — et pratiquez-la dans un environnement de développement. Enregistrez l'état actuel, exécutez la vérification documentée et comparez le résultat avec le signal attendu. Ensuite, introduisez cette habitude dans le flux de travail de votre équipe, peut-être comme un crochet de pré-commit ou une validation CI.

Un flux de travail technique fiable rend la défaillance visible, protège les valeurs sensibles, limite les modifications à la ressource prévue et définit la vérification de la récupération avant qu'un incident ne force la décision. Avec ces pratiques, vous transformerez les erreurs de Kustomization de blocages en corrections gérables et routinières.