a0030 - Installationsleitfaden
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ansible/a-betriebssystem/a0030-installation.md
Installationsleitfaden
Schritt-für-Schritt-Anleitung, um den Home-Server von Null aus zu provisionieren.
Überblick
Die Installation des TECH-Clusters (Homeserver mit k3s, ArgoCD-Hub, Tailscale) wird durch
einen einzigen Ansible-Playbook-Run erledigt. Dieser Leitfaden begleitet jeden Schritt — vom
Repo-Clone bis zur Verifikation eines lauffähigen Clusters. Die beiden weiteren Cluster PROD
und ENTW (KVM-VMs) sowie die Worker kommen danach dazu, siehe
Schritt 9 und
Schritt 10.
Dauer TECH: ca. 15–25 Minuten (mehrheitlich Downloads).
Schritt 1 — Repository klonen
git clone https://github.com/pkr-lab/capulus-core.git
cd capulus-core
Bei einem Fork stattdessen die URL des Forks verwenden.
Schritt 2 — Inventory konfigurieren (Server-IP setzen)
Inventory-Datei öffnen und die Platzhalter-IP durch die tatsächliche IP des Servers ersetzen:
$EDITOR inventory/hosts.yml
192.168.1.100 durch die eigene Server-IP ersetzen:
homeserver:
hosts:
homeserver:
ansible_host: 192.168.1.100 # <-- ANPASSEN
ansible_user: ubuntu
ansible_ssh_private_key_file: ~/.ssh/id_ed25519
Falls der SSH-User nicht ubuntu ist, ansible_user ebenfalls anpassen.
Liegt der Private Key woanders, ansible_ssh_private_key_file setzen.
Verbindung testen:
ansible -i inventory/hosts.yml homeserver -m ping
# Erwartet: homeserver | SUCCESS => { "ping": "pong" }
Schritt 3 — Variablen setzen
Variablendatei öffnen und alle Werte durchgehen:
$EDITOR group_vars/all.yml
Pflicht-Änderungen:
| Variable | Wert |
|---|---|
timezone |
Eigene Zeitzone (z. B. Europe/Berlin, America/New_York) |
argocd_repo_url |
URL des eigenen GitHub-Repos |
local_subnet |
Heim-LAN-Subnetz (z. B. 192.168.178.0/24) |
tailscale_auth_key |
Via Ansible-Vault setzen (Schritt 4) |
Optional:
| Variable | Default | Hinweis |
|---|---|---|
auto_upgrade |
true |
OS + alle Komponenten bei jedem Run auf neuesten Stable halten |
auto_reboot_if_required |
true |
Auto-Reboot, wenn APT /var/run/reboot-required setzt |
k3s_version |
"" (leer) |
Leer ⇒ k3s_channel folgen. Pin auf z. B. v1.30.2+k3s1 |
k3s_channel |
stable |
Wird genutzt, wenn k3s_version leer ist |
helm_version |
"" (leer) |
Ohne Wirkung seit Incident 017. Die Helm-Version steht in capulus-ansible/roles/k3s/defaults/main.yml (k3s_helm_release), Renovate hebt sie an |
argocd_version |
"" (leer) |
Leer ⇒ neuestes Argo-Helm-Chart |
hostname |
homeserver |
Hostname des Servers |
dnsmasq_prod_vm_hosts |
Hostliste | Hosts unter *.prod.homeserver, die auf die PROD-VM (.99) statt auf den TECH-Cluster zeigen |
semaphore_vault_password |
Vault-Block | Ansible-Vault-Passwort, das Semaphore zur Laufzeit zum Decrypten nutzt |
Tipp.
auto_upgrade: falsesetzen, wenn Reproduzierbarkeit wichtig ist
(CI, Lab-Snapshots) — Ansible installiert dann nur fehlende Pakete und respektiert alle Pins.
Schritt 4 — Tailscale-Auth-Key mit Ansible-Vault verschlüsseln
Niemals den Auth-Key im Klartext committen. Stattdessen mit Ansible-Vault verschlüsseln.
-
Auth-Key im Tailscale-Admin-Panel erstellen:
- Generate auth key
- Reusable deaktivieren (Single-Use ist sicherer)
- Ephemeral deaktivieren (der Server soll persistent bleiben)
- Key kopieren (beginnt mit
tskey-auth-…)
-
Mit Ansible-Vault verschlüsseln:
ansible-vault encrypt_string 'tskey-auth-DEIN_AUTH_KEY' --name 'tailscale_auth_key'
Beim ersten Mal wird ein Vault-Passwort vergeben. Dieses Passwort merken —
es wird bei jedem Playbook-Run abgefragt.
- Das Kommando liefert etwas wie:
tailscale_auth_key: !vault |
$ANSIBLE_VAULT;1.1;AES256
39393965316162623733326665376234386665643530...
...
Encryption successful
-
Den kompletten Block in
capulus-ansible/group_vars/all.ymlals Wert für
tailscale_auth_keyeinsetzen (vontailscale_auth_key:bis zur letzten Zeile). -
Verifizieren:
grep -A5 "tailscale_auth_key:" capulus-ansible/group_vars/all.yml
# Korrekt: tailscale_auth_key: !vault |
# Falsch: tailscale_auth_key: "tskey-auth-..."
Schritt 5 — Ansible-Requirements installieren
Galaxy-Collections auf der Control-Machine installieren:
ansible-galaxy collection install -r requirements.yml
Installiert:
ansible.posix— POSIX-System-Modulecommunity.general— erweiterte Community-Modulekubernetes.core— Kubernetes-/Helm-Module
Verifizieren:
ansible-galaxy collection list | grep -E "ansible.posix|community.general|kubernetes.core"
Schritt 6 — Playbook ausführen
Einfachster Weg — Makefile:
make install # ruft `ansible-galaxy install` + das Playbook auf
Oder Ansible direkt:
ansible-playbook \
-i capulus-ansible/inventory/hosts.yml \
capulus-ansible/site.yml \
--ask-vault-pass
Vault-Passwort eingeben, wenn abgefragt.
Was das Playbook tut (in Reihenfolge):
- common (~3 min) — APT-Updates, UFW-Firewall, Kernel-Parameter, Swap-off, chrony NTP.
- dnsmasq (~30 s) — Installiert und konfiguriert
dnsmasqfür die Zone*.homeserverauf LAN-Interface undtailscale0. - tailscale (~1 min) — Installiert Tailscale, joint das Tailnet mit dem vault-verschlüsselten Auth-Key.
- k3s (~5 min) — Installiert k3s, schreibt die kubeconfig, installiert Helm.
- argocd (~10 min) — Deployt ArgoCD per Helm-Chart und appliziert das Root-
ApplicationSet. - semaphore_secrets (~30 s) — Rendert das Bootstrap-Secret, das der in-Cluster-Semaphore-Pod liest.
- thermal_watchdog / resource_watchdog (~30 s) — Selbst-Abschaltung bei Übertemperatur bzw. Dauerlast.
- cluster_power_manager / power_agent (~30 s) — Wake-on-LAN-Steuerung der Worker je nach Last, HTTP-API für Helligkeit/Wake/Shutdown aus der iOS-App.
- cups_print_server (~1 min) — Richtet CUPS + Treiber für die per USB angeschlossenen Drucker ein (siehe capulus-ansible/2-betrieb-hardware/20040-printer.md).
Im Anschluss an die host-zentrischen Rollen laufen zwei zusätzliche Plays:
- semaphore_targets (~30 s pro Target-Host) — Pusht den Semaphore-SSH-Public-Key in jeden Host der Inventory-Gruppe
semaphore_targets. - semaphore_bootstrap (~1 min) — Spricht die Semaphore-REST-API auf dem Home-Server an und legt Projects, Keys, Repositories, Inventories und Templates idempotent an.
Am Ende druckt das Playbook eine Summary mit den URLs.
Nur bestimmte Rollen ausführen (via Tags, siehe Tag pro Rolle in capulus-ansible/site.yml):
# Nur common
make common
# oder:
ansible-playbook -i inventory/hosts.yml site.yml --tags common --ask-vault-pass
# Nur k3s + argocd
ansible-playbook -i inventory/hosts.yml site.yml --tags k3s,argocd --ask-vault-pass
# Nur die Split-DNS-Schicht (nach Änderung von dnsmasq_prod_vm_hosts)
make dnsmasq
# Tailscale komplett überspringen
ansible-playbook -i inventory/hosts.yml site.yml --skip-tags tailscale --ask-vault-pass
Alle Convenience-Targets siehst du mit make help.
Das Playbook ist vollständig idempotent — mehrfaches Ausführen ist sicher und führt zu keinen unnötigen Änderungen.
Schritt 7 — Installation verifizieren
Per SSH auf den Server und folgende Kommandos laufen lassen:
k3s-Node-Status
ssh [email protected]
kubectl get nodes
Nach make install (nur homeserver):
NAME STATUS ROLES AGE VERSION
homeserver Ready control-plane,master 5m v1.36.4+k3s1
Nach make controlplane-1 (beide Nodes):
NAME STATUS ROLES AGE VERSION
homeserver Ready control-plane,master 5m v1.36.4+k3s1
worker-0 Ready <none> 2m v1.36.4+k3s1
Alle System-Pods
kubectl get pods -A
Alle sollten Running oder Completed sein. Besonders prüfen:
kube-system: Traefik, CoreDNS, metrics-server, local-path-provisionerargocd: argocd-server, argocd-repo-server, argocd-application-controller, …
ArgoCD-Application-Status
kubectl get applications -n argocd
# oder
kubectl get applicationsets -n argocd
Tailscale-Verbindung
tailscale status
Erwartet: dein Server verbunden mit einer 100.x.x.x-IP, Status Connected.
tailscale ip -4
# Liefert die Tailscale-IP, z. B.: 100.101.102.103
Initial-Passwort von ArgoCD
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d; echo
Schritt 8 — Services nutzen
ArgoCD-Web-UI
Im Browser öffnen:
https://argocd.tech.homeserver
Direkt nach der Erstinstallation existiert der Ingress noch nicht (der Hostname greift erst, wenn das
Zertifikat den Eintrag argocd.tech.homeserver enthält). Bis dahin geht der NodePort http://<server-ip>:30080
(Standard der Rolle: argocd_server_nodeport_enabled: true). Sobald der Ingress läuft, setzt
host_vars/homeserver den Wert auf false und der NodePort entfällt.
Das Zertifikat ist selbstsigniert — Browser-Warnung bestätigen.
Login:
- Username:
admin - Passwort: Output aus Schritt 7
Wichtig: Passwort nach dem ersten Login ändern:
- User-Icon (links oben)
- User Info
- Update Password
ArgoCD-CLI
CLI lokal installieren:
# Linux
curl -sSL -o argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
chmod +x argocd
sudo mv argocd /usr/local/bin/
# macOS
brew install argocd
Login:
argocd login argocd.tech.homeserver --username admin --password <initial-passwort> --grpc-web
kubectl von der Control-Machine
Kubeconfig vom Server holen:
# Lokal
scp [email protected]:~/.kube/config ~/.kube/home-server-config
# Nutzen
KUBECONFIG=~/.kube/home-server-config kubectl get nodes
# Oder in den Default-Kubeconfig mergen
KUBECONFIG=~/.kube/config:~/.kube/home-server-config kubectl config view --merge --flatten > ~/.kube/merged-config
mv ~/.kube/merged-config ~/.kube/config
kubectl config get-contexts
kubectl config use-context default # oder den angezeigten Context-Namen
Hinweis: Die kubeconfig auf dem Server zeigt auf 127.0.0.1:6443. Für
Remote-Zugriff entweder:
- SSH-Tunnel:
ssh -L 6443:localhost:6443 [email protected] - Oder die Server-Adresse in der kubeconfig auf die Tailscale-IP umschreiben, bevor sie kopiert wird.
Schritt 9 — worker-0 als Worker-Node beitreten lassen
Nachdem make install auf homeserver abgeschlossen ist, kann worker-0
(192.168.178.95) als zweiter Kubernetes-Worker-Node dem Cluster beitreten.
Voraussetzungen:
- k3s läuft auf homeserver (Schritt 6 abgeschlossen)
- worker-0 ist per SSH erreichbar (Ansible-Konnektivität testen:
ansible -i inventory/hosts.yml worker-0 -m ping) vault_worker-0_become_passwordingroup_vars/all.ymlgesetzt
worker-0 provisionieren:
make controlplane-1
Das Playbook führt in dieser Reihenfolge aus:
- k3s_agent — Deaktiviert Swap, lädt Kernel-Module, konfiguriert sysctl,
installiertnfs-common(Voraussetzung für dienas-StorageClass, siehe
capulus-core/2-betrieb-hardware/20000-nas-storage.md), liest den Join-Token vom
Control-Plane-Server, installiert k3s im Agent-Mode und wartet bis der
NodeReadyist. - thermal_watchdog, resource_watchdog — automatischer Shutdown bei
Übertemperatur bzw. anhaltend hoher CPU/RAM-Last.
worker-0 ist ein reiner k3s-Compute-Node — identisch zu worker-1 (siehe
unten). Persistente App-Daten laufen über die nas-StorageClass (UGREEN
NAS), nicht mehr lokal auf worker-0.
Nur den k3s-Agent-Schritt ausführen:
make k3s-agent
Verifikation:
ssh [email protected] kubectl get nodes -o wide
Erwartet:
NAME STATUS ROLES AGE VERSION INTERNAL-IP
homeserver Ready control-plane,master 10m v1.36.4+k3s1 192.168.178.94
worker-0 Ready <none> 2m v1.36.4+k3s1 192.168.178.95
Weiterer Worker (worker-1): folgt demselben Muster über
make worker-1 (Playbook capulus-ansible/worker-1.yml) — inhaltlich identisch zu
controlplane-1.yml, beide sind reine k3s-Compute-Nodes. Details siehe
capulus-core/b-kubernetes-gitops/b0000-k3s.md.
Schritt 10 — PROD- und ENTW-Cluster einrichten (optional)
Nach dem TECH-Cluster lassen sich zwei weitere, voneinander getrennte Cluster als KVM-VMs aufbauen
(Hintergrund: a0010,
40080). Voraussetzung sind
libvirt_host_enabled: true und die VM-Definitionen in den host_vars
(host_vars/homeserver/vars.yml für prod-vm, host_vars/worker-1/vars.yml für entw-vm).
Achtung Netzwerk: Die Rolle
libvirt_hoststellt den Host auf eine Bridge (br0) um. Ein
falsch angegebenes Interface (network_interface) trennt den Host vom LAN. Die Rolle prüft das
perassert; trotzdem in einem Wartungsfenster arbeiten, eine Konsole bereithalten und danach
einen Reboot-Test machen (Troubleshooting).
PROD (auf dem Homeserver):
make libvirt-host # KVM + Bridge auf dem homeserver, legt die prod-vm (192.168.178.99) an
make prod # common + node_exporter + k3s in der prod-vm
Danach den Cluster im ArgoCD-Hub registrieren und die PROD-ApplicationSets anwenden — Schritt für
Schritt in capulus-core/komponenten/bootstrap-prod.md.
ENTW (auf worker-1):
make worker-1-libvirt-host # KVM + Bridge auf worker-1, legt die entw-vm (192.168.178.100) an
make entw # common + k3s + eigene ArgoCD-Instanz in der entw-vm
Die ENTW-ArgoCD-Instanz folgt dem Branch entw, der vorher gepusht sein muss
(b0050). DNS für *.dev.homeserver setzt die
dnsmasq-Rolle (make dnsmasq).
Verifikation:
kubectl -n argocd get applications | grep '^prod-' # im TECH-Hub: PROD-Applications
ssh [email protected] 'sudo k3s kubectl get nodes' # PROD
ssh [email protected] 'sudo k3s kubectl get nodes' # ENTW
Setup aktualisieren
Um Konfigurationsänderungen nach dem ersten Setup anzuwenden, einfach das
Playbook erneut laufen lassen:
ansible-playbook -i inventory/hosts.yml site.yml --ask-vault-pass
Für Application-Changes, die ArgoCD verwaltet: commit + push ins Git-Repo —
ArgoCD erkennt und appliziert die Änderung automatisch.
Fehlersuche
| Schritt | Symptom | Lösung |
|---|---|---|
| 2 und 3 | Playbook stoppt wegen Platzhaltern oder falscher IP | Inventory und group_vars/all.yml prüfen (Voraussetzungen) |
| 4 | tailscale_auth_key wird als Klartext gelesen |
Wert mit ansible-vault encrypt_string verschlüsseln, !vault-Block einsetzen |
| 5 | make deps scheitert |
Netz und requirements.yml prüfen |
| 6 | Playbook bricht bei „Wait for k3s“ ab | Troubleshooting: k3s startet nicht, Rolle k3s |
| 6 | Verbindung bricht nach common ab |
UFW oder Netplan, Rolle common |
| 6 | Tailscale-Schritt scheitert | Auth-Key abgelaufen, Rolle tailscale |
| 7 | Applications nicht Synced oder Healthy |
ArgoCD: Fehlersuche |
| 7 | Pods hängen | k3s: Fehlersuche |
| 9 | Worker tritt nicht bei | Rolle k3s_agent |
| 10 | PROD oder ENTW nicht erreichbar | Rolle libvirt_host, PROD im Hub |
Dry-Run vor jedem Lauf: make check. Allgemeine Fehlersuche: zentrale Fehlersuche.