Kustomize : Factorisez vos manifests Kubernetes

Ce guide vous permet de gérer plusieurs environnements Kubernetes (dev, staging, prod) sans dupliquer vos fichiers YAML. Vous apprendrez à créer une base commune, appliquer des overlays par environnement, et déployer avec kubectl apply -k. Prérequis : connaître les manifests Kubernetes de base (Deployment, Service).

Ce que vous allez apprendre

Structurer vos manifests avec une base et des overlays
Personnaliser les déploiements sans modifier les fichiers d'origine
Utiliser kubectl apply -k et kubectl diff -k au quotidien
Éviter les pièges courants (secrets, patches, versions)

Qu'est-ce que Kustomize ?

Kustomize est un outil natif intégré à Kubectl qui permet de personnaliser des fichiers YAML sans utiliser de templates. Contrairement à Helm, qui repose sur un système de charts avec des valeurs dynamiques, Kustomize utilise des patches et des overlays pour modifier des configurations existantes.

L'idée principale est simple : au lieu de dupliquer des fichiers YAML, on applique des modifications ciblées à une base commune. Cela permet de gérer plusieurs environnements sans complexifier la maintenance des manifests.

Pourquoi utiliser Kustomize ?

La question se pose au moment où la même application doit vivre sur plusieurs environnements. La réponse spontanée consiste à copier le dossier de manifests, et le résultat est toujours le même : au bout de quelques mois, une correction appliquée à la production manque à la recette, et personne ne sait dire ce qui diffère volontairement de ce qui diffère par oubli. Kustomize répond par la composition, ce qui rend l'écart entre deux environnements lisible d'un coup d'œil.

Avec Kustomize, vous pouvez :

Éviter la duplication (DRY) des fichiers YAML en réutilisant une base commune.
Personnaliser les déploiements en appliquant des overlays spécifiques à chaque environnement.
Gérer les secrets et les ConfigMaps sans les inclure directement dans mes manifests.
Modifier facilement les images et les labels d’un déploiement Kubernetes.

Différences entre Kustomize et Helm

Voici un tableau comparatif des différences entre Kustomize et Helm :

Critère	Kustomize	Helm
Approche	Patch des fichiers YAML	Templates avec valeurs dynamiques
Complexité	Simple et natif	Plus puissant mais plus complexe
Gestion des dépendances	Pas de gestion intégrée	Support des chart dependencies
Utilisation avec `kubectl`	Oui (intégré depuis v1.14)	Non, nécessite `helm`
Apprentissage	Facile pour débutants	Peut être complexe

Si je veux juste modifier mes manifests existants sans apprendre un nouvel outil, Kustomize est la solution idéale. Pour des déploiements plus avancés avec gestion des dépendances, Helm reste plus adapté.

Installation de Kustomize

Kustomize est intégré à kubectl depuis la version 1.14. Vous n'avez donc pas besoin de l'installer séparément.

La version de Kustomize embarquée dans kubectl peut être en décalage avec le binaire kustomize standalone. Si vous rencontrez des comportements différents entre kubectl kustomize et kustomize build, vérifiez les versions :

kubectl version --client  # Version kubectl
kustomize version         # Version standalone (si installée)

Pour les fonctionnalités récentes, préférez installer le binaire standalone.

Concepts de Kustomize

Pour gérer efficacement les configurations Kubernetes, il est essentiel de comprendre les concepts fondamentaux de Kustomize. Cet outil offre une approche structurée pour personnaliser et déployer des ressources Kubernetes sans dupliquer les fichiers YAML.

Le fichier `kustomization.yaml`

Au cœur de Kustomize se trouve le fichier kustomization.yaml. Ce fichier définit comment assembler et personnaliser les ressources Kubernetes. Voici les principaux champs que l'on peut y trouver :

resources : liste des fichiers ou répertoires contenant les manifests à inclure.
patches : modifications à appliquer aux ressources existantes.
configMapGenerator et secretGenerator : pour générer des ConfigMaps et Secrets à partir de fichiers ou de littéraux.
labels et annotations : labels et annotations à ajouter à toutes les ressources.

