Erreurs de configuration Kustomization Kubernetes et comment les éviter

Introduction

Kustomize est un outil de gestion de configuration natif de Kubernetes qui permet de personnaliser des fichiers YAML bruts sans utiliser de modèles. Il fonctionne en superposant des patchs, des ressources et des générateurs sur une configuration de base. Utilisé correctement, Kustomize réduit la duplication et assure la cohérence des environnements. Mal configuré, il peut entraîner des échecs de déploiement, des modifications inattendues des ressources et des problèmes difficiles à déboguer en production.

Cet article passe en revue les erreurs de configuration Kustomization les plus courantes, explique pourquoi elles se produisent et montre comment les éviter ou s'en remettre. Chaque erreur est accompagnée d'un exemple concret, des commandes pour la diagnostiquer et des étapes pour la corriger. L'accent est mis sur la sécurité opérationnelle pratique : observer avant de modifier, limiter le rayon d'impact, vérifier les résultats et documenter les chemins de reprise.

Avant d'aborder les erreurs, établissons un environnement de référence et les commandes clés utilisées tout au long de ce document.

Version et environnement de référence

Avant de déboguer un problème Kustomize, confirmez les versions de vos outils et le contexte du cluster. Kustomize est intégré à kubectl via kubectl kustomize, mais un binaire autonome kustomize est également disponible. Les fonctionnalités et le comportement peuvent varier selon les versions.

Vérifiez la version de kubectl et la version Kustomize intégrée :

kubectl version --client
# Sortie inclut :
# Client Version: v1.28.0
# Kustomize Version: v5.0.3

Si vous utilisez le binaire autonome :

kustomize version
# Sortie :
# v5.0.3

Vérifiez votre contexte Kubernetes actuel et votre espace de noms :

kubectl config current-context
# Exemple : gke_my-project_us-central1-a_cluster-1
kubectl config view --minify | grep namespace

Une erreur courante consiste à appliquer la sortie Kustomize au mauvais cluster ou espace de noms parce que le contexte n'a pas été vérifié. Confirmez toujours le contexte avant toute application.

Pour tous les exemples, nous utiliserons une structure de répertoire de base simple :

base/
  kustomization.yaml
  deployment.yaml
  service.yaml
overlays/
  dev/
    kustomization.yaml
    patch.yaml
  prod/
    kustomization.yaml
    patch.yaml

Note : Le nom de fichier kustomization.yaml est la valeur par défaut, mais kustomization.yml et Kustomization sont également reconnus. Utiliser un nom de fichier non pris en charge est une erreur fréquente.

Chemin de configuration sûr : construction incrémentale

Un flux de travail sûr avec Kustomize consiste à construire et inspecter les manifestes rendus avant de les appliquer au cluster. Cela permet de détecter les erreurs tôt sans affecter les charges de travail en cours d'exécution.

Chemin sûr étape par étape

1. Écrivez vos fichiers de base et d'overlay.
2. Exécutez kubectl kustomize <répertoire> pour générer les manifestes finaux.
3. Examinez la sortie pour vérifier les changements attendus.
4. Optionnellement, redirigez vers kubectl diff pour voir ce qui changerait dans le cluster.
5. Appliquez avec kubectl apply -k <répertoire>.
6. Vérifiez avec kubectl rollout status et d'autres contrôles.

Exemple de rendu d'un overlay :

kubectl kustomize overlays/dev
# Affiche le YAML complet avec tous les patchs appliqués.

Exemple de comparaison avec le cluster en direct :

kubectl diff -k overlays/dev
# Montre les lignes ajoutées/supprimées par rapport à l'état actuel du cluster.

Cette approche évite de nombreuses erreurs car vous voyez exactement ce qui sera appliqué.

Erreurs courantes de Kustomization et comment les éviter

Erreur 1 : Chemins de fichiers incorrects ou ressources manquantes

Kustomize référence des fichiers dans le champ resources, le champ patches et d'autres générateurs. Une faute de frappe dans un chemin de fichier entraîne une erreur de construction ou, pire, l'ignorance silencieuse d'un patch.

Exemple :

