Die meisten Kubernetes-Add-ons werden in einen bereits funktionierenden Cluster installiert. Cilium ist anders: Als CNI ist es das Netzwerk des Clusters. Der Cluster muss also ohne ein Standard-CNI erstellt werden, das diese Rolle schon belegt, sonst hat Cilium nichts zu übernehmen. Diese Anleitung behandelt diese Reihenfolge anhand eines lokalen kind-Clusters und installiert danach Cilium mit Helm.

Warum die Reihenfolge hier zählt

Ein Kubernetes-Cluster startet normalerweise mit einem bereits installierten CNI, das das Pod-Netzwerk verwaltet: kindnet bei kind oder der Standard eines Cloud-Anbieters. Wird Cilium auf einem bereits aktiven CNI installiert, versuchen zwei Netzwerk-Plugins, dieselbe Aufgabe zu übernehmen, was nicht funktioniert. Cilium muss das einzige CNI sein. Das bedeutet, dass du jedes Standard-CNI, das die Rolle sonst beanspruchen würde, deaktivierst, bevor du Cilium installierst – nicht danach.

Einen Cluster mit deaktiviertem Standard-CNI erstellen

Bei kind ist das eine Einstellung der Cluster-Konfiguration und nichts, was du nachträglich deaktivierst:

# 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

Erwarte, dass jeder Knoten NotReady zeigt. Das ist normal und kein Fehler: Ohne installiertes CNI können Knoten nicht als bereit markiert werden. Die extraPortMappings sind für eine einfache Installation nicht erforderlich. Sie sind vorab für spätere Anleitungen dieser Reihe eingerichtet, die Services über kind extern bereitstellen – kind hat keinen Cloud-Load-Balancer, der von sich aus routbare Adressen vergibt.

Wenn du einen verwalteten Cloud-Kubernetes-Dienst statt eines lokalen Clusters nutzt, schau in die Dokumentation des Anbieters, wie man einen Cluster ohne dessen Standard-CNI erstellt. Der Mechanismus unterscheidet sich je nach Anbieter, die zugrunde liegende Anforderung – kein CNI belegt die Rolle, bevor Cilium installiert wird – ist aber überall dieselbe.

Die Gateway-API-CRDs vor Cilium installieren, falls du die Gateway API nutzen willst

Wenn du die Kubernetes Gateway API mit Cilium verwenden willst (Thema der nächsten Anleitung), installiere jetzt ihre CustomResourceDefinitions, bevor du die Gateway-API-Unterstützung in Ciliums eigener Installation aktivierst. Ciliums Gateway-API-Controller erwartet, dass diese CRDs (GatewayClass, Gateway, HTTPRoute und verwandte Typen) bereits im Cluster existieren:

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

Pinne ein bestimmtes Gateway-API-Release, statt immer das neueste zu ziehen. Die Gateway API entwickelt sich schneller, als jede Implementierung mithalten kann, und Ciliums eigene Release Notes geben an, mit welcher Gateway-API-Version ein bestimmtes Cilium-Release tatsächlich getestet wurde. Eine neuere CRD-Version, als Cilium unterstützt, ist eine realistische Quelle für verwirrende Fehler, die nichts mit deiner eigenen Konfiguration zu tun haben.

Cilium mit Helm installieren

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

Es lohnt sich, die vollständige Datei mit den Standardwerten vor der Installation durchzusehen. Sie ist lang, aber die maßgebliche Liste dessen, was konfigurierbar ist. Für einen Cluster, in dem du auch die Gateway API nutzt, sind das die wichtigsten Einstellungen:

# cilium-values.yaml (relevanter Auszug)
kubeProxyReplacement: true

gatewayAPI:
  enabled: true
  gatewayClass:
    create: false   # erstelle deine eigene GatewayClass explizit, siehe nächste Anleitung

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

kubeProxyReplacement: true lässt Cilium das Service-Routing vollständig in eBPF übernehmen, wie in der vorherigen Anleitung beschrieben, statt neben kube-proxy zu laufen. gatewayClass.create auf false zu setzen ist eine bewusste Entscheidung und kein Standard, den du beibehalten musst: Du erstellst und besitzt die GatewayClass-Ressource selbst (nützlich, wenn du sie über ein GitOps-Werkzeug wie Argo CD oder Flux verwaltest, damit sie wie der Rest deiner Konfiguration verfolgt wird), statt das Helm-Chart implizit eine anlegen zu lassen. Hubble und seine Oberfläche hier zu aktivieren, gibt dir die Observability-Werkzeuge, auf die in dieser Reihe verwiesen wird, sie sind aber nicht nötig, damit Gateway API oder BGP für sich funktionieren.

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

Die Installation bestätigen

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

Die Cilium-Pods sollten Running erreichen, und sobald das der Fall ist, sollten die Knoten, die direkt nach der Cluster-Erstellung NotReady waren, sofort auf Ready wechseln. Dafür muss nichts weiter passieren – es ist Ciliums eigener Agent, der auf jedem Knoten hochkommt und das freischaltet.

Ein Hinweis, was du später gefahrlos ändern kannst

kubeProxyReplacement und welches CNI installiert ist, sind Einstellungen, die du besser bei der Installation richtig setzt. Sie auf einem laufenden Cluster zu ändern, ist störend und nichts, womit man leichtfertig experimentieren sollte. Die meisten anderen Werte – Ressourcenlimits, welche Funktionen aktiviert sind, die Hubble-Konfiguration – lassen sich später mit helm upgrade gegen dieselbe Values-Datei anpassen, ohne diese Vorsicht.