Tag 8: RKE2-Cluster auf Proxmox bauen
Ziel: Sechs VMs per OpenTofu, darauf RKE2 HA mit Cilium (kube-proxy-Ersatz, L2) und kube-vip – erreichbar über die VIP
10.10.20.10. · Dauer: ca. 120 min · Voraussetzung: Tag 7, Proxmox VE 9.x mit ca. 18 vCPU, 36 GB RAM, 300 GB Disk
Briefing
- Proxmox liefert nur Rechenleistung: ein Cloud-Init-Template (VMID
9000), sechs Klone per OpenTofu (
bpg/proxmox). - Ansible installiert RKE2: drei Server (etcd, Control Plane, Taint
CriticalAddonsOnly), drei Agents für Workloads. - Cilium kommt als RKE2-Chart
rke2-cilium; die Werte setzt eineHelmChartConfig. kube-proxy ist aus, Cilium übernimmt (eBPF). - kube-vip hält per ARP die API-VIP
10.10.20.10. LoadBalancer-IPs für Gateways vergibt später Cilium (Tag 9). - RKE2-Ingress ist aus (
ingress-controller: none): Traefik würde seit v1.36 eigene Gateway-API-CRDs (v1.5.1) mitbringen und mit Envoy Gateway kollidieren.
Laptop: tofu + ansible + kubectl
│ API 8006 (Token tofu@pve!provider)
┌──────▼──────────────── Proxmox VE 9 · vmbr0 · 10.10.20.0/24 ────────────┐
│ 9000 ubuntu-2404-tpl ──clone──► rke2-cp-1 .11 rke2-wk-1 .21 │
│ rke2-cp-2 .12 rke2-wk-2 .22 │
│ rke2-cp-3 .13 rke2-wk-3 .23 │
│ VIP 10.10.20.10 (kube-vip, ARP) LB-Pool .100-.120 (Cilium, Tag 9) │
└─────────────────────────────────────────────────────────────────────────┘
Achtung: Proxmox, Mehrknoten-RKE2 und ARP-VIPs lassen sich nicht in kind nachstellen. Alle Ausgaben in diesem Kapitel stammen aus der offiziellen Doku bzw. statischer Validierung (
tofu validate,ansible-lint,helm template) und sind mit „(gekürzt, kann je nach Version abweichen)” markiert.
Drill 1: API-Token und Template auf dem Proxmox-Host
Der Code liegt in ~/gw-lab/code/infra-proxmox. Das
Skript pve-prep.sh läuft einmal als root auf dem
Proxmox-Host.
scp ~/gw-lab/code/infra-proxmox/pve-prep.sh [email protected]:
ssh [email protected] 'bash ~/pve-prep.sh'Kern des Skripts – Rolle mit minimalen Rechten für Klonen und Cloud-Init:
pveum role add TofuProv -privs "VM.Allocate VM.Clone VM.Audit VM.PowerMgmt \
VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk \
VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options \
VM.GuestAgent.Audit Datastore.AllocateSpace Datastore.Audit \
SDN.Use SDN.Audit Sys.Audit"
pveum user add tofu@pve --comment "OpenTofu Lab"
pveum aclmod / -user tofu@pve -role TofuProv
pveum user token add tofu@pve provider --privsep 0Erwartet (gekürzt, kann je nach Version abweichen):
┌──────────────┬──────────────────────────────────────┐
│ key │ value │
╞══════════════╪══════════════════════════════════════╡
│ full-tokenid │ tofu@pve!provider │
│ info │ {"privsep":"0"} │
│ value │ 3f0c...-....-....-....-............ │
└──────────────┴──────────────────────────────────────┘
Der value erscheint nur einmal. Auf dem Laptop
speicherst du ihn nur in der Shell-Umgebung:
read -rs PVE_SECRET
export TF_VAR_pve_api_token="tofu@pve!provider=${PVE_SECRET}"Der zweite Teil baut das Template: Ubuntu-24.04-Cloud-Image,
qemu-guest-agent per virt-customize
hineininstalliert, Disk per import-from.
virt-customize -a "$IMG" --install qemu-guest-agent \
--truncate /etc/machine-id
qm create 9000 --name ubuntu-2404-tpl --ostype l26 \
--cores 2 --memory 2048 --cpu host \
--net0 "virtio,bridge=$BRIDGE" --scsihw virtio-scsi-single \
--agent enabled=1 --serial0 socket --vga serial0
qm set 9000 --scsi0 "$STORAGE:0,import-from=$PWD/$IMG,discard=on,ssd=1"
qm set 9000 --ide2 "$STORAGE:cloudinit" --boot order=scsi0
qm template 9000Erwartet (gekürzt, kann je nach Version abweichen):
[ 0.0] Examining the guest ...
[ 14.2] Installing packages: qemu-guest-agent
[ 41.8] Finishing off
transferred 3.5 GiB of 3.5 GiB (100.00%)
scsi0: successfully created disk 'local-lvm:base-9000-disk-0,discard=on,ssd=1'
Warum der Guest Agent? Mit agent { enabled = true }
wartet der Provider auf den Agent und liest die IPs aus. Fehlt er im
Image, hängt tofu apply bis zum Timeout.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Sechs VMs mit OpenTofu
cd ~/gw-lab/code/infra-proxmox
cat main.tfErwartet:
resource "proxmox_virtual_environment_vm" "node" {
for_each = var.nodes
name = each.key
node_name = var.pve_node
vm_id = each.value.vm_id
tags = ["rke2", each.value.role]
on_boot = true
clone {
vm_id = var.template_id
full = true
}
agent {
enabled = true # qemu-guest-agent ist im Template (pve-prep.sh)
}
cpu {
cores = each.value.cores
type = "host" # Cilium/eBPF profitiert von allen CPU-Flags
}
memory {
dedicated = each.value.memory
}
disk {
datastore_id = var.datastore
interface = "scsi0"
size = each.value.disk
discard = "on"
ssd = true
}
network_device {
bridge = var.bridge
model = "virtio"
}
initialization {
datastore_id = var.datastore
dns {
domain = "lab.internal"
servers = [var.dns_server]
}
ip_config {
ipv4 {
address = "${each.value.ip}/24"
gateway = var.gateway
}
}
user_account {
username = "ubuntu"
keys = [trimspace(var.ssh_public_key)]
}
}
}
Die sechs Knoten stehen als Map in variables.tf (Server
2 vCPU/4 GB, Agents 4 vCPU/8 GB). Eigene Werte (Endpoint, SSH-Key)
kommen in terraform.tfvars:
cp terraform.tfvars.example terraform.tfvars
sed -i.bak "s|ssh-ed25519 AAAA.*\"|$(cat ~/.ssh/id_ed25519.pub)\"|" \
terraform.tfvars
tofu init
tofu validateErwartet (gekürzt):
- Installing bpg/proxmox v0.116.0...
- Installed bpg/proxmox v0.116.0 (signed, key ID ...)
OpenTofu has been successfully initialized!
Success! The configuration is valid.
tofu plan -out lab.plan | tail -1
tofu apply lab.planErwartet (gekürzt, kann je nach Version abweichen):
Plan: 6 to add, 0 to change, 0 to destroy.
proxmox_virtual_environment_vm.node["rke2-cp-1"]: Creation complete after 1m12s
...
Apply complete! Resources: 6 added, 0 changed, 0 destroyed.
Tipp:
proxmox_virtual_environment_vmist die stabile Ressource des Providers. Die neuen Namenproxmox_vm/proxmox_cloned_vmsind in v0.116 noch experimentell bzw. jung – im Lab bleibst du beim Bewährten.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Inventory und Erreichbarkeit
OpenTofu kennt die IPs und rendert das Ansible-Inventory aus
inventory.tftpl:
tofu output -raw inventory > ~/gw-lab/code/infra-rke2/inventory.yml
cd ~/gw-lab/code/infra-rke2
cat inventory.ymlErwartet:
all:
vars:
ansible_user: ubuntu
children:
rke2_servers:
hosts:
rke2-cp-1: { ansible_host: 10.10.20.11 }
rke2-cp-2: { ansible_host: 10.10.20.12 }
rke2-cp-3: { ansible_host: 10.10.20.13 }
rke2_agents:
hosts:
rke2-wk-1: { ansible_host: 10.10.20.21 }
rke2-wk-2: { ansible_host: 10.10.20.22 }
rke2-wk-3: { ansible_host: 10.10.20.23 }
ansible-galaxy collection install -r requirements.yml
ansible all -m ansible.builtin.ping -o
ansible all -a 'ip -br -4 addr show eth0' -oErwartet (gekürzt, kann je nach Version abweichen):
rke2-cp-1 | SUCCESS => {"changed": false,"ping": "pong"}
...
rke2-wk-3 | CHANGED | rc=0 | (stdout) eth0 UP 10.10.20.23/24
Warum eth0? Die Netzwerkkonfiguration, die Proxmox per
Cloud-Init liefert, benennt die NIC eth0. Genau dieser Name
steht in group_vars/all.yml als rke2_iface –
kube-vip und Cilium brauchen ihn.
Fortschritt speichern? Kostenlos registrieren
Drill 4: RKE2-Konfiguration verstehen
cat group_vars/all.ymlErwartet:
rke2_version: v1.36.5+rke2r1
rke2_vip: 10.10.20.10
rke2_api_fqdn: rke2.lab.internal
rke2_iface: eth0 # Proxmox-Cloud-Init benennt die NIC eth0
# Lab-Wert! Echt: per ansible-vault oder Umgebungsvariable
rke2_token: >-
{{ lookup('ansible.builtin.env', 'RKE2_TOKEN')
| default('rke2-lab-token-1234', true) }}
kube_vip_version: v1.2.4
# Tag 9 setzt das auf "true", sobald die Gateway-API-CRDs da sind
cilium_gateway_class_create: auto
rke2_first_server: "{{ groups['rke2_servers'][0] }}"Die Server-Konfiguration
(roles/rke2_server/templates/config.yaml.j2):
token: {{ rke2_token }}
{% if inventory_hostname != rke2_first_server %}
server: https://{{ rke2_vip }}:9345
{% endif %}
node-ip: {{ ansible_host }}
tls-san:
- {{ rke2_vip }}
- {{ rke2_api_fqdn }}
cni: cilium
disable-kube-proxy: true
ingress-controller: none
node-taint:
- "CriticalAddonsOnly=true:NoExecute"
write-kubeconfig-mode: "0600"
etcd-snapshot-schedule-cron: "0 */6 * * *"
etcd-snapshot-retention: 8| Schlüssel | Wirkung |
|---|---|
tls-san |
API-Zertifikat gilt auch für VIP und
rke2.lab.internal |
server |
fehlt nur auf rke2-cp-1 – der initialisiert etcd |
disable-kube-proxy |
kein kube-proxy-Pod, Cilium übernimmt Services |
ingress-controller: none |
kein Traefik, keine fremden Gateway-API-CRDs |
Die Cilium-Werte legt Ansible als HelmChartConfig in
/var/lib/rancher/rke2/server/manifests/ – RKE2 merged sie
in sein Chart rke2-cilium:
apiVersion: helm.cattle.io/v1
kind: HelmChartConfig
metadata:
name: rke2-cilium
namespace: kube-system
spec:
valuesContent: |-
kubeProxyReplacement: true
k8sServiceHost: localhost # RKE2-Supervisor-LB auf jedem Node
k8sServicePort: 6443
devices: {{ rke2_iface }}
l2announcements:
enabled: true
externalIPs:
enabled: true
k8sClientRateLimit: # L2-Leases brauchen API-Budget
qps: 20
burst: 40
gatewayAPI:
enabled: true
gatewayClass:
create: "{{ cilium_gateway_class_create }}"
operator:
replicas: 2
rollOutPods: true
rollOutCiliumPods: trueWarum localhost:6443? Ohne kube-proxy gibt es beim Start
keinen funktionierenden kubernetes-Service. Jeder
RKE2-Knoten betreibt aber einen lokalen Load Balancer auf
127.0.0.1:6443, der zu den Servern weiterleitet – Cilium
spricht den an.
Fortschritt speichern? Kostenlos registrieren
Drill 5: kube-vip für die API-VIP
kube-vip läuft als DaemonSet nur auf den Servern und wird ebenfalls
als Auto-Deploy-Manifest abgelegt. Ausschnitt aus
roles/rke2_server/templates/kube-vip.yaml.j2:
containers:
- name: kube-vip
image: ghcr.io/kube-vip/kube-vip:{{ kube_vip_version }}
args: ["manager"]
env:
- { name: vip_arp, value: "true" }
- { name: port, value: "6443" }
- { name: vip_interface, value: "{{ rke2_iface }}" }
- { name: vip_subnet, value: "32" }
- { name: cp_enable, value: "true" }
- { name: cp_namespace, value: kube-system }
- { name: svc_enable, value: "false" }
- { name: vip_leaderelection, value: "true" }
- { name: vip_leaseduration, value: "5" }
- { name: vip_renewdeadline, value: "3" }
- { name: vip_retryperiod, value: "1" }
- { name: address, value: "{{ rke2_vip }}" }Ablauf beim Bootstrap: rke2-cp-1 startet ohne
server:, das Manifest erzeugt das DaemonSet, kube-vip
gewinnt die Lease plndr-cp-lock und antwortet per ARP auf
10.10.20.10. Erst dann können rke2-cp-2/3 und
die Agents über https://10.10.20.10:9345 beitreten –
deshalb wartet die Rolle auf Port 9345 der VIP.
Warum svc_enable: "false"? Sonst würden kube-vip und
Cilium LB-IPAM um dieselben LoadBalancer-Services konkurrieren.
Vor dem Lauf prüfst du statisch:
ansible-playbook --syntax-check site.yml
ansible-lintErwartet:
playbook: site.yml
Passed: 0 failure(s), 0 warning(s) in 16 files processed of 17 encountered.
Last profile that met the validation criteria was 'production'.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Playbook ausführen
export RKE2_TOKEN=$(openssl rand -hex 32)
time ansible-playbook site.ymlErwartet (gekürzt, kann je nach Version abweichen):
PLAY [Erster Server (cluster-init)] ****************************************
TASK [rke2_server : Warten, bis der Node Ready ist] ************************
FAILED - RETRYING: [rke2-cp-1]: Warten, bis der Node Ready ist (20 retries left).
ok: [rke2-cp-1]
TASK [rke2_server : Warten, bis die VIP den Supervisor-Port bedient] *******
ok: [rke2-cp-1]
PLAY [Weitere Server, einzeln (etcd-Quorum!)] ******************************
...
PLAY RECAP *****************************************************************
rke2-cp-1 : ok=14 changed=8 unreachable=0 failed=0 skipped=0
rke2-wk-3 : ok=8 changed=5 unreachable=0 failed=0 skipped=0
real 11m42s
Warum serial: 1 für die weiteren Server? Treten zwei
neue etcd-Mitglieder gleichzeitig bei, kann das Quorum kurz kippen.
Einzeln ist robust.
Das letzte Play holt rke2.yaml, ersetzt
127.0.0.1 durch die VIP und den Namen default
durch rke2-lab:
export KUBECONFIG=~/.kube/rke2-lab.yaml
kubectl config current-context
kubectl get nodes -o wideErwartet (gekürzt, kann je nach Version abweichen):
rke2-lab
NAME STATUS ROLES AGE VERSION INTERNAL-IP
rke2-cp-1 Ready control-plane,etcd 14m v1.36.5+rke2r1 10.10.20.11
rke2-cp-2 Ready control-plane,etcd 10m v1.36.5+rke2r1 10.10.20.12
rke2-cp-3 Ready control-plane,etcd 8m v1.36.5+rke2r1 10.10.20.13
rke2-wk-1 Ready <none> 5m v1.36.5+rke2r1 10.10.20.21
rke2-wk-2 Ready <none> 5m v1.36.5+rke2r1 10.10.20.22
rke2-wk-3 Ready <none> 5m v1.36.5+rke2r1 10.10.20.23
Fortschritt speichern? Kostenlos registrieren
Drill 7: Cilium und VIP prüfen
kubectl -n kube-system get ds kube-proxy 2>&1 | tail -1
kubectl -n kube-system exec ds/cilium -c cilium-agent -- \
cilium-dbg status | grep -E 'KubeProxyReplacement|Cluster health'
kubectl -n kube-system get lease plndr-cp-lock \
-o jsonpath='{.spec.holderIdentity}{"\n"}'Erwartet (gekürzt, kann je nach Version abweichen):
Error from server (NotFound): daemonsets.apps "kube-proxy" not found
KubeProxyReplacement: True [eth0 10.10.20.21 fe80::... (Direct Routing)]
Cluster health: 6/6 reachable (2026-10-09T10:12:31Z)
rke2-cp-1
Gateway API ist in Cilium aktiviert, aber die CRDs fehlen noch. Der Operator merkt das beim Start, meldet einen Fehler und lässt den Controller aus – Cilium selbst läuft normal weiter:
kubectl -n kube-system logs deploy/cilium-operator | grep -i gateway | head -2
kubectl get gatewayclass 2>&1Erwartet (gekürzt, kann je nach Version abweichen):
level=error msg="Required GatewayAPI resources are not found, please refer to docs
for installation instructions" ...
error: the server doesn't have a resource type "gatewayclass"
Das ist gewollt: An Tag 9 installierst du die CRDs und startest den Operator neu – die Reihenfolge ist das Thema dort.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
export KUBECONFIG=~/.kube/rke2-lab.yaml
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
check "API über VIP erreichbar" \
'curl -sk https://10.10.20.10:6443/version | grep -q gitVersion'
check "6 Nodes Ready" \
'[ "$(kubectl get nodes --no-headers | grep -c " Ready ")" -eq 6 ]'
check "3 etcd-Server" \
'[ "$(kubectl get nodes -l node-role.kubernetes.io/etcd=true \
--no-headers | wc -l)" -eq 3 ]'
check "Server getaintet" \
'kubectl get node rke2-cp-1 -o jsonpath="{.spec.taints}" \
| grep -q CriticalAddonsOnly'
check "kein kube-proxy" '! kubectl -n kube-system get ds kube-proxy'
check "Cilium-DaemonSet vollständig" \
'kubectl -n kube-system rollout status ds/cilium --timeout=10s'
check "kube-vip-Lease vergeben" \
'kubectl -n kube-system get lease plndr-cp-lock \
-o jsonpath="{.spec.holderIdentity}" | grep -q rke2-cp'
check "kein Traefik" '! kubectl -n kube-system get deploy rke2-traefik'Challenge
Beweise, dass die API-VIP ausfallsicher ist: Fahre den aktuellen
Lease-Halter hart herunter und miss, wie lange
kubectl get nodes über die VIP nicht antwortet. Starte die
VM danach wieder.
Hinweis: Die Lease-Dauer von kube-vip ist 5 s,
qm stop simuliert einen Stromausfall.
Lösung
holder=$(kubectl -n kube-system get lease plndr-cp-lock \
-o jsonpath='{.spec.holderIdentity}')
vmid=$(ssh [email protected] \
"qm list | awk '\$2==\"$holder\"{print \$1}'")
ssh [email protected] "qm stop $vmid"
start=$(date +%s)
until kubectl get nodes --request-timeout=2s >/dev/null 2>&1; do sleep 1; done
echo "API wieder da nach $(( $(date +%s) - start )) s"
kubectl -n kube-system get lease plndr-cp-lock \
-o jsonpath='{.spec.holderIdentity}{"\n"}'
ssh [email protected] "qm start $vmid"Erwartet (gekürzt, kann je nach Version abweichen):
API wieder da nach 9 s
rke2-cp-2
Mit zwei von drei etcd-Mitgliedern bleibt das Quorum erhalten; nur die VIP wandert.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Template und VMs per Pipeline bauen (Packer oder Image-Factory),
Image-Version taggen; Token mit
--privsep 1und ACL nur auf Pool/Storage. rke2_tokenaus Vault/OpenBao oderansible-vault, nie im Repo; RKE2-CIS-Profil (profile: cis) und Pod Security prüfen.- Statt ARP-VIP oft ein externer Load Balancer (F5, HAProxy-Paar) oder BGP – kube-vip ARP braucht ein flaches L2-Segment.
- etcd-Snapshots nach S3 (
etcd-s3: true) und Restore regelmäßig üben – Tag 14 legt vor den Drills einen Snapshot als Sicherheitsnetz an. - Upgrades mit dem System Upgrade Controller und
Plan-Ressourcen statt Ad-hoc-Skripten (siehe docs.rke2.io, „Automated Upgrades”).