Kustomize en 2026 : structurer ses manifestes Kubernetes

Une base, trois overlays et zéro copier-coller : la méthode Kustomize que j'utilise sur tous mes projets Kubernetes en 2026.

Kustomize en 2026 : structurer ses manifestes Kubernetes

Kustomize en 2026, c'est quoi concrètement

Kustomize prend un dossier de manifestes Kubernetes valides et en produit un autre, sans templating. Tu ne touches pas au YAML d'origine : tu déclares des transformations dans un kustomization.yaml, et l'outil les applique.

La version stable au moment où j'écris est kustomize/v5.8.3, sortie le 8 octobre 2026. Elle est aussi embarquée dans kubectl via kubectl kustomize et kubectl apply -k, ce qui veut dire zéro installation sur un poste qui a déjà le client Kubernetes.

Le cas d'usage qui te concerne : trois environnements (dev, staging, prod) qui partagent 95 % des manifestes et divergent sur l'image, le nombre de réplicas et deux variables d'environnement. Avec Kustomize, tu écris ces 95 % une fois.

Kustomize ou Helm : la frontière est nette

Helm excelle quand tu consommes du logiciel écrit par quelqu'un d'autre : ingress-nginx, cert-manager, Prometheus. Les charts ont des values.yaml documentés, des hooks, un cycle de release.

Kustomize gagne quand le YAML est à toi. Pas de couche de templating, pas de {{ .Values.machin }} à déboguer, pas de release à gérer. Le manifeste final reste lisible par kubectl nu.

Mon avis tranché : si tu maintiens tes propres Deployments et que tu as commencé avec Helm « parce que c'est la norme », tu portes une dette. J'ai détaillé ce raisonnement dans les Helm charts sont-ils adaptés aux petits projets, et la réponse reste la même en 2026.

