ClusterAPI : gérer les clusters Kubernetes comme du code

Introduction

Kubernetes a transformé la manière de déployer des applications. Mais dans la majorité des organisations, la création et la maintenance des clusters Kubernetes restent encore largement manuelles, hétérogènes et fragiles. Clusters créés à la main, scripts spécifiques par environnement, procédures de mise à niveau risquées, destruction manuelle : ces pratiques deviennent rapidement un goulot d’étranglement opérationnel.

Le problème est simple : on traite Kubernetes comme du code, mais l’infrastructure Kubernetes elle-même reste un artefact manuel.

C’est exactement ce que ClusterAPI (CAPI) résout. En offrant une approche déclarative et standardisée à la gestion des clusters, CAPI permet de traiter l’infrastructure Kubernetes comme du vrai code : versionné dans Git, automatisé par CI/CD, reproductible et avec une auditabilité complète.

Le problème : pourquoi les clusters manuels deviennent un enfer

La réalité du quotidien

Imaginez ce scénario typique :

• Un développeur ouvre une MR pour tester une nouvelle fonctionnalité sur un environnement isolé.
• Il demande au DevOps de créer un cluster de test. Ou pire : il utilise un script maison écrit par un collègue parti il ​​ya 2 ans.
• Le cluster est créé… mais pas vraiment « comme les autres ». Les versions Kubernetes diffèrent. Les configurations réseau ne sont pas identiques. Les politiques de sécurité manquent.
• Après examen, le cluster doit être détruit. Mais quelqu’un oublie une ressource Azure, une VMSS reste allumée, et ça coûte cher en silence.
• Six mois plus tard, le cluster de production a dérivé de tant de façons qu’on ne sait plus vraiment comment il fonctionne.

Ce tableau n’est pas une fiction. C’est la réalité dans 70% des organisations.

Les vrais coûts cachés

• Latence opérationnelle : créer un cluster manuellement ou via script prend 4-8h, vérification manuelle comprend.
• Erreurs humaines : oublis de configuration, incohérences entre environnements, risques de sécurité.
• Drift opérationnel : après déploiement, le cluster réel diverge de la « définition » initiale.
• Coûts cloud non maîtrisés : ressources orphelines, oublis de nettoyage, instances tournant inutilement.
• Frustration d’équipe : les DevOps passent du temps sur des tâches répétitives au lieu de l’architecture.

La solution : ClusterAPI et la gestion déclarative

Qu’est-ce que ClusterAPI ?

ClusterAPI est un projet CNCF qui apporte une API Kubernetes standard pour créer, mettre à jour et détruire des clusters Kubernetes de manière déclarative.

Simple en apparence, radical en impact :

• Un cluster Kubernetes devient une ressource Kubernetes : un objet Cluster créé via kubectl apply.
• Les nœuds, machines, réseaux et load balancers sont décrits dans des manifestes YAML.
• Le cycle de vie complet (provisioning, mise à l’échelle, mise à niveau, réparation) est automatisé par des contrôleurs.
• L’état souhaité vit dans Git. GitOps applique l’état. Les devs ne créent plus « à la main » : ils ouvrent une MR.

Architecture logique

CAPI s’appuie sur des fournisseurs :

• Fournisseurs d’infrastructures (Azure/CAPZ, AWS/CAPA, GCP, vSphere, OpenStack, etc.) : responsables de créer/détruire les VMs et ressources cloud.
• Fournisseur Bootstrap (kubeadm) : responsable d’initialiser Kubernetes sur les VMs.
• Fournisseur ControlPlane (kubeadm) : responsable du plan de contrôle.

Le modèle est en étoile :

1. Un cluster de gestion héberge CAPI et ses contrôleurs.
2. CAPI crée/gère des workload clusters déclarés en YAML.
3. Le cluster de gestion peut être local (kind, k3d, kubeadm, talos) ou un cluster géré existant.

Le cas d’usage : clusters éphémères par MR

Le scénario réel

Chez Néosoft et nos clients, voici un pattern puissant et concret :

