Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 2: CNI verstehen und installieren

Ziel: Du weißt, wie containerd das CNI-Plugin findet und aufruft, rufst ein Plugin von Hand auf und änderst Ciliums Konfiguration per Helm – inklusive Rollback. · Dauer: ca. 70 min · Voraussetzung: Tag 1

Briefing

  • CKNE: Core Infrastructure and CNI (15 %) – „Installing and Configuring CNI Plugins“.
  • CNI (Container Network Interface) ist ein schlanker Vertrag: Die Runtime ruft ein Programm aus /opt/cni/bin auf, gibt ihm per Umgebungsvariablen den Befehl (ADD, DEL, CHECK, VERSION) und per stdin eine JSON-Konfiguration aus /etc/cni/net.d. Das Plugin antwortet mit JSON: Interfaces, IPs, Routen.
  • Das kubelet kennt CNI seit v1.24 nicht mehr – nur die Runtime (containerd).
  • Cilium installiert Binary und Konfiguration selbst und verwaltet sie per Helm.
kubelet ──CRI──> containerd ──liest──> /etc/cni/net.d/05-cilium.conflist
                     │
                     └──exec──> /opt/cni/bin/cilium-cni ──API──> cilium-agent

Drill 1: Konfiguration und Binaries auf dem Node

mkdir -p ~/ckne/tag02 && cd ~/ckne/tag02
sudo ls -la /etc/cni/net.d
sudo cat /etc/cni/net.d/05-cilium.conflist
ls /opt/cni/bin
k -n kube-system get ds cilium \
  -o jsonpath='{.spec.template.spec.initContainers[*].name}'
echo

Erwartet (gekürzt):

drwx------ 2 root root 4096 Nov 18 22:40 .
-rw-r--r-- 1 root root    0 Apr 24  2026 .kubernetes-cni-keep
-rw------- 1 root root  191 Nov 18 22:40 05-cilium.conflist
{
  "cniVersion": "1.0.0",
  "name": "cilium",
  "plugins": [
    {
       "type": "cilium-cni",
       "enable-debug": false,
       "log-file": "/var/run/cilium/cilium-cni.log"
    }
  ]
}
LICENSE  README.md  bandwidth  bridge  cilium-cni  dhcp  dummy  firewall  host-device
host-local  ipvlan  loopback  macvlan  portmap  ptp  sbr  static  tap  tuning  vlan  vrf
config mount-cgroup apply-sysctl-overwrites mount-bpf-fs clean-cilium-state
install-cni-binaries

Eine .conflist ist eine Plugin-Kette (plugins: [...]), die der Reihe nach läuft; hier steht nur cilium-cni. type ist der Dateiname des Binaries in /opt/cni/bin. Die Standard-Plugins (bridge, macvlan, host-local …) stammen aus dem Paket kubernetes-cni (Tag 0), cilium-cni legt der Init-Container install-cni-binaries ab. Die Konfiguration schreibt der Agent erst, wenn er bereit ist (write-cni-conf-when-ready) – bis dahin bleibt der Node NotReady. Nur falls podman installiert ist, liegt hier zusätzlich 87-podman-bridge.conflist.cilium_bak: Cilium hat die fremde Konfiguration umbenannt (Drill 5).

Fortschritt speichern? Kostenlos registrieren

Drill 2: Wer liest die Konfiguration?

sudo grep -A4 "cri.v1.runtime'.cni]" /etc/containerd/config.toml
sudo crictl info | jq '.cniconfig | {PluginConfDir, PluginDirs, PluginMaxConfNum}'
sudo crictl info | jq -r '.cniconfig.Networks[].Config.Name'
sudo cat /var/lib/kubelet/kubeadm-flags.env

