Installer Flux CD — Bootstrap et configuration initiale

Flux CD s’installe sur un cluster Kubernetes en une seule commande de bootstrap. Ce guide couvre l’installation du CLI flux, la vérification de compatibilité du cluster, le bootstrap sur GitHub ou GitLab, et les premières commandes pour vérifier que tout fonctionne. À la fin, vous avez un Flux opérationnel qui surveille son propre dépôt.

Ce que vous allez apprendre

Installer le CLI flux sur votre machine
Vérifier la compatibilité de votre cluster avec flux check --pre
Bootstrapper Flux sur GitHub ou GitLab en une commande
Comprendre la structure créée dans votre dépôt par le bootstrap
Diagnostiquer l’état des composants Flux avec flux get all

Prérequis

Avant de commencer, vérifiez que vous avez :

Un cluster Kubernetes v1.28+ fonctionnel — kind, k3s, ou un cluster cloud
kubectl installé et configuré avec accès admin au cluster
Un compte GitHub ou GitLab avec droits de création de dépôt
Un token d’accès personnel (PAT) GitHub ou GitLab avec droits repo

Vérification des prérequis :

kubectl version --client
kubectl get nodes   # Tous les nœuds doivent être Ready

Pour un environnement de test rapide, installez kind et créez un cluster en une commande :

kind create cluster --name flux-lab
kubectl get nodes
# NAME                     STATUS   ROLES           AGE
# flux-lab-control-plane   Ready    control-plane   30s

Installer le CLI flux

La méthode recommandée utilise le script d’installation officiel Flux :

curl -s https://fluxcd.io/install.sh | sudo bash

Vérifiez l’installation :

flux --version
# flux version 2.8.3

Activez l’autocomplétion (optionnel mais utile) :

# Bash
echo "source <(flux completion bash)" >> ~/.bashrc

# Zsh
echo "source <(flux completion zsh)" >> ~/.zshrc

brew install fluxcd/tap/flux
flux --version
# flux version 2.8.3

Téléchargez le binaire pour votre architecture depuis les releases GitHub :

# Linux amd64
FLUX_VERSION=2.8.3
curl -Lo flux.tar.gz "https://github.com/fluxcd/flux2/releases/download/v${FLUX_VERSION}/flux_${FLUX_VERSION}_linux_amd64.tar.gz"
tar -xzf flux.tar.gz
sudo mv flux /usr/local/bin/
flux --version

Vérifier la compatibilité du cluster

Avant le bootstrap, vérifiez que votre cluster est compatible avec Flux :

flux check --pre

Attendu :

► checking prerequisites
✔ Kubernetes 1.32.0 >=1.28.0-0
✔ prerequisites checks passed

Si vous voyez des erreurs (version Kubernetes trop ancienne, droits insuffisants), corrigez-les avant de continuer.

Bootstrapper Flux

Le bootstrap est une opération idempotente : vous pouvez la relancer sans risque si elle échoue ou si vous voulez reconfigurer Flux. Elle :

Crée les manifestes des composants Flux.
Les pousse dans votre dépôt Git.
Les applique sur le cluster.

Créez un token GitHub PAT (Personal Access Token) avec les droits repo (lecture + écriture sur les dépôts). Il sera utilisé uniquement pendant le bootstrap pour créer le dépôt et pousser les manifestes.

# Exportez votre token GitHub
export GITHUB_TOKEN=<votre-token>
export GITHUB_USER=<votre-username>

# Bootstrap Flux sur un nouveau dépôt
flux bootstrap github \
  --owner=${GITHUB_USER} \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/my-cluster \
  --personal

Détail des options :

Option	Description
`--owner`	Votre nom d’utilisateur ou organisation GitHub
`--repository`	Nom du dépôt (créé s’il n’existe pas)
`--branch`	Branche à surveiller (doit exister ou `--branch` crée `main`)
`--path`	Chemin dans le dépôt où Flux place ses composants
`--personal`	Indique un dépôt personnel (pas d’organisation)

export GITLAB_TOKEN=<votre-token>
export GITLAB_USER=<votre-username>

flux bootstrap gitlab \
  --owner=${GITLAB_USER} \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/my-cluster \
  --personal

Pour un groupe GitLab (namespace partagé), remplacez --owner par le nom du groupe et retirez --personal.

export GITEA_TOKEN=<votre-token>

flux bootstrap gitea \
  --hostname=gitea.example.com \
  --owner=<votre-username> \
  --repository=fleet-infra \
  --branch=main \
  --path=clusters/my-cluster \
  --personal

Sortie attendue du bootstrap