Dans overlays/dev/kustomization.yaml :

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
patchesStrategicMerge:
  - deployment-patch.yaml  # Le fichier n'existe pas, le nom réel est patch.yaml

Lorsque vous exécutez kubectl kustomize overlays/dev, vous verrez une erreur comme :

Error: accumulating resources: accumulation err='accumulating resources from 'deployment-patch.yaml': evalsymlink failure on '/path/overlays/dev/deployment-patch.yaml' : lstat /path/overlays/dev/deployment-patch.yaml: no such file or directory'

Comment l'éviter :

• Vérifiez les chemins de fichiers relatifs au fichier kustomization.
• Utilisez kubectl kustomize ou kustomize build après tout renommage de fichier.
• Envisagez une structure de répertoires qui garde les overlays proches de leurs patchs.

Reprise :

Corrigez le chemin et reconstruisez. L'erreur est détectée avant l'application, donc aucun impact sur le cluster.

Erreur 2 : Mauvaise compréhension de la sémantique des patchs (fusion stratégique vs patchs JSON)

Kustomize prend en charge plusieurs types de patchs : patchesStrategicMerge, patchesJson6902 et le champ plus récent patches avec patch et target. Chacun a un comportement différent. Utiliser le mauvais type peut entraîner des mutations inattendues des ressources.

Exemple : Patch de fusion stratégique qui supprime involontairement un champ

Le déploiement de base a :

spec:
  template:
    spec:
      containers:
        - name: app
          image: nginx:1.19
          ports:
            - containerPort: 80

Le patch d'overlay patch.yaml :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
spec:
  template:
    spec:
      containers:
        - name: app
          image: nginx:1.21

Le patch omet ports. Avec la fusion stratégique, la liste ports de la base est conservée car c'est une liste de maps avec une clé de fusion (containerPort). Cependant, si vous utilisiez un patch JSON 6902 avec "op": "replace" sur le conteneur, il pourrait supprimer des champs non spécifiés. Comprendre la sémantique de fusion est crucial.

Comment l'éviter :

• Préférez patches avec target et patch explicites pour plus de clarté.
• Testez les résultats du patch avec kubectl kustomize et examinez la sortie complète.
• Pour des modifications complexes, envisagez d'utiliser patchesJson6902 uniquement lorsque vous avez besoin d'opérations JSON Pointer précises.

Reprise :

Si un patch a supprimé quelque chose involontairement, corrigez le patch et réappliquez. S'il est déjà appliqué, vous devrez peut-être réappliquer la configuration de base ou restaurer manuellement les champs.

Erreur 3 : Utilisation incorrecte des générateurs (ConfigMaps, Secrets)

Les générateurs Kustomize créent des ressources à partir de fichiers ou de littéraux. Une erreur courante consiste à utiliser configMapGenerator sans generatorOptions pour définir un suffixe de hachage, ce qui entraîne des problèmes de ConfigMap immuables lors de la mise à jour des données.

Exemple :

kustomization.yaml :

configMapGenerator:
  - name: app-config
    files:
      - config.properties

Par défaut, Kustomize ajoute un hachage du contenu au nom de la ConfigMap, par exemple app-config-7b58b6d6f5. Lorsque le contenu du fichier change, le nom change, forçant une mise à jour progressive des déploiements qui le référencent. C'est souvent souhaité. Cependant, si vous définissez generatorOptions.disableNameSuffixHash: true, le nom reste constant et les mises à jour de la ConfigMap ne déclencheront pas de redémarrage des pods à moins que vous ne le fassiez manuellement.

Erreur : Désactiver le suffixe de hachage sans comprendre la conséquence. Les pods peuvent continuer à utiliser l'ancienne configuration jusqu'à leur redémarrage.

Comment l'éviter :

• Laissez le suffixe de hachage activé sauf raison délibérée.
• Si vous le désactivez, implémentez une stratégie pour redémarrer les charges de travail (par exemple, kubectl rollout restart deployment/app).
• Utilisez kubectl get configmap pour voir les noms générés.

Reprise :

Si les pods ne prennent pas la nouvelle configuration, redémarrez manuellement le déploiement :

kubectl rollout restart deployment/app

Erreur 4 : Remplacement incorrect des espaces de noms