Le bloc labels mérite une précision, parce qu'elle décide du sort du Service. Par défaut il étiquette les objets sans toucher aux selectors ; l'option includeSelectors: true les y pousse aussi. Les deux comportements sont utiles et le mauvais choix est silencieux : un label d'environnement posé sur les Pods mais absent du selector du Service donne un Service qui ne route plus vers rien, sans le moindre événement pour le signaler.

labels:
  - pairs:
      env: prod
    includeSelectors: true

C'est aussi pour cette raison que l'ancien champ commonLabels est déprécié : il modifiait toujours les selectors, y compris ceux d'un Deployment déjà déployé, alors que spec.selector est immuable.

Bases et Overlays

Kustomize utilise une hiérarchie de configurations :

Base : ensemble de ressources communes à plusieurs environnements.
Overlay : personnalisation spécifique à un environnement (développement, staging, production) qui s'appuie sur une base.

Cette structure permet de réutiliser les configurations et de les adapter selon les besoins sans duplication.

Générateurs et Transformateurs

Kustomize propose des outils pour créer et modifier des ressources :

Générateurs : créent des ConfigMaps et des Secrets à partir de sources externes.
Transformateurs : modifient les ressources existantes, par exemple en ajoutant des labels ou en changeant les noms.

Patches

Les patches permettent d'appliquer des modifications ciblées aux ressources.

Exemple simple d’utilisation de Kustomize

Nous commençons par un exemple simple pour comprendre comment Kustomize fonctionne. Nous allons créer un deployement et le personnaliser pour deux environnements : dev et prod.

Voici l'arborescence de notre projet :

Répertoirekustomize-example/
- Répertoirebase/
  - kustomization.yaml
  - deployment.yaml
- Répertoireoverlays/
  - Répertoiredev/
    kustomization.yaml
    deployment-patch.yaml
  - Répertoireprod/
    kustomization.yaml
    deployment-patch.yaml

Création de la base

Commencer par créer le répertoire base/ dans le dossier de votre projet :

mkdir base

Dans ce répertoire, créez le fichier deployment.yaml :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: nginx:1.31.3@sha256:5a88c9c45479443d7be2eadc894b4ed0a9801bae03d97a5760ae13b5c2005942
          ports:
            - containerPort: 80

On définit ensuite la configuration de base dans le fichier base/kustomization.yaml :

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml

On déclare la ressource deployment.yaml dans le fichier kustomization.yaml.

Création des overlays pour Dev et Prod

Nous allons maintenant définir des overlays pour personnaliser le Namespace selon l’environnement.

Commencez par créer les répertoires dev/ et prod/ dans le dossier overlays/.

mkdir -p overlays/{dev,prod}

Créez les fichiers de patch dans chaque répertoire d'overlay.

Le fichier deployment-patch.yaml pour dev (1 réplica + label environnement) :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 1
  template:
    metadata:
      labels:
        env: dev

Ce patch modifie le nombre de réplicas et ajoute un label env: dev.

Le fichier deployment-patch.yaml pour la prod (3 réplicas + label environnement) :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  template:
    metadata:
      labels:
        env: prod

On créé ensuite les fichiers kustomization.yaml dans les répertoires dev/ et prod/ pour appliquer les patches :

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - ../../base

patches:
  - path: deployment-patch.yaml

Tester avant d'appliquer

Le bon réflexe tient en trois commandes, dans cet ordre :

Avant de déployer, toujours prévisualiser et valider :

kustomize build overlays/dev/ (ou kubectl kustomize overlays/dev/), Voir le YAML généré
kubectl diff -k overlays/dev/, Comparer avec l'existant
kubectl apply -k overlays/dev/, Appliquer

Générez les manifests pour dev :

# Avec kubectl intégré
kubectl kustomize overlays/dev/

# Ou avec le binaire standalone
kustomize build overlays/dev/

