Kustomize : installation, templates et déploiement

Kustomize est un outil de configuration Kubernetes qui permet de personnaliser des manifests YAML par composition et patches, sans templating. Intégré dans kubectl depuis la v1.14 (kubectl apply -k), il fonctionne par superposition : une base contient les manifests communs, des overlays (dev, staging, prod) y appliquent les différences (patches, variables d'images, préfixes de noms, labels). Pas de template engine, uniquement du YAML pur - ce qui le rend plus prévisible que Helm pour les workflows orientés GitOps.

Informations essentielles

Origine : Google → Kubernetes SIG CLI · Licence : Apache 2.0 · Architectures : x86_64, ARM64

Liens : Site officiel · Documentation · GitHub

Support : Intégré dans kubectl. Maintenu par Kubernetes SIG CLI.

Stack par défaut

Composant	Valeur
Intégration kubectl	`kubectl apply -k` et `kubectl kustomize`
CLI standalone	`kustomize` (version plus récente que kubectl intégré)
Fichier central	`kustomization.yaml` dans chaque répertoire
Patches	Strategic Merge Patch, JSON 6902 Patch
Transformers	namePrefix, nameSuffix, commonLabels, commonAnnotations, images

Prérequis

Ressource	Valeur
kubectl	1.14+ (kustomize intégré)
kustomize CLI	Optionnel, pour une version plus récente que kubectl embarqué

Installation (CLI standalone)

# Script officiel
curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
sudo mv kustomize /usr/local/bin/

# Homebrew
brew install kustomize

kustomize version

Structure type d'un projet Kustomize

my-app/
├── base/                     # Manifests communs
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   └── service.yaml
└── overlays/
    ├── dev/
    │   ├── kustomization.yaml
    │   └── patch-replicas.yaml
    ├── staging/
    │   └── kustomization.yaml
    └── production/
        ├── kustomization.yaml
        ├── patch-resources.yaml
        └── patch-ingress.yaml

Base - kustomization.yaml

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

resources:
  - deployment.yaml
  - service.yaml
  - ingress.yaml

# base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: my-app
          image: ghcr.io/org/my-app:latest
          resources:
            requests:
              cpu: 100m
              memory: 128Mi

Overlay Production

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

namePrefix: prod-           # Préfixe sur tous les noms de ressources
namespace: production

resources:
  - ../../base

# Remplacer l'image avec le bon tag de prod
images:
  - name: ghcr.io/org/my-app
    newTag: "1.4.2"

# Ajouter des labels communs
commonLabels:
  env: production

# Patches spécifiques à la prod
patches:
  - path: patch-replicas.yaml
  - path: patch-resources.yaml

# overlays/production/patch-replicas.yaml - Strategic Merge Patch
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app           # cible le Deployment my-app de la base
spec:
  replicas: 5

# overlays/production/patch-resources.yaml - Strategic Merge Patch
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
        - name: my-app
          resources:
            requests:
              cpu: 500m
              memory: 512Mi
            limits:
              cpu: 1000m
              memory: 1Gi

Appliquer une configuration

# Prévisualiser les manifests générés
kubectl kustomize overlays/production
# ou avec la CLI standalone
kustomize build overlays/production

# Appliquer directement
kubectl apply -k overlays/production

# Prévisualiser + appliquer via pipe
kustomize build overlays/production | kubectl apply -f -

# Supprimer les ressources
kubectl delete -k overlays/production

Fonctionnalités avancées

Références à des ConfigMaps et Secrets depuis des fichiers

# kustomization.yaml
configMapGenerator:
  - name: app-config
    files:
      - config/app.properties
    literals:
      - LOG_LEVEL=info
      - ENV=production

secretGenerator:
  - name: db-credentials
    literals:
      - username=admin
      - password=secret
    type: Opaque

Inclure des ressources depuis une URL Git

resources:
  - github.com/kubernetes-sigs/kustomize/examples/multibases/dev/?ref=v5.4.0
  - ../../base

Variables de substitution (via Replacements)

# kustomization.yaml
replacements:
  - source:
      kind: Service
      name: my-app
      fieldPath: metadata.name
    targets:
      - select:
          kind: Ingress
          name: my-app
        fieldPaths:
          - spec.rules.0.http.paths.0.backend.service.name

Mise à jour

# CLI standalone
curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash
sudo mv kustomize /usr/local/bin/

# Via Homebrew
brew upgrade kustomize

Troubleshooting

# Vérifier la sortie avant d'appliquer
kustomize build overlays/production | kubectl diff -f -

# Lister les ressources qui seraient appliquées
kustomize build overlays/production | grep "^kind:"

# Valider la syntaxe (dry-run)
kubectl apply -k overlays/production --dry-run=client

# Erreur "no such file or directory" dans les patches
# Vérifier que le name dans le patch correspond exactement à celui de la base
# (avant application des namePrefix)

Ressources

Site officiel : https://kustomize.io
Documentation de référence : https://kubectl.docs.kubernetes.io/references/kustomize/
GitHub : https://github.com/kubernetes-sigs/kustomize
Exemples : https://github.com/kubernetes-sigs/kustomize/tree/master/examples