1. Dev ouvre une MR pour une fonctionnalité applicative.
2. Un webhook GitLab CI a déclenché un pipeline qui applique un manifeste CAPI.
3. Un cluster Kubernetes dédié est créé en ~10-15 minutes via Azure + CAPZ.
4. ArgoCD déploie automatiquement l’application sur ce cluster éphémère.
5. Dev et reviewers testent, font leur review d’app.
6. À la fusion (ou fermeture) de la MR, un travail CI détruit le manifeste CAPI.
7. Toutes les ressources Azure sont automatiquement nettoyées en ~5-10 minutes.

Résultat :

✅ Chaque MR a un cluster isolé, garanti identique aux autres.

✅ Zéro création manuelle, zéro risque d’oubli de nettoyage.

✅ Coût cloud réel et maîtrisé : la ressource existe que le temps de la MR.

✅ Reproductibilité garantie : même cluster, même config, même réseau.

✅ Auditabilité complète : qui a créé/détruit quoi, via quel commit.

Autres cas d’usage (brièvement)

• Staging multi-tenant : chaque client a son propre cluster créé/détruit via CAPI.
• Multi-cloud standardisé : même YAML sur Azure, AWS, GCP → réduction drastique de la complexité.
• Disaster recovery : recréer un cluster depuis zéro en quelques minutes, garanti fonctionnel.
• Environnements de formation/démo : clusters jetables à volonté, sans friction.

Les providers : CAPZ, CAPA et les addons gérés

Qu’est-ce qu’un fournisseur ?

Un fournisseur est un contrôleur Kubernetes qui étend CAPI pour un cloud spécifique ou un type d’infrastructure. Il traduit les manifestes CAPI déclaratifs en appels API cloud réels.

Les principaux fournisseurs

• CAPZ (Cluster API Provider Azure) : crée/gère des clusters sur Azure (VMs, VMSS, réseaux, load balancers).
• CAPA (Cluster API Provider AWS) : crée/gère des clusters sur AWS (EC2, VPC, ELB, etc.).
• CAPG (Cluster API Provider Google Cloud) : crée/gère des clusters sur GCP.
• CAPV (Cluster API Provider vSphere) : crée/gère des clusters sur vSphere on-premise.

Les addons gérés : quand laisser le cloud supplier gérer

CAPI permet également de créer des clusters Kubernetes gérés via des addons spécialisés :

• AKS sur Azure : AzureClusterpeut être configuré pour utiliser AKS géré au lieu de créer des VM manuellement. Le plan de contrôle est géré par Azure.
• EKS sur AWS : similaire, le plan de contrôle est géré par AWS.
• GKE sur GCP : le plan de contrôle est géré par Google.

Avantage : vous gardez la déclaration CAPI (versionnage, GitOps, reproductibilité) sans gérer le plan de contrôle vous-même. Azure/AWS/GCP gère les mises à jour, la haute disponibilité, les patchs de sécurité.

Exemple : avec CAPZ, vous pouvez créer un AKS géré via CAPI, ajouter des pools de nœuds (workers) gérés, et laisser Azure gérer le reste. C’est le meilleur des deux mondes : IaC déclaratif + infrastructure managée.

Mise en œuvre : de la théorie à la pratique

Prérequis

• Configurer Azure CLI (az login).
  Un abonnement Azure avec quotas suffisants (CPU, IP publiques).
• kubectl pointant sur un cluster de gestion Kubernetes existant (AKS, ou cluster local).
• clusterctl installer.
• Un repo GitLab ou GitHub pour versionner vos manifestes CAPI.

Étape 1 : Initialiser CAPI sur le Management Cluster

clusterctl init --infrastructure azure

Cela installe :

• Les CRD CAPI.
• Le fournisseur Azure (CAPZ).
• Les fournisseurs de plan d’amorçage et de plan de contrôle (kubeadm).

Vérification :

kubectl get pods -n capz-system
kubectl get pods -n capi-system

Étape 2 : Configurer l’Identité Azure (Workload Identity)

CAPI doit créer des ressources Azure. Au lieu de stocker des identifiants, utilisez Azure Workload Identity (moderne et sécurisé) :

# Créer une identité gérée et lui donner les droits
az identity create --resource-group <RG> --name capi-identity
az role assignment create \
  --role "Contributor" \
  --assignee <IDENTITY_CLIENT_ID> \
  --scope /subscriptions/<SUB_ID>