Résultat produit :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
        env: dev
    spec:
      containers:
      - image: nginx:1.31.3@sha256:5a88c9c45479443d7be2eadc894b4ed0a9801bae03d97a5760ae13b5c2005942
        name: my-app
        ports:
        - containerPort: 80

Pour la prod :

kubectl kustomize overlays/prod/

Résultat attendu :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
        env: prod
    spec:
      containers:
      - image: nginx:1.31.3@sha256:5a88c9c45479443d7be2eadc894b4ed0a9801bae03d97a5760ae13b5c2005942
        name: my-app
        ports:
        - containerPort: 80

Le nombre de réplicas et le label env sont différents pour dev et prod.

Appliquer au cluster :

# Prévisualiser les différences avec l'existant
kubectl diff -k overlays/dev/

# Appliquer
kubectl apply -k overlays/dev/

Comment gérer les namespaces avec Kustomize ?

Pour gérer les namespaces avec Kustomize, il suffit d'ajouter dans le fichier kustomization.yaml de chaque overlay le champ namespace :

namespace: my-app-dev

Pour le dev et :

namespace: my-app-prod

Pour la prod.

Lançons à nouveau la commande kubectl kustomize overlays/prod/ pour voir le résultat.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  namespace: my-app-prod
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
        env: prod
    spec:
      containers:
      - image: nginx:1.31.3@sha256:5a88c9c45479443d7be2eadc894b4ed0a9801bae03d97a5760ae13b5c2005942
        name: my-app
        ports:
        - containerPort: 80

Le namespace my-app-prod est automatiquement injecté dans toutes les ressources de l'overlay.

Plus de personnalisation avec Kustomize

Kustomize permet de personnaliser les ressources Kubernetes de plusieurs manières sans modifier directement les fichiers YAML d’origine. Ces customisations sont définies dans le fichier kustomization.yaml.

Ajout d’un préfixe (`namePrefix`)

On peut ajouter un préfixe à toutes les ressources définies dans un kustomization.yaml :

namePrefix: dev-

Une ressource Deployment nommée web-app deviendra dev-web-app.

Ajout d’un suffixe (`nameSuffix`)

De la même manière, on peut ajouter un suffixe :

nameSuffix: -v1

Une ressource web-app deviendra web-app-v1.

Ajouter une annotation commune (`commonAnnotations`)

Les annotations ne servent pas à sélectionner des objets, contrairement aux labels : elles portent des informations destinées aux humains et aux outils, une référence de ticket, un propriétaire, une date de livraison. Les poser depuis la surcouche évite de les recopier dans chaque manifeste, et garantit qu'aucun objet produit ne les perd en route.

On peut aussi ajouter une annotation :

commonAnnotations:
  owner: "admin@company.com"

Toutes les ressources auront cette annotation.

Créer une `ConfigMap` avec `configMapGenerator`

Au lieu d'écrire un fichier YAML à la main, on peut générer une ConfigMap directement :

configMapGenerator:
  - name: app-config
    literals:
      - ENV=production
      - LOG_LEVEL=debug

Résultat généré :

apiVersion: v1
data:
  ENV: production
  LOG_LEVEL: debug
kind: ConfigMap
metadata:
  name: app-config-f8269b54dd  # Hash ajouté automatiquement

Ce suffixe n'est pas un bruit, c'est le mécanisme lui-même :

Par défaut, Kustomize ajoute un suffixe hash aux ConfigMaps et Secrets générés (ex: app-config-f8269b54dd). C'est intentionnel : quand le contenu change, le nom change aussi, ce qui force un redéploiement des Pods qui l'utilisent.

Pour désactiver ce comportement (déconseillé) :

generatorOptions:
  disableNameSuffixHash: true

Créer un `Secret` avec `secretGenerator`

De la même façon, on peut générer un Secret. Privilégiez les fichiers plutôt que les literals pour éviter de committer des secrets dans Git :

secretGenerator:
  - name: db-secret
    files:
      - secrets/db-password.txt  # Fichier dans .gitignore
    type: Opaque