CritèreKustomizeHelm
NatureTransformation de YAML existantTemplating + packaging
Courbe d'apprentissageUne heure pour les basesUne journée pour être à l'aise
Débogagekustomize build affiche le résultatRendu des templates à inspecter
Distribution tierceConsommation de dépôts Git distantsÉcosystème Artifact Hub
Gestion des releasesAucune (c'est Git qui décide)helm rollback, historique
Idéal pourTon propre code, multi-envLogiciels tiers, catalogues

Les quatre primitives qui font 90 % du travail

resources : le point d'entrée

resources liste les fichiers ou dossiers à inclure. Un dossier référencé doit lui-même contenir un kustomization.yaml, c'est ce qui permet la composition en cascade.

patches : la modification ciblée

Tu décris uniquement les champs à changer, pas le manifeste complet. Un patch qui ne dit que replicas: 4 laisse le reste du Deployment intact.

images : le remplacement de tag

Un bloc images réécrit le nom et le tag d'une image dans tous les manifestes d'un coup. C'est ce qui rend une promotion dev → prod vérifiable dans un diff.

configMapGenerator : le hash automatique

Un ConfigMap généré depuis un fichier reçoit un suffixe de hash dans son nom. Quand le contenu change, le nom change, et les pods redémarrent. Tu ne peux pas oublier de redémarrer.

Un dépôt réel : une base et trois overlays

Voici l'arborescence que j'utilise sur tous mes projets. Six fichiers suffisent pour couvrir trois environnements.

deploy/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── config/
│       └── app.properties
└── overlays/
    ├── dev/kustomization.yaml
    ├── staging/kustomization.yaml
    └── prod/kustomization.yaml

La base déclare ce qui ne change jamais d'un environnement à l'autre : le nom du conteneur, le port, la sonde de santé, le montage du ConfigMap.

# deploy/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml

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

L'overlay de prod ajoute son namespace, son préfixe, son tag d'image et son patch de réplicas. Rien d'autre.

# deploy/overlays/prod/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: shop-prod

resources:
  - ../../base

images:
  - name: registry.liink.ovh/shop-api
    newTag: "2026.10.28-1"

replicas:
  - name: shop-api
    count: 4

patches:
  - path: resources.yaml
    target:
      kind: Deployment
      name: shop-api

Le fichier resources.yaml de l'overlay prod ne contient que le delta : les requests CPU montées pour la charge réelle, et une variable de log en JSON.

# deploy/overlays/prod/resources.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: shop-api
spec:
  template:
    spec:
      containers:
        - name: api
          resources:
            requests:
              cpu: "500m"
              memory: "512Mi"
          env:
            - name: LOG_FORMAT
              value: "json"

Strategic merge ou JSON 6902 : lequel choisir

Kustomize accepte deux formats de patch. Le strategic merge est un YAML partiel qui fusionne par clé ; le JSON 6902 est une liste d'opérations indexées.

Règle simple : strategic merge pour 95 % des cas, JSON 6902 quand tu dois modifier un élément précis d'une liste sans toucher aux autres, ou supprimer une clé.

BesoinStrategic mergeJSON 6902
Changer replicasOui, 2 lignesOui, plus verbeux
Ajouter une variable d'envOui, fusion par nameOui, path indexé fragile
Supprimer une annotationnull expliciteop: remove
Retirer un conteneur d'une listeDélicatNaturel
Lisibilité du diffExcellenteMoyenne

Exemple de JSON 6902 pour supprimer l'annotation d'un Ingress sans réécrire l'objet. Note l'échappement du / dans le chemin.

patches:
  - target:
      kind: Ingress
      name: shop-ingress
    patch: |-
      - op: remove
        path: /metadata/annotations/nginx.ingress.kubernetes.io~1rewrite-target

Gérer les images et les tags sans casser la prod

Le champ newTag remplace le tag. Le champ digest remplace par empreinte SHA256, ce qui est la seule façon d'être certain de ce qui tourne.

En prod, je pinne le digest. En dev, je laisse newTag: latest pour que le cluster récupère la dernière build. La différence est dans l'overlay, pas dans le pipeline.

images:
  - name: registry.liink.ovh/shop-api
    newName: registry.liink.ovh/shop-api
    digest: sha256:8f14e45fceea167a5a36dedd4bea2543

Tu peux aussi éditer un overlay en une commande, ce qui évite les erreurs de recopie dans un script CI.

cd deploy/overlays/prod
kustomize edit set image registry.liink.ovh/shop-api:2026.10.28-2

ConfigMaps, Secrets et le piège du suffixe de hash

Un ConfigMap généré s'appelle app-config-6c9k4m2b8f. Le Deployment doit référencer ce nom, mais Kustomize réécrit automatiquement les références qu'il trouve dans les manifestes de la base.

Le problème arrive quand le nom est construit dynamiquement ou référencé dans un script d'init. Là, le hash casse tout. Deux options : sortir la référence du manifeste, ou désactiver le hash.

generatorOptions:
  disableNameSuffixHash: true

Désactive le hash seulement si tu acceptes de redémarrer tes pods à la main après un changement de config. Sinon, garde-le : c'est une sécurité gratuite. Pour les Secrets, préfère un secretGenerator alimenté par un fichier externe scellé par ton gestionnaire de secrets, jamais un stringData en clair dans Git.

Les cinq erreurs qui coûtent une mise en prod

  • Le namespace oublié dans l'overlay. Sans namespace:, les objets atterrissent dans default et ton kubectl apply -k réussit quand même.
  • Le patch qui ne matche rien. Un target.name mal orthographié est ignoré silencieusement. Vérifie avec kustomize build avant d'appliquer.
  • Le tag latest en prod. imagePullPolicy: Always ne te protège pas d'un rollback impossible : tu ne sais pas quelle version tournait hier.
  • Les ressources distantes sans ref. Une URL Git sans référence de commit suit la branche : ton build de demain ne sera pas celui d'aujourd'hui.
  • Le commonLabels hérité. Le champ a été remplacé par labels avec includeSelectors. Sur une base ancienne, il ajoute des labels aux sélecteurs et casse les Deployments existants.

Le troisième point m'a coûté deux heures en 2025 : un rollback kubectl rollout undo qui remet un pod sur une image latest déjà écrasée dans le registry. Depuis, aucun tag mutable ne passe la revue.

Tester un overlay avant de toucher au cluster

Trois commandes, dans cet ordre, et tu attrapes la majorité des erreurs sans risque.

# 1. Le rendu se construit et les noms sont ceux attendus
kustomize build deploy/overlays/prod | grep -E "^(kind|  name):" | head -30

# 2. Le YAML est valide vis-à-vis du schéma Kubernetes
kustomize build deploy/overlays/prod | kubeconform -strict -summary

# 3. Ce que le cluster va réellement changer
kubectl diff -k deploy/overlays/prod

kubectl diff -k est le seul contrôle qui te montre l'impact réel, y compris les champs remplis par les webhooks d'admission. Je le lance systématiquement en préprod, jamais directement contre la prod.

Pour un rendu complet de l'infrastructure, l'inspection du résultat produit reste plus fiable que la lecture des overlays. C'est la même logique que pour la supervision : ce qui compte est l'état observé, pas l'intention déclarée. Voir performance et scalabilité : les secrets de Kubernetes pour la partie ressources et limites.

Les components, la vraie nouveauté à exploiter

Un Component est un bloc de kustomization conditionnel, activable par overlay. C'est la bonne réponse au besoin « ajouter le debug mode en dev, les network policies en prod » sans dupliquer la base.

# components/observability/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1alpha1
kind: Component

patches:
  - path: otel-sidecar.yaml
    target:
      kind: Deployment

L'overlay prod déclare components: [../../components/observability], l'overlay dev ne le déclare pas. Même base, comportements différents, zéro copier-coller.

FAQ

Kustomize est-il toujours maintenu en 2026 ?

Oui. La dernière release est kustomize/v5.8.3 du 8 octobre 2026, et la bibliothèque kyaml est publiée en parallèle. Le projet vit sous l'organisation kubernetes-sigs.

La version embarquée dans kubectl est-elle à jour ?

Pas forcément. Le kubectl que tu télécharges embarque une version compilée au moment de sa sortie, et elle peut avoir plusieurs mois de retard sur la dernière release. Si tu utilises components ou les replacements, installe le binaire kustomize et compare kustomize version avec kubectl version --client.

Peut-on mélanger Helm et Kustomize ?

Oui, et c'est souvent la bonne architecture : un chart tiers rendu par helm template puis passé dans un overlay Kustomize pour les patchs locaux. La base de Helm gère la distribution, Kustomize gère tes exceptions.

Comment gérer plusieurs clusters avec la même base ?

Un overlay par cluster, pas un overlay par environnement. prod-paris et prod-frankfurt partent de la même base et ne diffèrent que par le contexte, les réplicas et les ressources. Un overlay partagé entre deux clusters finit toujours par contenir des conditions.

Faut-il versionner les manifestes générés ?

Non. Le kustomize build est déterministe : mêmes entrées, même sortie. Versionner le rendu crée deux sources de vérité et garantit qu'elles divergent. Versionne la base, les overlays et le hash du commit dans l'annotation de déploiement.

Ta checklist pour passer de kubectl apply -f à Kustomize

  1. Crée deploy/base et déplace-y tes manifestes actuels sans les modifier.
  2. Ajoute un kustomization.yaml avec un seul resources: qui liste tes fichiers.
  3. Lance kubectl diff -k deploy/base : le diff doit être vide. S'il ne l'est pas, un fichier manque.
  4. Crée l'overlay prod avec le namespace, les réplicas et le tag d'image.
  5. Extrais les valeurs d'environnement dans un configMapGenerator et garde le hash activé.
  6. Ajoute kubeconform et kubectl diff dans ton pipeline avant tout apply.

La migration complète m'a pris une demi-journée sur un projet de 14 manifestes. Le gain n'est pas la vitesse du premier jour, c'est la disparition des fichiers deployment-prod-v2-final.yaml. Pour la couche réseau qui vient après, l'approche est la même : implémenter les Ingress dans tes projets Kubernetes se fait proprement une fois la base posée.

Si tu veux creuser la référence complète des champs, la documentation officielle de l'API Kustomization est ici, et le guide des tâches Kubernetes là. Les notes de version sont sur le dépôt kubernetes-sigs/kustomize.