Kustomize peut définir l'espace de noms pour toutes les ressources à l'aide du champ namespace. Mais une erreur courante est de supposer qu'il s'applique aux ressources de portée cluster ou aux ressources qui ont déjà un espace de noms codé en dur.

Exemple :

namespace: my-namespace
resources:
  - deployment.yaml
  - service.yaml

Cela définit metadata.namespace sur le déploiement et le service, mais pas sur un ClusterRole ou une ressource Namespace incluse. De plus, si une ressource de base a déjà metadata.namespace: default, l'espace de noms de l'overlay ne le remplace pas ; il faut plutôt un patch.

Comment l'éviter :

• Utilisez namespace au niveau de l'overlay de manière cohérente.
• Vérifiez la sortie rendue pour voir les espaces de noms.
• Utilisez kubectl get all -n my-namespace pour vérifier.

Reprise :

Si les ressources se retrouvent dans le mauvais espace de noms, vous pouvez les déplacer en les extrayant et en les réappliquant avec le bon espace de noms, ou les supprimer et les recréer.

Erreur 5 : Mauvaise utilisation des remplacements et de la substitution de variables

Kustomize a replacements et vars (obsolète) pour substituer des valeurs entre les ressources. vars est obsolète et prête souvent à confusion car elle ne fonctionne que dans certains champs. De nombreux utilisateurs utilisent encore vars et rencontrent des erreurs ou des résultats inattendus.

Exemple avec vars obsolète :

vars:
  - name: SERVICE_NAME
    objref:
      kind: Service
      name: my-service
      apiVersion: v1
    fieldref:
      fieldpath: metadata.name

Puis dans une ConfigMap, vous pourriez essayer $(SERVICE_NAME) mais il ne sera pas substitué à moins que le champ ne le prenne en charge. replacements est plus puissant et plus sûr.

Comment l'éviter :

• Utilisez replacements au lieu de vars.
• Comprenez quels champs prennent en charge les remplacements.
• Toujours construire et inspecter la sortie pour les substitutions.

Reprise :

Si la substitution n'a pas eu lieu, vérifiez la configuration replacements. Corrigez et reconstruisez.

Vérification et diagnostics

Après avoir appliqué la sortie Kustomize, vérifiez que l'état du cluster correspond aux attentes. Voici les commandes de diagnostic essentielles.

Vérifier l'état du déploiement

kubectl rollout status deployment/app -n my-namespace
# Sortie :
# Waiting for deployment "app" rollout to finish: 1 old replicas are pending termination...
# deployment "app" successfully rolled out

Examiner les pods

kubectl get pods -n my-namespace -o wide
# Vérifiez READY, STATUS, RESTARTS, AGE, IP, NODE

Pour un pod en échec :

kubectl describe pod <pod-name> -n my-namespace
# Regardez la section Events pour les erreurs d'extraction d'image, les échecs de planification, etc.

Vérifiez les journaux :

kubectl logs <pod-name> -n my-namespace
# Pour le crash précédent :
kubectl logs <pod-name> -n my-namespace --previous

Comparer le rendu et l'appliqué

Si vous soupçonnez une discordance, générez à nouveau la kustomization et comparez avec ce qui est dans le cluster :

kubectl kustomize overlays/dev > /tmp/rendered.yaml
kubectl get deployment app -n my-namespace -o yaml > /tmp/live.yaml
diff /tmp/rendered.yaml /tmp/live.yaml

Cela aide à repérer les changements involontaires.

Modes de défaillance et reprise

Même avec une configuration soignée, des échecs surviennent. Voici les modes de défaillance courants spécifiques à Kustomize et comment s'en remettre.

Échec : L'application échoue en raison d'un manifeste invalide

Symptôme : kubectl apply -k overlays/dev renvoie une erreur comme :

error: error validating "overlays/dev": error validating data: [ValidationError(Deployment.spec): unknown field "replicas" in io.k8s.api.apps.v1.DeploymentSpec, ...]

Cause : Le manifeste rendu contient un champ invalide, peut-être dû à un patch ajoutant un champ non pris en charge par la version de l'API.

Reprise :