Ensuite, créez un Kubernetes secret avec les informations d’identification de l’identité (la vraie approche sécurisée demande une fédération OIDC, mais ce workflow basique fonctionne).

Étape 3 : Créer un Cluster AKS Managé avec CAPI

Voici un manifeste simplifié pour créer un cluster AKS géré via CAPI :

---
apiVersion: cluster.x-k8s.io/v1beta1
kind: Cluster
metadata:
  name: demo-cluster
  namespace: default
spec:
  clusterNetwork:
    pods:
      cidrBlocks: ["192.168.0.0/16"]
  infrastructureRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: AzureCluster
    name: demo-cluster
  controlPlaneRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: AzureManagedControlPlane
    name: demo-control-plane

---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: AzureCluster
metadata:
  name: demo-cluster
spec:
  location: westeurope
  resourceGroup: demo-cluster-rg
  subscriptionID: <YOUR_SUB_ID>
  identityRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: AzureClusterIdentity
    name: capi-identity
  networkSpec:
    vnet:
      name: demo-cluster-vnet
      cidrBlock: "10.0.0.0/8"

---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: AzureManagedControlPlane
metadata:
  name: demo-control-plane
spec:
  location: westeurope
  subscriptionID: <YOUR_SUB_ID>
  resourceGroup: demo-cluster-rg
  version: v1.29.2
  identityRef:
    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
    kind: AzureClusterIdentity
    name: capi-identity

---
apiVersion: cluster.x-k8s.io/v1beta1
kind: MachinePool
metadata:
  name: demo-workers
spec:
  clusterName: demo-cluster
  replicas: 3
  template:
    spec:
      clusterName: demo-cluster
      infrastructureRef:
        apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
        kind: AzureManagedMachinePool
        name: demo-workers

---
apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
kind: AzureManagedMachinePool
metadata:
  name: demo-workers
spec:
  mode: User
  vmSize: Standard_D2s_v3

Que se passe-t-il ?

• AzureCluster et AzureManagedControlPlane déclarent un AKS géré sur Azure.
• AzureManagedMachinePoolcrée un pool de nœuds (workers) géré.
• CAPZ communique avec Azure pour créer l’AKS, les ressources réseau et les pools de nœuds.
• En quelques minutes, vous avez un cluster AKS fonctionnel, déclaré en YAML.

Étape 4 : Appliquer et Vérifier

# Appliquer le manifest
kubectl apply -f cluster-aks.yaml

# Vérifier l'état du cluster
kubectl get clusters
kubectl describe cluster demo-cluster

# Vérifier les machine pools
kubectl get machinepools
kubectl describe machinepool demo-workers

# Une fois prêt, récupérer la kubeconfig
clusterctl get kubeconfig demo-cluster > kubeconfig.yaml
kubectl --kubeconfig=kubeconfig.yaml get nodes

Étape 5 : Mise à l’échelle et mise à niveau

Mise à l’échelle :

spec:
  replicas: 5  # Augmenter de 3 à 5 workers

Mise à niveau de Kubernetes :

spec:
  version: v1.30.0  # Augmenter la version

CAPZ orchestre l’upgrade de manière contrôlée.

La réalité opérationnelle : ce qui marche, ce qui ralentit

Les vrais temps

• Création du cluster AKS : 5-10 minutes (Azure crée l’AKS géré + pools de nœuds).
• Destruction : 3-5 minutes (dévision des ressources).

Ces temps sont prévisibles et fiables, contrairement aux méthodes manuelles.

Piège réels à éviter

1. Quotas Azure : Vérifiez vos limites de vCPU, IP publiques par région. Créer plusieurs clusters peut atteindre rapidement les quotas.
2. Gestion des secrets : Les identifiants Azure pour CAPI doivent être sécurisés. Utilisez Workload Identity ou un secret géré, pas du texte clair.
3. Lifecycle des nœuds : CAPI recréera automatiquement un nœud qui tombe. L’application doit gérer les perturbations (anti-affinité, sondes de préparation, arrêt progressif).
4. Cleanup oublié : Un cluster détruit via CAPI supprime les objets Kubernetes, mais pas nécessairement les ressources Azure orphelines (snapshots, disques non attachés). Vérifiez les groupes de ressources.
5. Versions Kubernetes : Assurez-vous que la version que vous déclarez est supportée par le fournisseur Azure.

