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/binauf, 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}'
echoErwartet (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.envErwartet:
[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 -2Erwartet (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-ipamErwartet:
{"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 wideprü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 RenamingErwartet (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}'; echoErwartet (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 debugErwartet (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=ciliumErwartet (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=debugErwartet (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-systemErwartet (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 GLEICHErwartet (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
- Zeige auf
worker1, welche CNI-Netze containerd geladen hat. Zeitziel: 45 s - Zeige, mit welchen Werten Cilium ursprünglich installiert wurde (Revision 1). Zeitziel: 30 s
- Zeige die Pfade, unter denen Cilium Konfiguration und Binary ablegt (Helm-Werte). Zeitziel: 45 s
- Lege in
tag02einen Podweb(nginx:1.29) aufworker1an 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 wideErwartet (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 nodesErwartet: alle drei Nodes Ready.
ssh [email protected] sudo ls /etc/cni/net.dErwartet: nur 05-cilium.conflist – kein
00-tag02.conf* mehr.
diff values-vorher.yaml <(helm get values cilium -n kube-system -o yaml) && echo GLEICHErwartet: GLEICH (kein
debug mehr in den Werten).
cilium config view | grep -w '^debug'Erwartet: debug false
ip -br link | grep -c tag02Erwartet: 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
exitErwartet:
[{"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 tag02Die Cilium-Werte sind seit Drill 8 wieder auf dem Stand von
values-vorher.yaml.
Prüfungstipp
- Erst
helm get valuessichern, dannhelm upgrade --reuse-values --set …; ohne--reuse-valuessetzt Helm alle Werte zurück. Danachrollout restart ds/cilium. - Node
NotReadymit „cni plugin not initialized“:/etc/cni/net.d(mitsudo, das Verzeichnis istdrwx------),/opt/cni/binund 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 seterzeugt Drift, die Helm 4 als SSA-Konflikt meldet. - Upgrades nach Ciliums Upgrade Guide: Pre-Flight-Check, eine
Minor-Version pro Schritt,
upgradeCompatibilityfür alte Defaults. rollOutCiliumPods=truestartet Agenten bei jeder Werteänderung automatisch neu – bequem, aber jeder Neustart ist ein kurzer Eingriff in den Datenpfad.cni.exclusive=falsenur, 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).