Zum Inhalt springen
Trainingslager IT-Trainingslager

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 eine HelmChartConfig. 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 0

Erwartet (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 9000

Erwartet (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.tf

Erwartet:

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 validate

Erwartet (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.plan

Erwartet (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_vm ist die stabile Ressource des Providers. Die neuen Namen proxmox_vm/proxmox_cloned_vm sind 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.yml

Erwartet:

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' -o

Erwartet (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.yml

Erwartet:

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: true

Warum 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-lint

Erwartet:

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.yml

Erwartet (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 wide

Erwartet (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>&1

Erwartet (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 1 und ACL nur auf Pool/Storage.
  • rke2_token aus Vault/OpenBao oder ansible-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”).