Erwartet:

    [plugins.'io.containerd.cri.v1.runtime'.cni]
      bin_dirs = ['/opt/cni/bin']
      conf_dir = '/etc/cni/net.d'
      max_conf_num = 1
      setup_serially = false
{
  "PluginConfDir": "/etc/cni/net.d",
  "PluginDirs": [
    "/opt/cni/bin"
  ],
  "PluginMaxConfNum": 1
}
cni-loopback
cilium
KUBELET_KUBEADM_ARGS=""

containerd lädt aus conf_dir die lexikografisch erste gültige Datei (max_conf_num = 1) – deshalb das Präfix 05-. Dazu kommt immer ein internes Loopback-Netz für lo. Das kubelet hat keine CNI-Flags mehr; früher übliche Optionen wie --network-plugin oder --cni-conf-dir gibt es nicht. Wer ein CNI-Problem sucht, schaut also in containerd und in /etc/cni/net.d, nicht ins kubelet.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Ein CNI-Plugin von Hand aufrufen

Genau so ruft containerd ein Plugin auf – hier das Standard-Plugin bridge in einem eigenen Network Namespace, ohne Kubernetes:

cat > tag02-bridge.conf <<'EOF'
{
  "cniVersion": "1.0.0",
  "name": "tag02-net",
  "type": "bridge",
  "bridge": "tag02br0",
  "isGateway": true,
  "ipam": {
    "type": "host-local",
    "subnet": "192.168.250.0/24",
    "dataDir": "/run/tag02-ipam"
  }
}
EOF
sudo ip netns add tag02
sudo CNI_COMMAND=ADD CNI_CONTAINERID=tag02demo CNI_NETNS=/var/run/netns/tag02 \
  CNI_IFNAME=eth0 CNI_PATH=/opt/cni/bin /opt/cni/bin/bridge < tag02-bridge.conf
sudo ip netns exec tag02 ip -br addr
ping -c1 -W1 192.168.250.2 | tail -2

Erwartet (gekürzt):

{
    "cniVersion": "1.0.0",
    "interfaces": [
        { "mac": "5e:9a:6a:e9:52:59", "name": "tag02br0" },
        { "mac": "56:ca:c6:02:eb:43", "name": "veth0ffc1d46" },
        { "mac": "9e:7e:e8:ed:ca:96", "name": "eth0",
          "sandbox": "/var/run/netns/tag02" }
    ],
    "ips": [
        { "address": "192.168.250.2/24", "gateway": "192.168.250.1", "interface": 2 }
    ]
}
lo               DOWN
eth0@if15        UP             192.168.250.2/24 fe80::9c7e:e8ff:feed:ca96/64
1 packets transmitted, 1 received, 0% packet loss, time 0ms

Das Haupt-Plugin bridge hat Bridge und veth-Paar gebaut und das IPAM-Plugin host-local (über CNI_PATH gefunden) nach einer Adresse gefragt. Welche Spec-Versionen ein Plugin spricht, verrät VERSION; danach räumst du mit DEL auf:

sudo CNI_COMMAND=VERSION /opt/cni/bin/cilium-cni < /dev/null; echo
sudo CNI_COMMAND=DEL CNI_CONTAINERID=tag02demo CNI_NETNS=/var/run/netns/tag02 \
  CNI_IFNAME=eth0 CNI_PATH=/opt/cni/bin /opt/cni/bin/bridge < tag02-bridge.conf
sudo ip netns exec tag02 ip -br addr
sudo ip netns del tag02 && sudo ip link del tag02br0 && sudo rm -rf /run/tag02-ipam

Erwartet:

{"cniVersion":"1.1.0","supportedVersions":["0.1.0","0.2.0","0.3.0","0.3.1","0.4.0",
"1.0.0","1.1.0"]}
lo               DOWN

DEL hat eth0 entfernt und die IP freigegeben. CHECK verlangt zusätzlich das vorige Ergebnis (prevResult) in der Konfiguration – das liefert sonst die Runtime.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Node ohne CNI-Konfiguration

Was passiert, wenn die Konfiguration fehlt? Auf worker2:

ssh [email protected]
sudo rm /etc/cni/net.d/05-cilium.conflist
sudo ls -la /etc/cni/net.d
sudo journalctl -u containerd --since -1min | grep -m1 'reload cni'
exit
CP=$(k -n kube-system get pod -l k8s-app=cilium \
  --field-selector spec.nodeName=worker2 -o name)
k -n kube-system logs $CP -c cilium-agent --since=2m | grep -E 'Wrote CNI'

Erwartet (gekürzt):

-rw-r--r-- 1 root root    0 Apr 24  2026 .kubernetes-cni-keep
-rw------- 1 root root  191 Nov 18 23:41 05-cilium.conflist
... level=error msg="failed to reload cni configuration after receiving fs change event
(RENAME \"/etc/cni/net.d/05-cilium.conflist\")" error="cni config load failed: no
network config found in /etc/cni/net.d: cni plugin not initialized ..."
... level=info msg="Wrote CNI configuration file" module=agent.infra.cni-config
destination=/host/etc/cni/net.d/05-cilium.conflist

Die Datei ist sofort wieder da: Der Agent beobachtet das Verzeichnis und schreibt sie neu (neuer Zeitstempel). containerd hat den Verlust aber bemerkt. Läuft gerade kein Agent (Neustart, CrashLoop), bleibt die Datei weg, und das kubelet meldet den Node nach wenigen Sekunden als NotReady:

kubelet.go:3343] "Container runtime network not ready" networkReady="NetworkReady=false
reason:NetworkPluginNotReady message:Network plugin returns error: cni plugin not
initialized"

Neue Pods auf dem Node bleiben dann in ContainerCreating; laufende Pods behalten ihr Netz. Abhilfe: den Agenten reparieren (k -n kube-system logs/describe des cilium-Pods), nicht die Datei von Hand zurückkopieren.

Achtung: Diesen Drill nur auf einem Node mit gesundem Agenten machen und vorher k -n kube-system get pods -l k8s-app=cilium -o wide prüfen.

Fortschritt speichern? Kostenlos registrieren

Drill 5: cni.exclusive – Cilium duldet keine fremde Konfiguration

scp tag02-bridge.conf [email protected]:/tmp/
ssh [email protected]
sudo cp /tmp/tag02-bridge.conf /etc/cni/net.d/00-tag02.conf
sleep 2; sudo ls /etc/cni/net.d
sudo rm /etc/cni/net.d/00-tag02.conf.cilium_bak /tmp/tag02-bridge.conf
exit
cilium config view | grep cni-exclusive
CP=$(k -n kube-system get pod -l k8s-app=cilium \
  --field-selector spec.nodeName=worker1 -o name)
k -n kube-system logs $CP -c cilium-agent --since=2m | grep Renaming

Erwartet (gekürzt):

00-tag02.conf.cilium_bak  05-cilium.conflist
cni-exclusive                                     true
... level=info msg="Renaming non-Cilium CNI configuration file"
module=agent.infra.cni-config source=00-tag02.conf destination=00-tag02.conf.cilium_bak

00- wäre vor 05- gelandet – containerd hätte neue Pods mit bridge statt Cilium verdrahtet. Mit cni.exclusive=true (Standard) benennt der Agent jede fremde Datei in *.cilium_bak um. Das schützt vor Resten alter CNIs, verhindert aber auch Meta-Plugins wie Multus – dafür muss cni.exclusive=false gesetzt werden (Tag 5).

Andere CNIs arbeiten nach demselben Muster, nur mit anderer Datei und Technik:

CNI Konfig in /etc/cni/net.d Datenpfad Policies
Cilium 05-cilium.conflist eBPF, VXLAN/Geneve/nativ K8s, L3–L7, FQDN
Calico 10-calico.conflist iptables/nftables oder eBPF, BGP K8s + eigene CRDs
Flannel 10-flannel.conflist VXLAN/host-gw (bridge) keine

