Flux CD — Première application avec Kustomize

Flux est installé et surveille votre dépôt. Vous allez maintenant déployer une première application réelle depuis Git. Ce guide explique comment créer une GitRepository (source), une Kustomization (déploiement), lire les statuts de réconciliation et vérifier que le self-healing fonctionne — la marque qu’un déploiement GitOps propre.

Guide précédent requis

Ce guide suppose que Flux est déjà bootstrappé sur votre cluster. Si ce n’est pas encore le cas, suivez d’abord Bootstrap et installation.

Ce que vous allez apprendre

• Structurer un dépôt Git de configuration pour plusieurs applications
• Créer une GitRepository pointant vers un dépôt Git
• Créer une Kustomization qui déploie les manifestes d’une application
• Lire les statuts de réconciliation : READY, SUSPENDED, FAILED
• Tester le self-healing : modifier le cluster et voir Flux corriger
• Suspendre et reprendre une Kustomization

Prérequis

• Flux bootstrappé sur un cluster (flux check affiche tout en vert)
• Un dépôt Git accessible par Flux (celui créé au bootstrap)
• kubectl et flux CLI installés localement

Structure du dépôt de configuration

Commençons par comprendre comment organiser le dépôt fleet-infra créé au bootstrap. La convention recommandée par Flux :

fleet-infra/
├── clusters/
│   └── my-cluster/
│       ├── flux-system/         ← Géré par Flux, ne pas modifier manuellement
│       └── apps.yaml            ← Kustomization racine des applications
├── apps/
│   ├── base/                    ← Manifestes de base
│   │   └── podinfo/             ← Une application
│   │       ├── deployment.yaml
│   │       ├── service.yaml
│   │       └── kustomization.yaml
│   ├── development/
│   │   └── podinfo/
│   │       └── kustomization.yaml   ← Overlay dev
│   └── production/
│       └── podinfo/
│           └── kustomization.yaml   ← Overlay prod
└── infrastructure/
    └── sources/
        └── podinfo.yaml         ← GitRepository

Cette structure sépare clairement :

• clusters/ : ce qui est spécifique à chaque cluster
• apps/ : les applications (base partagée + overlays par environnement)
• infrastructure/ : les sources et composants d’infrastructure partagés

Déployer une première application

Nous allons déployer podinfo, une application de démo légère souvent utilisée dans les tutoriels Kubernetes.

1. Créer la Source GitRepository

Dans votre dépôt fleet-infra, créez infrastructure/sources/podinfo.yaml :

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 1m
  ref:
    branch: master
  url: https://github.com/stefanprodan/podinfo

Ce fichier déclare que Flux doit surveiller le dépôt stefanprodan/podinfo sur la branche master et télécharger une archive toutes les minutes.

2. Créer la Kustomization de déploiement

Créez apps/base/podinfo/kustomization.yaml dans votre dépôt :

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml

Et clusters/my-cluster/apps.yaml :

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: apps
  namespace: flux-system
spec:
  interval: 5m
  path: ./apps/base/podinfo
  prune: true
  sourceRef:
    kind: GitRepository
    name: podinfo
  targetNamespace: podinfo

Deux types de Kustomization

Il y a deux fichiers différents ici :

• kustomization.yaml (minuscule) — fichier de configuration de l’outil CLI Kustomize qui liste les ressources à assembler.
• Kustomization (CRD Flux) — ressource Kubernetes qui dit à Flux quoi réconcilier depuis quelle source.

Les deux coexistent dans le dépôt sans conflit.

3. Pousser dans Git et observer la réconciliation

# Depuis la racine de fleet-infra
git add .
git commit -m "feat: add podinfo application"
git push origin main

Flux détecte le changement dans votre dépôt (dans les 60 secondes ou immédiatement si vous avez configuré un Receiver). Il applique les manifestes automatiquement.

Pour déclencher une réconciliation immédiate sans attendre :

flux reconcile source git flux-system
flux reconcile kustomization flux-system

4. Vérifier les statuts de réconciliation

# Lister les kustomizations
flux get kustomizations
# NAME      REVISION        SUSPENDED  READY   MESSAGE
# apps      master/a1b2c3   False      True    Applied revision: master@sha1:a1b2c3
# flux-system  main/d4e5f6  False      True    Applied revision: main@sha1:d4e5f6

# Vérifier les pods déployés
kubectl get pods -n podinfo
# NAME                       READY   STATUS    RESTARTS   AGE
# podinfo-7d9f8c6b5-x2k9p   1/1     Running   0          30s

# Voir les événements Flux
flux events --for kustomization/apps

5. Créer un namespace dédié (recommandé)

Par défaut, targetNamespace: podinfo déploie dans un namespace qui doit exister. Créez-le explicitement pour éviter une erreur :

kubectl create namespace podinfo

Ou ajoutez un Namespace dans les manifestes de base avec l’annotation kubectl.kubernetes.io/last-applied-configuration pour que Flux le gère.

Comprendre les statuts de réconciliation

Flux expose trois informations pour chaque ressource :

