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, 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ère | Kustomize | Helm |
|---|---|---|
| Nature | Transformation de YAML existant | Templating + packaging |
| Courbe d'apprentissage | Une heure pour les bases | Une journée pour être à l'aise |
| Débogage | kustomize build affiche le résultat | Rendu des templates à inspecter |
| Distribution tierce | Consommation de dépôts Git distants | Écosystème Artifact Hub |
| Gestion des releases | Aucune (c'est Git qui décide) | helm rollback, historique |
| Idéal pour | Ton propre code, multi-env | Logiciels 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.yamlLa 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.propertiesL'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-apiLe 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é.
| Besoin | Strategic merge | JSON 6902 |
|---|---|---|
Changer replicas | Oui, 2 lignes | Oui, plus verbeux |
| Ajouter une variable d'env | Oui, fusion par name | Oui, path indexé fragile |
| Supprimer une annotation | null explicite | op: remove |
| Retirer un conteneur d'une liste | Délicat | Naturel |
| Lisibilité du diff | Excellente | Moyenne |
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-targetGé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:8f14e45fceea167a5a36dedd4bea2543Tu 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-2ConfigMaps, 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: trueDé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 dansdefaultet tonkubectl apply -kréussit quand même. - Le patch qui ne matche rien. Un
target.namemal orthographié est ignoré silencieusement. Vérifie aveckustomize buildavant d'appliquer. - Le tag
latesten prod.imagePullPolicy: Alwaysne 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
commonLabelshérité. Le champ a été remplacé parlabelsavecincludeSelectors. 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/prodkubectl 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: DeploymentL'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
- Crée
deploy/baseet déplace-y tes manifestes actuels sans les modifier. - Ajoute un
kustomization.yamlavec un seulresources:qui liste tes fichiers. - Lance
kubectl diff -k deploy/base: le diff doit être vide. S'il ne l'est pas, un fichier manque. - Crée l'overlay prod avec le namespace, les réplicas et le tag d'image.
- Extrais les valeurs d'environnement dans un
configMapGeneratoret garde le hash activé. - Ajoute
kubeconformetkubectl diffdans ton pipeline avant toutapply.
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.