► connecting to github.com
► cloning branch "main" from Git repository "https://github.com/user/fleet-infra.git"
✔ cloned repository
► generating component manifests
✔ generated component manifests
✔ committed component manifests to "main" ("fleet-infra")
► pushing component manifests to "https://github.com/user/fleet-infra.git"
► installing components in "flux-system" namespace
✔ installed components
✔ reconciled components
► determining if source secret "flux-system/flux-system" exists
► generating source secret
✔ public key: ecdsa-sha2-nistp384 AAAA...
✔ configured deploy key
► applying source secret "flux-system/flux-system"
✔ reconciled source secret
► generating sync manifests
✔ generated sync manifests
✔ committed sync manifests to "main" ("fleet-infra")
► pushing sync manifests to "https://github.com/user/fleet-infra.git"
► applying sync manifests
✔ reconciled sync configuration
◎ waiting for Kustomization "flux-system/flux-system" to be reconciled
✔ Kustomization reconciled successfully
► confirming components are healthy
✔ helm-controller: deployment ready
✔ kustomize-controller: deployment ready
✔ notification-controller: deployment ready
✔ source-controller: deployment ready
✔ all components are healthy

Comprendre la structure créée dans Git

Après le bootstrap, votre dépôt contient :

fleet-infra/
└── clusters/
    └── my-cluster/
        └── flux-system/
            ├── gotk-components.yaml   # CRDs + Deployments des 5 contrôleurs
            ├── gotk-sync.yaml         # GitRepository + Kustomization
            └── kustomization.yaml     # Assemblage Kustomize

gotk-components.yaml — Ce fichier contient tous les composants Flux : les CRDs (CustomResourceDefinitions), les Deployments des 5 contrôleurs, les ServiceAccounts et les RBAC. Ne modifiez jamais ce fichier manuellement — utilisez flux install ou le bootstrap pour le mettre à jour.

gotk-sync.yaml — Ce fichier déclare deux objets :

Un GitRepository qui pointe vers votre dépôt.
Une Kustomization qui applique le contenu de clusters/my-cluster/.

C’est la boucle de self-management : Flux surveille son propre dépôt et se met à jour si vous modifiez les fichiers dans flux-system/.

Vérifier l’état de Flux

Une fois le bootstrap terminé, vérifiez que tous les composants sont sains :

# Vérifier les composants Flux
flux check

# Lister toutes les ressources Flux
flux get all

# Vérifier les pods dans le namespace flux-system
kubectl get pods -n flux-system

Attendu pour kubectl get pods -n flux-system :

NAME                                       READY   STATUS    RESTARTS   AGE
helm-controller-7b9b8b7c4-x2k9p           1/1     Running   0          2m
kustomize-controller-6d5f9b8c9-p4m7n      1/1     Running   0          2m
notification-controller-5c8d7b6f4-r8j2l   1/1     Running   0          2m
source-controller-5f7b9c8d6-k3n5q         1/1     Running   0          2m

Attendu pour flux get all :

NAME                        REVISION        SUSPENDED  READY   MESSAGE
gitrepository/flux-system   main/abc1234    False      True    stored artifact for revision 'main@sha1:abc1234'

NAME                        REVISION        SUSPENDED  READY   MESSAGE
kustomization/flux-system   main/abc1234    False      True    Applied revision: main@sha1:abc1234

Tous les objets doivent afficher READY: True.

Diagnostiquer les problèmes courants

Flux ne réconcilie pas

Si un objet affiche READY: False, inspectez les événements :

# Voir les événements d'une Kustomization
flux events --for kustomization/flux-system

# Voir les logs du contrôleur
kubectl logs -n flux-system deploy/kustomize-controller | tail -20

Le dépôt Git est inaccessible

# Vérifier la Source GitRepository
flux get source git

# Forcer une reconcile immédiate
flux reconcile source git flux-system

Si la source affiche une erreur d’authentification, vérifiez la deploy key :

kubectl describe secret -n flux-system flux-system

Un pod ne démarre pas

kubectl describe pod -n flux-system <nom-du-pod>
kubectl logs -n flux-system <nom-du-pod> --previous

Commandes de base à retenir

Commande	Description
`flux check`	Vérifie l’état des composants Flux
`flux get all`	Liste toutes les ressources Flux et leur état
`flux get sources git`	Affiche les GitRepository
`flux get kustomizations`	Affiche les Kustomizations
`flux reconcile source git <nom>`	Force la resynchronisation d’un dépôt
`flux reconcile kustomization <nom>`	Force la réconciliation d’une Kustomization
`flux events`	Affiche les événements récents
`flux logs`	Affiche les logs des contrôleurs
`flux suspend kustomization <nom>`	Met en pause une Kustomization
`flux resume kustomization <nom>`	Reprend une Kustomization suspendue

À retenir

Le CLI flux s’installe avec le script officiel ou Homebrew.
flux check --pre vérifie la compatibilité avant le bootstrap.
flux bootstrap est idempotent : on peut le relancer sans risque.
Le bootstrap crée une deploy key SSH stockée dans le Secret flux-system/flux-system.
Flux se gère lui-même : modifier gotk-sync.yaml dans Git met à jour Flux.
flux get all est la commande de diagnostic principale.

Prochaines étapes

Première application avec Kustomize Déployer votre première app depuis Git — GitRepository, Kustomization et flux get

Déploiements Helm avec HelmRelease Gérer des releases Helm de façon déclarative avec Flux

Concepts et architecture Flux CD Comprendre les 5 contrôleurs et le modèle Sources-Artefacts