Flannel lässt sich mit Cilium kombinieren (cni.chainingMode) – Cilium übernimmt dann nur Policies und Sichtbarkeit, Flannel das Routing.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Helm-Werte lesen

helm list -n kube-system
REV=$(helm history cilium -n kube-system -o json | jq '.[-1].revision')
echo $REV
helm get values cilium -n kube-system -o yaml > values-vorher.yaml
cat values-vorher.yaml
helm get values cilium -n kube-system --all | grep -A13 '^cni:'
cilium config view | grep -E '^cni-|write-cni'
k -n kube-system get cm cilium-config -o jsonpath='{.data.cni-exclusive}'; echo

Erwartet (gekürzt; Revision beim Durcharbeiten ab Tag 0, Werte anderer Tage können hinzukommen):

NAME    NAMESPACE    REVISION  ...  STATUS    CHART          APP VERSION
cilium  kube-system  1         ...  deployed  cilium-1.20.5  1.20.5
1
hubble:
  enabled: true
  relay:
    enabled: true
ipam:
  mode: cluster-pool
...
cni:
  binPath: /opt/cni/bin
  confPath: /etc/cni/net.d
  customConf: false
  exclusive: true
  install: true
  logFile: /var/run/cilium/cilium-cni.log
...
cni-exclusive                                     true
cni-log-file                                      /var/run/cilium/cilium-cni.log
write-cni-conf-when-ready                         /host/etc/cni/net.d/05-cilium.conflist
true

Drei Ebenen: helm get values zeigt nur, was du gesetzt hast (--all auch die Chart-Defaults), daraus rendert Helm die ConfigMap cilium-config, und cilium config view liest genau diese ConfigMap. Die Sicherung values-vorher.yaml brauchst du am Ende des Tages, die aktuelle Revision in $REV für den Rollback in Drill 8.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Werte ändern – cilium config set gegen helm upgrade

Beispiel: Debug-Logging des Agenten. Erst der schnelle Weg über die cilium CLI:

cilium config set debug true --restart=false
k -n kube-system get cm cilium-config -o jsonpath='{.data.debug}'; echo
helm get values cilium -n kube-system | grep -c debug

Erwartet (Symbole am Zeilenanfang weggelassen):

Patching ConfigMap cilium-config with debug=true...
Restart Cilium pods for configmap changes to take effect
true
0

Die ConfigMap sagt true, Helm weiß davon nichts – Drift. Der saubere Weg ist der Helm-Wert, der Chart-Schlüssel heißt debug.enabled:

helm upgrade cilium cilium/cilium -n kube-system --version 1.20.5 \
  --reuse-values --set debug.enabled=true
helm get values cilium -n kube-system | grep -A1 '^debug'
k -n kube-system get pods -l k8s-app=cilium

Erwartet (gekürzt):

Release "cilium" has been upgraded. Happy Helming!
REVISION: 2
debug:
  enabled: true
NAME           READY   STATUS    RESTARTS   AGE
cilium-b9sn5   1/1     Running   0          5m16s
cilium-mwscd   1/1     Running   0          5m17s
cilium-xfv79   1/1     Running   0          5m4s

--reuse-values übernimmt alle bisherigen Werte – ohne den Schalter setzt Helm alles andere auf Chart-Defaults zurück (Tunnel weg, IPAM anders: Cluster kaputt). Die Pods sind aber alt: Eine geänderte ConfigMap startet die Agenten nicht neu (rollOutCiliumPods: false). Also selbst neu starten:

k -n kube-system rollout restart ds/cilium
k -n kube-system rollout status ds/cilium
cilium status --wait | grep -E 'Cilium:'
k -n kube-system logs ds/cilium -c cilium-agent --since=60s | grep -c level=debug

Erwartet (gekürzt):

daemonset.apps/cilium restarted
daemon set "cilium" successfully rolled out
 /¯¯\__/¯¯\    Cilium:             OK