Avec secrets/db-password.txt contenant uniquement le mot de passe (sans retour à la ligne final).

Résultat généré :

apiVersion: v1
data:
  db-password.txt: c3VwZXJzZWNyZXQxMjM=  # Base64
kind: Secret
metadata:
  name: db-secret-gcf5mcd8td  # Hash ajouté
type: Opaque

Un détail décide du manifeste qui consommera ce Secret : la clé vaut le nom du fichier, db-password.txt dans l'exemple ci-dessus, et non un nom que vous auriez choisi. La syntaxe CLE=chemin la fixe explicitement, ce qui évite de devoir nommer un fichier d'après une variable d'environnement :

files:
  - PASSWORD=secrets/db-password.txt  # Clé = PASSWORD

Modifier les images dans les `Deployments`

Avec images, on remplace le nom, le tag ou le digest d’une image sans modifier le manifeste de base :

images:
  - name: nginx
    newName: registry.example.net/nginx-durci
    newTag: "1.31.3"

Appliqué à la base de ce guide, le rendu devient registry.example.net/nginx-durci:1.31.3. Un détail mérite votre attention, et il se voit dans cette sortie : la base était épinglée par digest, et newTag produit une référence par tag, donc l'épinglage disparaît. Pour le conserver, c'est le champ digest: qu'il faut employer à la place de newTag.

Intégration GitOps

Kustomize est nativement supporté par les outils GitOps :

Argo CD : détecte automatiquement les kustomization.yaml et applique les overlays
Flux : supporte Kustomize via les Kustomization CRDs

C'est l'une des raisons pour lesquelles Kustomize est populaire en production : il s'intègre sans friction dans un workflow GitOps.

Dépannage

Les deux premières lignes couvrent la quasi-totalité des appels à l'aide sur ce sujet, et elles ont un point commun : le message d'erreur ne nomme jamais Kustomize. Il parle d'un champ immuable ou d'un objet introuvable, parce que le cluster reçoit du YAML sans savoir d'où il vient. Le réflexe utile est donc de lire le rendu avec kubectl kustomize avant de chercher plus loin.

Symptôme	Cause probable	Solution
Patch non appliqué	Mauvais `name` dans le patch	Vérifier que `metadata.name` correspond à la ressource cible
`error: no objects passed to apply`	`resources` vide ou mal pointé	Vérifier le chemin dans `resources: [../../base]`
ConfigMap/Secret introuvable	Nom avec hash vs nom fixe	Le nom inclut un hash ; utiliser `kubectl get configmap` pour voir le nom réel
`unknown field`	Version kubectl trop ancienne	Mettre à jour kubectl ou utiliser le binaire kustomize
Labels non fusionnés	Patch partiel mal formé	Inclure le chemin complet (`spec.template.metadata.labels`)
Différence `kustomize build` vs `kubectl kustomize`	Versions différentes	Comparer `kustomize version` et `kubectl version`
`field is immutable` sur `spec.selector`	Un label a été poussé jusque dans les selectors d'un objet déjà déployé	Supprimer et recréer l'objet : `spec.selector` ne se modifie pas après création
Le Service ne route plus vers ses Pods	Le label d'environnement est sur les Pods mais pas dans le selector	Poser `includeSelectors: true` dans le bloc `labels`

À retenir

