Rolle `k3s_agent`
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ansible/rollen/k3s_agent.md
Rolle k3s_agent
Cluster-Beitritt (TECH) per Join-Token vom Control-Plane.
| Läuft gegen | worker-1 (controlplane-1 nutzt nur die Voraussetzungen und die Firewall dieser Rolle, siehe 400a0) |
| Tags | – |
| Quellcode | roles/k3s_agent |
Variablen
Der Server, bei dem der Agent beitritt, kommt aus k3s_server_host (controlplane-0, gesetzt in group_vars/k3s_servers.yml und group_vars/k3s_agents.yml, nicht im Vault). Der k3s-Nodename ist k3s_agent_hostname aus den host_vars.
Defaults aus defaults/main.yml. Überschreiben in group_vars/ oder host_vars/. k3s_installer_url und k3s_installer_sha256 stehen gemeinsam für k3s und k3s_agent in group_vars/all.yml, k3s_version und k3s_server_host des TECH-Clusters kommen aus k3s_cluster_version und k3s_cluster_server_host (ebenfalls group_vars/all.yml).
| Variable | Default | Bedeutung |
|---|---|---|
k3s_agent_ufw_enable |
false |
– |
k3s_agent_ufw_trusted_hosts |
[] |
– |
k3s_agent_ufw_vm_bridge |
`` | – |
Aufteilung der Tasks
Die Voraussetzungen (tasks/prerequisites.yml: nfs-common, Hostname, Swap, Module, sysctl) und die Host-Firewall (tasks/ufw.yml, nur mit k3s_agent_ufw_enable: true) liegen in eigenen Dateien; Swap, Module und sysctl kommen aus common/tasks/k8s_prerequisites.yml. Die Rolle k3s nutzt sie im Modus join für controlplane-1 per import_role … tasks_from, statt sie zu kopieren. Die Variablen k3s_agent_* behalten ihren Namen, auch wenn sie auf einem Server gelten (k3s_agent_hostname ist dort der OS-Hostname).
Ablauf
- nfs-common installieren
- hostnamen setzen
- neuen hostnamen in /etc/hosts eintragen
- kubernetes-voraussetzungen aus der rolle common übernehmen (
common/tasks/k8s_prerequisites.yml) - kubelet-api (port 10250) vom k3s-server erlauben
- flannel-vxlan (udp 8472) nur aus dem lan erlauben
- offene regeln für flannel-vxlan und die api (6443) auf dem agent entfernen
- gesamten verkehr aus dem pod-cidr von k3s erlauben
- gesamten verkehr aus dem service-cidr von k3s erlauben
- infrastruktur-hosts vollständig erlauben
- veraltete offene regeln entfernen
- ssh aus dem lan erlauben
- tailscale-wireguard erlauben
- bridge für virtuelle maschinen weiterleiten
- ufw aktivieren
- node-token von k3s vom server lesen
- node-token von k3s als fakt setzen
- verzeichnis /etc/rancher/k3s anlegen
- k3s-agent-konfiguration templaten
- prüfen ob k3s bereits installiert ist
- aktuelle k3s-version lesen (falls installiert)
- entscheiden ob der k3s-installer (erneut) laufen muss
- k3s-installationsskript herunterladen
- k3s-agent installieren oder aktualisieren
- k3s-installationsskript entfernen
- dienst k3s-agent aktivieren und starten
- warten bis der node {{ k3s_agent_hostname }} ready ist
- node-status des clusters lesen
- alle nodes des clusters anzeigen
Handler
- k3s-agent neu starten
Templates
k3s-agent-config.yaml.j2
Fehlersuche
Allgemeines Vorgehen bei Rollen: ansible-playbook <playbook>.yml --limit <host> --tags <tag> --check --diff -vvv zeigt Änderungen ohne sie anzuwenden (make <ziel>-check bei den Playbooks mit Dry-Run). Die Rollenübersicht mit Make-Zielen: Rollen.
sudo systemctl status k3s-agent
sudo journalctl -u k3s-agent -n 100 --no-pager
sudo cat /etc/rancher/k3s/config.yaml
kubectl get nodes -o wide # auf dem Homeserver
| Symptom | Ursache | Lösung |
|---|---|---|
Worker tritt nicht bei (Unauthorized, Timeout zur Server-URL) |
Join-Token veraltet (Control-Plane neu aufgesetzt) oder Server nicht erreichbar (UFW, Netz, Tailscale) | Rolle erneut ausrollen: sie liest den Token neu von /var/lib/rancher/k3s/server/node-token des Servers (make controlplane-1/worker-1) |
| Pods auf dem Worker starten nicht (NFS) | nfs-common fehlt oder NAS nicht erreichbar |
Paket installieren (die Rolle tut das), NAS-Speicher |
Kubelet nicht erreichbar vom Server (logs, exec schlagen fehl) |
UFW blockiert Port 10250 vom Server | Regel „kubelet API von k3s-Server“ (die Rolle setzt sie), UFW-Status prüfen |
| Netz zwischen Nodes gestört | VXLAN (UDP 8472) nur aus dem LAN erlaubt | Firewall und Flannel prüfen (k3s) |
| Worker ist nachts aus | gewollt (Cluster Power Manager) | Cluster Power Manager |
Allgemeine Fehlersuche: Host-Troubleshooting, zentrale Fehlersuche.