3507

Fortschritt speichern? Kostenlos registrieren

Drill 8: Rollback

helm history cilium -n kube-system
helm rollback cilium $REV -n kube-system

Erwartet (gekürzt):

REVISION  UPDATED  STATUS      CHART          ...  DESCRIPTION
1         ...      superseded  cilium-1.20.5  ...  Install complete
2         ...      deployed    cilium-1.20.5  ...  Upgrade complete
Error: conflict occurred while applying object kube-system/cilium-config /v1,
Kind=ConfigMap: Apply failed with 1 conflict: conflict with "cilium" using v1:
.data.debug

Nimm die Revision vor deiner Änderung ($REV aus Drill 6, hier 1). Der Rollback scheitert an der Drift aus Drill 7: Helm 4 schreibt per Server-Side Apply, und das Feld .data.debug gehört auch dem Field Manager cilium (die CLI). Das Upgrade lief noch durch, weil beide denselben Wert wollten; der Rollback will ihn ändern – Konflikt. Die Besitzer zeigt:

k -n kube-system get cm cilium-config --show-managed-fields -o yaml \
  | grep -E '^  - apiVersion|manager:|operation:'

Erwartet (gekürzt):

  - apiVersion: v1
    manager: helm
    operation: Apply
  - apiVersion: v1
    manager: cilium
    operation: Update

Helm soll gewinnen, also den Konflikt erzwingen, neu starten und gegen die Sicherung vergleichen:

helm rollback cilium $REV -n kube-system --force-conflicts
cilium config view | grep -w '^debug'
k -n kube-system rollout restart ds/cilium
k -n kube-system rollout status ds/cilium
cilium status --wait | grep -E 'Cilium:|Operator:'
diff values-vorher.yaml <(helm get values cilium -n kube-system -o yaml) && echo GLEICH

Erwartet (gekürzt):

Rollback was a success! Happy Helming!
debug                                             false
daemon set "cilium" successfully rolled out
 /¯¯\__/¯¯\    Cilium:             OK
 \__/¯¯\__/    Operator:           OK
GLEICH

Ein Rollback legt eine neue Revision an („Rollback to 1“), er löscht keine. Der gescheiterte Versuch steht als failed in der Historie. Lehre: Im Helm-Cluster cilium config set nur zum Ausprobieren – dauerhafte Änderungen gehören in die Werte.

Fortschritt speichern? Kostenlos registrieren

Übung: Speed-Drills

  1. Zeige auf worker1, welche CNI-Netze containerd geladen hat. Zeitziel: 45 s
  2. Zeige, mit welchen Werten Cilium ursprünglich installiert wurde (Revision 1). Zeitziel: 30 s
  3. Zeige die Pfade, unter denen Cilium Konfiguration und Binary ablegt (Helm-Werte). Zeitziel: 45 s
  4. Lege in tag02 einen Pod web (nginx:1.29) auf worker1 an und zeige seine IP. Zeitziel: 45 s

Lösung

ssh [email protected] "sudo crictl info | jq -r '.cniconfig.Networks[].Config.Name'"
helm get values cilium -n kube-system --revision 1
helm get values cilium -n kube-system --all | grep -E '^  (binPath|confPath):'
k create ns tag02
k -n tag02 run web --image=nginx:1.29 --overrides='{"spec":{"nodeName":"worker1"}}'
k -n tag02 get pod web -o wide

Erwartet (gekürzt):

cni-loopback
cilium
USER-SUPPLIED VALUES:
hubble:
  enabled: true
...
  binPath: /opt/cni/bin
  confPath: /etc/cni/net.d
namespace/tag02 created
pod/web created
NAME   READY   STATUS    RESTARTS   AGE   IP           NODE
web    1/1     Running   0          26s   10.0.1.196   worker1

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

k get nodes

Erwartet: alle drei Nodes Ready.

