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 ?

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

Glissez pour voir

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.

Version intégrée vs standalone

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.

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.

Migration depuis patchesStrategicMerge

Si vous voyez patchesStrategicMerge ou patchesJson6902 dans d’anciens tutoriels, sachez que ces champs sont dépréciés. Utilisez le champ unifié patches: à la place.

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:latest
          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

Workflow recommandé

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

1. kustomize build overlays/dev/ (ou kubectl kustomize overlays/dev/) — Voir le YAML généré
2. kubectl diff -k overlays/dev/ — Comparer avec l’existant
3. 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:latest
        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:latest
        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:latest
        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)

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

Pourquoi le hash dans le nom ?

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

Nom de clé = nom de fichier

La clé du Secret est le nom du fichier (db-password.txt), pas une clé personnalisée. Pour choisir le nom de la clé :

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

Ne jamais committer de secrets

Même avec secretGenerator, les secrets en clair n’ont pas leur place dans Git. En production, utilisez :

• SOPS : chiffrement des fichiers secrets dans le repo
• Sealed Secrets : secrets chiffrés côté cluster
• External Secrets Operator : secrets depuis un vault externe (AWS SM, HashiCorp Vault…)

Modifier les images dans les Deployments

Avec images, on peut modifier le nom ou la version d’une image sans modifier le manifeste :

images:
  - name: nginx
    newName: my-nginx
    newTag: "1.21"

Une image nginx:latest sera remplacée par my-nginx:1.21.

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

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

Glissez pour voir

À 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

Prochaines étapes

Helm : gestionnaire de packages Kubernetes Pour des déploiements plus complexes avec gestion des dépendances

kubectl : interagir avec Kubernetes Maîtriser la CLI Kubernetes pour le déploiement et le debug

×

📖 Voir la documentation →