La plupart des add-ons Kubernetes s’installent dans un cluster déjà fonctionnel. Cilium est différent : en tant que CNI, il est le réseau du cluster, ce qui signifie qu’un cluster doit être créé sans CNI par défaut occupant déjà ce rôle, faute de quoi Cilium n’a rien à reprendre. Ce guide couvre cet enchaînement, avec un cluster local kind, puis l’installation de Cilium avec Helm.

Pourquoi l’ordre compte ici

Un cluster Kubernetes démarre normalement avec un CNI déjà installé qui gère le réseau des Pods : kindnet sur kind, ou le CNI par défaut d’un fournisseur cloud. Si Cilium est installé par-dessus un CNI déjà actif, vous vous retrouvez avec deux plugins réseau qui tentent de remplir le même rôle, ce qui ne fonctionne pas. Cilium doit être le seul CNI, ce qui implique de désactiver le CNI par défaut qui occuperait sinon ce rôle avant l’installation de Cilium, et non après.

Créer un cluster avec le CNI par défaut désactivé

Sur kind, c’est un paramètre de configuration du cluster, pas quelque chose que l’on désactive après coup :

# kind-config.yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
  disableDefaultCNI: true
nodes:
  - role: control-plane
    extraPortMappings:
      - containerPort: 30080
        hostPort: 80
      - containerPort: 30443
        hostPort: 443
  - role: worker

kind create cluster --config kind-config.yaml
kubectl get nodes

Attendez-vous à voir tous les nœuds en NotReady. C’est normal, pas un échec : sans CNI installé, les nœuds ne peuvent pas être marqués comme prêts. Les extraPortMappings ne sont pas nécessaires pour une installation de base ; ils sont préparés à l’avance pour les guides suivants de cette série, qui exposent des services en externe via kind, lequel n’a pas de répartiteur de charge cloud pour fournir des adresses routables par lui-même.

Si vous utilisez un service Kubernetes managé dans le cloud plutôt qu’un cluster local, consultez la documentation de ce fournisseur pour savoir comment créer un cluster sans son CNI par défaut ; le mécanisme diffère selon le fournisseur, mais l’exigence sous-jacente, aucun CNI n’occupant le rôle avant l’installation de Cilium, est la même partout.

Installer les CRD Gateway API avant Cilium, si vous comptez les utiliser

Si vous prévoyez d’utiliser Kubernetes Gateway API avec Cilium (traité dans le guide suivant), installez dès maintenant ses CustomResourceDefinitions, avant d’activer la prise en charge de Gateway API dans l’installation de Cilium. Le contrôleur Gateway API de Cilium s’attend à ce que ces CRD (GatewayClass, Gateway, HTTPRoute et les types associés) existent déjà dans le cluster :

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.1/standard-install.yaml

Fixez une version précise de Gateway API plutôt que de toujours récupérer la plus récente. Gateway API évolue plus vite que ne peut le suivre chaque implémentation, et les notes de version de Cilium précisent avec quelle version de Gateway API une version donnée de Cilium a réellement été testée ; utiliser des CRD plus récentes que ce que Cilium prend en charge est une source réaliste d’erreurs déroutantes qui n’ont rien à voir avec votre propre configuration.

Installer Cilium avec Helm

helm repo add cilium https://helm.cilium.io
helm repo update
helm show values cilium/cilium --version 1.19.0 > cilium-values.yaml

Passer en revue le fichier de valeurs par défaut complet avant d’installer vaut les quelques minutes nécessaires ; il est long, mais c’est la liste de référence de tout ce qui est configurable. Pour un cluster où vous utiliserez aussi Gateway API, voici les paramètres les plus importants :

# cilium-values.yaml (extrait pertinent)
kubeProxyReplacement: true

gatewayAPI:
  enabled: true
  gatewayClass:
    create: false   # créez vous-même votre GatewayClass explicitement, voir le guide suivant

hubble:
  enabled: true
  relay:
    enabled: true
  ui:
    enabled: true

kubeProxyReplacement: true fait prendre en charge entièrement le routage des Services par Cilium, en eBPF, comme présenté dans le guide précédent, plutôt que de fonctionner à côté de kube-proxy. Mettre gatewayClass.create à false est un choix délibéré, pas une valeur par défaut à conserver : cela signifie que vous créez et possédez vous-même la ressource GatewayClass (utile si vous la gérez via un outil GitOps comme Argo CD ou Flux, afin qu’elle soit suivie comme le reste de votre configuration) plutôt que de laisser le chart Helm en créer une implicitement. Activer Hubble et son interface ici vous donne les outils d’observabilité auxquels cette série fait référence, même s’ils ne sont pas indispensables au fonctionnement de Gateway API ou de BGP.

helm install cilium cilium/cilium \
  --version 1.19.0 \
  --namespace kube-system \
  -f cilium-values.yaml

Confirmer l’installation

kubectl get pods -n kube-system -l k8s-app=cilium
kubectl get nodes

Les Pods de Cilium doivent atteindre l’état Running, et une fois que c’est le cas, les nœuds qui étaient NotReady juste après la création du cluster doivent passer à Ready. Rien d’autre n’a besoin de se produire pour cette transition ; c’est l’agent Cilium qui démarre sur chaque nœud qui la débloque.

Ce que vous pouvez modifier sans risque plus tard

kubeProxyReplacement et le choix du CNI installé sont le genre de paramètres qu’il vaut mieux bien régler dès l’installation ; les modifier sur un cluster en production est perturbateur et ne doit pas se faire à la légère. La plupart des autres valeurs (limites de ressources, fonctionnalités activées, configuration de Hubble) peuvent être ajustées plus tard avec helm upgrade sur le même fichier de valeurs, sans le même niveau de précaution.