ssh [email protected] sudo ls /etc/cni/net.d

Erwartet: nur 05-cilium.conflist – kein 00-tag02.conf* mehr.

diff values-vorher.yaml <(helm get values cilium -n kube-system -o yaml) && echo GLEICH

Erwartet: GLEICH (kein debug mehr in den Werten).

cilium config view | grep -w '^debug'

Erwartet: debug false

ip -br link | grep -c tag02

Erwartet: 0 – Bridge und Namespace aus Drill 3 sind weg.

Challenge

Zeige auf worker1 ohne kubectl, welches Ergebnis cilium-cni für den Pod web an containerd zurückgegeben hat (IP, Gateway, Routen), und prüfe es im Network Namespace des Pods.

Hinweis: crictl inspectp enthält das CNI-Ergebnis unter .info.cniResult.

Lösung

ssh [email protected]
P=$(sudo crictl pods --name web --namespace tag02 -q)
sudo crictl inspectp $P | jq -c '.info.cniResult.Interfaces.eth0.IPConfigs'
sudo crictl inspectp $P | jq -c '.info.cniResult.Routes'
NS=$(sudo crictl inspectp $P | jq -r '.info.cniResult.Interfaces.eth0.Sandbox')
sudo nsenter --net=$NS ip -br addr show eth0
sudo nsenter --net=$NS ip route
ip -br addr show cilium_host
exit

Erwartet:

[{"Gateway":"10.0.1.116","IP":"10.0.1.196"}]
[{"dst":"10.0.1.116/32"},{"dst":"0.0.0.0/0","gw":"10.0.1.116","mtu":1450}]
eth0@if105       UP             10.0.1.196/32 fe80::30b3:d1ff:fe92:a91b/64
default via 10.0.1.116 dev eth0 mtu 1450
10.0.1.116 dev eth0 scope link
cilium_host@cilium_net UP             10.0.1.116/32 fe80::e8f2:3fff:fe4a:8c5a/64

Cilium vergibt eine /32 und setzt cilium_host als Gateway; die MTU 1450 berücksichtigt den VXLAN-Overhead (Tag 4). Alles, was im Pod-Netz steht, kam aus dem CNI-Ergebnis.

Fortschritt speichern? Kostenlos registrieren

Aufräumen

k delete namespace tag02

Die Cilium-Werte sind seit Drill 8 wieder auf dem Stand von values-vorher.yaml.

Prüfungstipp

  • Erst helm get values sichern, dann helm upgrade --reuse-values --set …; ohne --reuse-values setzt Helm alle Werte zurück. Danach rollout restart ds/cilium.
  • Node NotReady mit „cni plugin not initialized“: /etc/cni/net.d (mit sudo, das Verzeichnis ist drwx------), /opt/cni/bin und den CNI-Agent-Pod prüfen.
  • Doku-Stellen: kubernetes.io „Network Plugins“, docs.cilium.io „Installation using Helm“ und „Upgrade Guide“, CNI-Spezifikation auf github.com/containernetworking/cni.

Enterprise-Notiz

  • Werte gehören in eine versionierte values.yaml (GitOps), nicht in --set-Ketten; cilium config set erzeugt Drift, die Helm 4 als SSA-Konflikt meldet.
  • Upgrades nach Ciliums Upgrade Guide: Pre-Flight-Check, eine Minor-Version pro Schritt, upgradeCompatibility für alte Defaults.
  • rollOutCiliumPods=true startet Agenten bei jeder Werteänderung automatisch neu – bequem, aber jeder Neustart ist ein kurzer Eingriff in den Datenpfad.
  • cni.exclusive=false nur, wenn ein Meta-Plugin (Multus) gebraucht wird; sonst schützt die Exklusivität vor Resten alter CNIs nach einer Migration.
  • Node-Images ohne Fremd-CNI-Dateien bauen (podman, Docker legen eigene an).