Kustomize permet de personnaliser des manifests Kubernetes sans templates ni duplication
La structure base + overlays sépare la config commune des spécificités par environnement
Utilisez toujours kubectl diff -k avant kubectl apply -k
Le champ patches: remplace les anciens patchesStrategicMerge et patchesJson6902
Les generators ajoutent un hash au nom des ConfigMaps/Secrets (c'est normal)
Ne jamais committer de secrets en clair, même avec secretGenerator
La version intégrée à kubectl peut différer du binaire standalone

Mettre en pratique

Une base, deux overlays, et la preuve que les deux environnements sortent bien du même fichier. Ce lab vous fait décrire l'application une seule fois, la déployer dans deux namespaces avec un nombre de replicas différent, puis vérifier que les deux déploiements partagent la même image et la même structure. Le piège du selector y est posé : sans includeSelectors, le Service ne trouve plus ses Pods.

Une base Kustomize et deux overlays, dev et prod

$ dsoxlab run ckad-kustomize-overlays

Environnement : VM·Durée : ~20 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que dsoxlab et comment l'installer

dsoxlab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/kubernetes-dsoxlab-training

Lancer ce lab, puis valider votre travail :

dsoxlab run ckad-kustomize-overlays
dsoxlab check ckad-kustomize-overlays

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille l'installation, le calcul du score et les pièges.

Testez vos connaissances

Les questions portent sur ce qui décide en pratique : le champ qui déclare la base, l'empreinte que les generators ajoutent au nom, la différence entre rendre et appliquer, et le piège du selector immuable. Une réponse ratée désigne la section à relire.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

8 min.

70% requis

Informations

Le chronomètre démarre au clic sur Démarrer
Questions à choix multiples, vrai/faux et réponses courtes
Vous pouvez naviguer entre les questions
Les résultats détaillés sont affichés à la fin

Pour aller plus loin

Kyverno : Transformer et valider les manifests à l'admission, quand la modification doit s'appliquer à ce que les autres déploient.
Operators : L'étage au-dessus, quand la variation entre environnements devient de la logique et non plus du YAML.
Certification CKAD : Kustomize y est attendu, au même titre que les manifests écrits à la main.

Kustomize : Factorisez vos manifests Kubernetes

Ce que vous allez apprendre

Qu'est-ce que Kustomize ?

Pourquoi utiliser Kustomize ?

Différences entre Kustomize et Helm

Installation de Kustomize

Concepts de Kustomize

Le fichier `kustomization.yaml`

Bases et Overlays

Générateurs et Transformateurs

Patches

Exemple simple d’utilisation de Kustomize

Création de la base

Création des overlays pour Dev et Prod

Tester avant d'appliquer

Comment gérer les namespaces avec Kustomize ?

Plus de personnalisation avec Kustomize

Ajout d’un préfixe (`namePrefix`)

Ajout d’un suffixe (`nameSuffix`)

Ajouter une annotation commune (`commonAnnotations`)

Créer une `ConfigMap` avec `configMapGenerator`

Créer un `Secret` avec `secretGenerator`

Modifier les images dans les `Deployments`

Intégration GitOps

Dépannage

À retenir

Mettre en pratique

Testez vos connaissances

Contrôle de connaissances

Informations

Vérification

Profil de compétences

Quoi faire maintenant

Pour aller plus loin

Kustomize : Factorisez vos manifests Kubernetes

Ce que vous allez apprendre

Qu'est-ce que Kustomize ?

Pourquoi utiliser Kustomize ?

Différences entre Kustomize et Helm

Installation de Kustomize

Concepts de Kustomize

Le fichier kustomization.yaml

Bases et Overlays

Générateurs et Transformateurs

Patches

Exemple simple d’utilisation de Kustomize

Création de la base

Création des overlays pour Dev et Prod

Tester avant d'appliquer

Comment gérer les namespaces avec Kustomize ?

Plus de personnalisation avec Kustomize

Ajout d’un préfixe (namePrefix)

Ajout d’un suffixe (nameSuffix)

Ajouter une annotation commune (commonAnnotations)

Créer une ConfigMap avec configMapGenerator

Créer un Secret avec secretGenerator

Modifier les images dans les Deployments

Intégration GitOps

Dépannage

À retenir

Mettre en pratique

Testez vos connaissances

Contrôle de connaissances

Informations

Profil de compétences

Quoi faire maintenant

Pour aller plus loin

Le fichier `kustomization.yaml`

Ajout d’un préfixe (`namePrefix`)

Ajout d’un suffixe (`nameSuffix`)

Ajouter une annotation commune (`commonAnnotations`)

Créer une `ConfigMap` avec `configMapGenerator`

Créer un `Secret` avec `secretGenerator`

Modifier les images dans les `Deployments`