Points positifs validés

✅ Reproductibilité garantie : plusieurs clusters créés avec le même YAML sont vraiment identiques.

✅ Zéro dérive : CAPI recalibré en continu. Si une VM meurt, elle est recréée.

✅ Mise à l’échelle facile : changeur → mise à l’échelle orchestré. replicas: 5

✅ Upgrade contrôlé : changer → Rolling Upgrade Orchestré. version: v1.30.0

✅ Coûts prévus : payer juste les ressources créées.

✅ Control plane géré : avec AKS, Azure gère les patchs et la HA.

Le regard critique : quand CAPI est pertinent, quand ce n’est pas

CAPI fait sens si :

• Vous créez régulièrement de nouveaux clusters (multi-environnement, multi-tenant, clusters éphémères par MR).
• Vous avez plusieurs équipes qui doivent créer des clusters et vous voulez standardiser et éviter les erreurs.
• Vous visez du multi-cloud et voulez une approche unifiée.
• Votre cluster de gestion est déjà stable (c’est un pré-requis non trivial).
• Vous êtes prêt à investir dans l’outillage GitOps (ArgoCD, Flux, etc.).

CAPI est overkill si :

• Vous avez 1-2 clusters stables créés une fois, jamais recréés.
• Votre équipe est très petite et les manuels de scripts suffisent.
• Votre fournisseur cloud propose déjà une API puissante pour créer des clusters en one-shot (ex : Terraform pour AKS managé). Dans ce cas, Terraform peut être suffisant.

La vraie limite

CAPI excelle à automatiser l’orchestration , pas à abstraire la complexité du cloud. Vous devez toujours comprendre les réseaux, les identités Azure, les versions Kubernetes, les politiques de sécurité, etc. Ce n’est pas une « abstraction magique » : c’est une standardisation d’une complexité existante.

Intégration avec GitOps et Platform Engineering

Le flux complet

1. L’équipe plateforme définit des templates CAPI de clusters (Helm charts ou Kustomize).
2. L’équipe de développement ouvre une MR → webhook déclenché la création du cluster éphémère via CAPI.
3. ArgoCD (pointant sur le cluster de gestion) voit le cluster créé et déploie automatiquement l’application.
4. Dev teste, fait la review.
5. MR fermée → webhook déclenché suppression du cluster → ArgoCD nettoyer, CAPI déprovisionne.

C’est un vrai self-service sécurisé : les développeurs n’ont pas accès à Azure CLI ni à kubectl directement. Tout passe par Git et CI/CD.

Bonnes pratiques

• Versionnez les templates CAPI : gardez l’historique des modifications, auditabilité.
• Utilisez des namespaces : un namespace par « tenant » ou par « projet » pour isoler les ressources.
• Définissez des quotas : limiter le nombre de clusters par MR, la durée de vie (TTL), les ressources par cluster.
• Mettez en place une politique de nettoyage : détruire les clusters qui traînent au-delà d’un certain temps.
• Surveiller les coûts : tagguer les ressources Azure par cluster CAPI pour une traçabilité budgétaire.

Conclusion

ClusterAPI change le jeu opérationnel , mais c’est un changement de processus et d’outillage , pas une baguette magique.

Pour les équipes prêtes à investir dans l’automatisation, CAPI apporte une valeur énorme :

• Fiabilité : clusters reproductibles, zéro dérive.
• Rapidité : création/destruction en quelques minutes.
• Coûts maîtrisés : payer juste ce qu’on consomme.
• Auditabilité : chaque action vient d’un commit Git.
• Scalabilité organisationnelle : les plateformes peuvent standardiser sans friction.

Mais il faut aussi être honnête : CAPI ajoute de la complexité opérationnelle. Vous devez maintenir un management cluster stable, comprendre les fournisseurs cloud, maîtriser Kubernetes, GitOps, et CI/CD. Ce n’est pas pour les petites équipes ou les clusters « une fois et oublier ».

Pour les organisations qui créent régulièrement des clusters ou qui souhaitent du multi-cloud standardisé, CAPI n’est plus une expérience. C’est une nécessité.