• Exécutez kubectl kustomize overlays/dev et inspectez la sortie.
• Recherchez le champ invalide et corrigez le patch ou la base.
• Réappliquez.

Échec : Le déploiement ne se termine pas

Symptôme : Les pods sont créés mais le déploiement n'atteint jamais le nombre de réplicas souhaité. kubectl rollout status se bloque.

Cause : Peut-être la nouvelle image est erronée, les limites de ressources sont trop faibles ou la sonde de rediness échoue.

Reprise :

• Vérifiez les événements du pod : kubectl describe pod <new-pod>.
• Vérifiez les journaux pour les erreurs d'application.
• Si nécessaire, revenez à la version précédente en utilisant kubectl rollout undo deployment/app.
• Ou appliquez un overlay de kustomization précédent.

Échec : ConfigMap ou Secret non mis à jour

Symptôme : Après la mise à jour d'un fichier de générateur de ConfigMap, les pods ont toujours l'ancienne configuration.

Cause : Suffixe de hachage désactivé ou déploiement non redémarré.

Reprise :

• Vérifiez le nom de la ConfigMap : kubectl get configmap -n my-namespace.
• Si le nom est inchangé, redémarrez manuellement : kubectl rollout restart deployment/app.
• Envisagez d'activer le suffixe de hachage pour les futures mises à jour.

Liste de contrôle des opérations pour les déploiements Kustomize

Utilisez cette liste de contrôle avant et après l'application des modifications Kustomize en production. Le responsable de la liste (par exemple, l'ingénieur de publication) doit examiner chaque élément et le valider.

Liste de contrôle avant application

• [ ] Contexte du cluster et espace de noms confirmés (kubectl config current-context).
• [ ] Manifestes rendus examinés (kubectl kustomize overlays/prod).
• [ ] kubectl diff -k overlays/prod ne montre que les changements attendus.
• [ ] Les secrets ne sont pas commités dans Git ; des espaces réservés ou une gestion externe des secrets sont utilisés.
• [ ] Plan de retour documenté (par exemple, hash de commit Git précédent, kubectl rollout undo).
• [ ] Les quotas et limites de ressources sont suffisants.
• [ ] Une sauvegarde des ressources critiques existe.

Liste de contrôle après application

• [ ] kubectl apply -k overlays/prod a réussi sans erreurs.
• [ ] État du déploiement terminé : kubectl rollout status deployment/app -n prod.
• [ ] Pods sains : kubectl get pods -n prod montre tous en état Running.
• [ ] Les journaux ne montrent pas d'erreurs fatales (vérification ponctuelle).
• [ ] Points de terminaison du service répondent : kubectl get endpoints -n prod et test d'une requête.
• [ ] Les métriques et alertes sont nominales.
• [ ] Documenter toute déviation pour la prochaine revue.

Responsable : Priya Sharma, Responsable de l'ingénierie de publication.

Fréquence de revue : À chaque publication en production ; revues post-incident en plus.

Conclusion

Kustomize est un outil puissant, mais sa flexibilité rend les erreurs de configuration faciles à commettre. En comprenant les pièges courants — tels que les chemins de fichiers incorrects, la confusion des types de patchs, les mauvaises configurations des générateurs, les remplacements d'espaces de noms et la substitution de variables obsolète — vous pouvez éviter la plupart des problèmes avant qu'ils n'atteignent la production.

Les pratiques clés sont : inspecter la sortie rendue avec kubectl kustomize, comparer avec le cluster, appliquer de manière incrémentale et vérifier avec l'état du déploiement et les journaux. Ayez toujours un plan de retour et documentez le responsable et la cadence de revue.

Commencez par appliquer ces pratiques dans un environnement de développement. Créez un petit overlay, introduisez une erreur délibérée et observez l'erreur. Puis corrigez-la et gagnez en confiance. Avec le temps, ces habitudes rendront vos déploiements Kustomize plus sûrs et plus prévisibles.

Prochaine étape : Prenez l'un de vos répertoires de kustomization existants et exécutez kubectl kustomize dessus. Examinez attentivement la sortie. Ensuite, exécutez kubectl diff -k pour voir ce qui changerait dans le cluster. Cet exercice simple peut révéler des problèmes cachés dans votre configuration actuelle.