Champ	Valeurs possibles	Signification
READY	True, False, Unknown	L’objet est dans l’état souhaité
SUSPENDED	True, False	La réconciliation est mise en pause
MESSAGE	Texte libre	Dernier message de statut

Glissez pour voir

Statuts courants

Applied revision: ... — succès, les manifestes ont été appliqués.

Reconciliation in progress — Flux est en train de réconcilier.

kustomization path not found — le path déclaré dans la Kustomization n’existe pas dans la source. Vérifiez le chemin relatif.

Source not ready — la GitRepository référencée n’est pas prête. Déboguez d’abord la source : flux get source git.

namespace not found — le targetNamespace déclaré n’existe pas dans le cluster. Créez le namespace ou gérez-le dans les manifestes.

Tester le self-healing

Le self-healing est l’une des propriétés fondamentales du GitOps : toute modification manuelle du cluster est automatiquement annulée par Flux.

Voici comment le tester :

# Modifier manuellement le nombre de replicas
kubectl scale deployment podinfo -n podinfo --replicas=5

# Observer le changement
kubectl get deployment podinfo -n podinfo
# READY   UP-TO-DATE   AVAILABLE
# 5/5     5            5

# Attendre jusqu'à 5 minutes (ou forcer la reconcile)
flux reconcile kustomization apps

# Vérifier que Flux a rétabli la valeur déclarée dans Git
kubectl get deployment podinfo -n podinfo
# READY   UP-TO-DATE   AVAILABLE
# 2/2     2            2

Flux a détecté que l’état du cluster (5 replicas) différait de ce qui est déclaré dans Git (2 replicas) et a corrigé automatiquement.

Le self-healing ne s'applique qu'aux champs gérés par Flux

Flux gère le self-healing sur les champs qu’il a lui-même appliqués. Si un autre outil (HPA, VPA, opérateur custom) modifie un champ que Flux gère aussi, un conflit de réconciliation peut survenir. Dans ce cas, utilisez kustomize patches pour exclure les champs gérés par d’autres outils.

Suspendre et reprendre une Kustomization

Il est parfois nécessaire de suspendre la réconciliation d’une Kustomization — avant une opération de maintenance, par exemple, ou lors d’un débogage :

# Suspendre
flux suspend kustomization apps

# Flux affiche SUSPENDED: True
flux get kustomizations
# NAME   REVISION        SUSPENDED  READY  MESSAGE
# apps   master/a1b2c3   True       True   ...

# Faire votre opération de maintenance...

# Reprendre
flux resume kustomization apps

Une Kustomization suspendue ne se self-heal pas

Pendant la suspension, les modifications manuelles du cluster ne seront pas rétablies par Flux. Reprenez la réconciliation dès que possible pour retrouver les garanties GitOps.

Dépendances entre Kustomizations

Quand une application dépend d’une autre (par exemple, une application qui nécessite qu’une base de données soit déployée en premier), utilisez spec.dependsOn :

apiVersion: kustomize.toolkit.fluxcd.io/v1
kind: Kustomization
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 5m
  dependsOn:
    - name: database    # my-app attend que database soit READY
  path: ./apps/my-app
  prune: true
  sourceRef:
    kind: GitRepository
    name: fleet-infra

Flux attend que database soit READY: True avant de réconcilier my-app. Si database échoue, my-app reste en attente.

Utiliser un dépôt privé

Si votre dépôt d’application est privé (séparé du dépôt de configuration), vous devez créer un Secret avec les credentials :

# Créer un Secret avec une clé SSH dédiée
flux create secret git my-app-credentials \
  --url=ssh://git@github.com/my-org/my-app \
  --ssh-key-algorithm=ecdsa \
  --ssh-ecdsa-curve=p521

Cette commande génère une paire de clés SSH et affiche la clé publique. Ajoutez cette clé publique comme deploy key sur votre dépôt GitHub.

Puis référencez ce Secret dans la GitRepository :

apiVersion: source.toolkit.fluxcd.io/v1
kind: GitRepository
metadata:
  name: my-app
  namespace: flux-system
spec:
  interval: 1m
  url: ssh://git@github.com/my-org/my-app
  ref:
    branch: main
  secretRef:
    name: my-app-credentials

À retenir

• GitRepository déclare une source — Flux télécharge son contenu.
• Kustomization déclare ce qu’on déploie depuis une source et où.
• Le self-healing corrige automatiquement toute dérive entre Git et le cluster — c’est la garantie fondamentale du GitOps.
• prune: true supprime du cluster les ressources retirées de Git.
• dependsOn permet d’ordonner les déploiements inter-dépendants.
• flux suspend / flux resume permettent de mettre en pause sans supprimer.

Prochaines étapes

Déploiements Helm avec HelmRelease Gérer des releases Helm déclaratives avec HelmRepository et HelmRelease

Multi-tenancy Isoler les équipes avec des namespaces dédiés et du RBAC fin

Automatisation d'images Flux détecte les nouvelles images et met à jour Git automatiquement

×

📖 Voir la documentation →