a0020 - Voraussetzungen
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ansible/a-betriebssystem/a0020-prerequisites.md
Voraussetzungen
Dieses Dokument listet alles auf, was vor dem ersten Playbook-Run vorhanden sein muss.
Control-Machine
Der Rechner, von dem aus Ansible läuft, braucht:
Ansible >= 2.14
# Version prüfen
ansible --version
# Installation via pip (empfohlen)
pip3 install --user "ansible>=2.14"
# Oder via pipx (isolierte Umgebung)
pipx install ansible
# Auf Ubuntu/Debian via apt (oft ältere Version)
sudo apt install ansible
Python >= 3.10
# Version prüfen
python3 --version
# Zusätzlich zu Ansible benötigte Python-Pakete:
pip3 install --user netaddr jmespath
netaddr wird von ansible.utils für CIDR-Berechnungen (UFW-Regeln) genutzt,
jmespath von dem community.general.json_query-Filter in der Rolle
semaphore_bootstrap.
SSH-Client
Ein normaler ssh-Client muss verfügbar sein. Test:
ssh -V
Ziel-Server
Frische Ubuntu-26.04-LTS-Installation
- Server-Variante (kein Desktop)
- Mindestens 4 GB RAM (Referenz: 32 GB)
- Mindestens 20 GB Disk (Referenz: 512 GB NVMe-SSD)
- Netzwerk-Anbindung (DHCP oder statische IP — statisch empfohlen)
- Non-Root-User mit
sudo-Rechten (Ubuntu-Default:ubuntu)
SSH-Key-Authentifizierung
Die Control-Machine muss sich passwortlos per Key am Server anmelden können:
# Falls noch kein Key vorhanden ist
ssh-keygen -t ed25519 -C "home-server-ansible" -f ~/.ssh/id_ed25519
# Public Key auf den Server kopieren (einmaliger Passwort-Login)
ssh-copy-id -i ~/.ssh/id_ed25519.pub [email protected]
# Login testen
ssh -i ~/.ssh/id_ed25519 [email protected] "echo 'SSH-Key-Login funktioniert'"
Liegt der Private Key woanders, in capulus-ansible/inventory/hosts.yml entsprechend
ansible_ssh_private_key_file anpassen.
Der Schlüssel-Login ist die einzige Anmeldeart: Die Rolle ssh_hardening schaltet Passwort-Login und root-Login auf homeserver, Workern, prod-vm und entw-vm ab
(60020). Der Schlüssel muss deshalb vor dem ersten Lauf der Rolle auf dem Host liegen.
Python 3 auf dem Server
Ubuntu 26.04 bringt Python 3.12 mit:
ssh [email protected] "python3 --version"
Externe Accounts
Tailscale-Account + Auth-Key
- Auf tailscale.com registrieren (kostenlos für Personal Use).
- Settings → Keys im Tailscale-Admin-Panel öffnen.
- Generate auth key anklicken.
- Optionen wählen:
- Reusable: Nein (Single-Use ist sicherer)
- Ephemeral: Nein (der Server soll im Netz bleiben)
- Tags: optional (z. B.
tag:homeserver)
- Key kopieren (beginnt mit
tskey-auth-…). - Mit Ansible-Vault verschlüsseln (siehe Installation Guide).
Git-Repository für GitOps
ArgoCD zieht die Manifests aus einem Git-Repository. Möglichkeiten:
- Dieses Repository selbst (empfohlen — am einfachsten)
- Ein separates privates Repository
Das Repository muss öffentlich sein oder ArgoCD mit Credentials für
private Repos versorgt werden.
argocd_repo_url in capulus-ansible/group_vars/all.yml auf die eigene Repo-URL setzen.
Ansible-Galaxy-Collections
Vor dem Playbook-Run die benötigten Collections installieren:
ansible-galaxy collection install -r requirements.yml
Die capulus-ansible/requirements.yml liefert:
| Collection | Version | Zweck |
|---|---|---|
ansible.posix |
>= 1.5.0 | POSIX-Module (sysctl, firewalld, …) |
community.general |
>= 7.0.0 | Erweiterte Module (snap, homebrew, …) |
kubernetes.core |
>= 2.4.0 | kubectl/Helm-Interaktionsmodule |
Pre-flight-Checks
Vor dem Playbook-Run alle Punkte abhaken — alle sollten grün sein.
1. SSH-Verbindung
ssh [email protected] "whoami"
# Erwartet: ubuntu
2. Passwortloses sudo
ssh [email protected] "sudo whoami"
# Erwartet: root
# Falls Passwort abgefragt wird, NOPASSWD-sudo konfigurieren:
# echo 'ubuntu ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/ubuntu
3. Ansible-Ping
ansible -i inventory/hosts.yml homeserver -m ping
# Erwartet:
# homeserver | SUCCESS => { "ping": "pong" }
4. Python auf dem Ziel verfügbar
ansible -i inventory/hosts.yml homeserver -m ansible.builtin.command \
-a "python3 --version"
# Erwartet: python3 3.x.x
5. Internet-Zugriff auf dem Server
ssh [email protected] "curl -sf https://get.k3s.io | head -5"
# Erwartet: Script-Header (keine Fehler)
6. Genug Disk-Speicher
ssh [email protected] "df -h /"
# Erwartet: mindestens 20 GB frei
7. Genug RAM
ssh [email protected] "free -h"
# Erwartet: mindestens 4 GB total
8. Inventory aktualisiert
grep "192.168.1.100" capulus-ansible/inventory/hosts.yml
# Liefert das den Default-Wert, wurde die Datei noch nicht angepasst.
9. group_vars aktualisiert
grep "YOUR_USER\|CHANGE_ME\|CHANGE_THIS" capulus-ansible/group_vars/all.yml
# Sollte KEINE Treffer liefern — sonst stehen noch Platzhalter drin.
10. Vault-Secret verschlüsselt
grep "tailscale_auth_key:" capulus-ansible/group_vars/all.yml
# Korrekt: tailscale_auth_key: !vault |
# Falsch: tailscale_auth_key: "CHANGE_ME_USE_VAULT"
Optional: Statische IP
Für einen Server ist eine statische IP dringend empfohlen — vor dem Ansible-Run
konfigurieren.
Auf Ubuntu 26.04 (netplan):
# /etc/netplan/00-installer-config.yaml
network:
version: 2
ethernets:
ens3: # tatsächlichen Interface-Namen aus `ip link show` einsetzen
dhcp4: false
addresses:
- 192.168.1.100/24
routes:
- to: default
via: 192.168.1.1
nameservers:
addresses:
- 1.1.1.1
- 8.8.8.8
# Anwenden:
sudo netplan apply
Anforderungen an den Heimrouter
- Server unter der konfigurierten IP erreichbar.
- Outbound UDP-Port 41641 nicht blockieren (Tailscale).
- Kein Port-Forwarding für Tailscale nötig (DERP-Relay als Fallback).
Fehlersuche
Die Pre-flight-Checks oben liefern die erste Diagnose. Typische Abweichungen:
| Check | Symptom | Lösung |
|---|---|---|
| 1 SSH-Verbindung | Permission denied (publickey) oder Timeout |
Schlüssel hinterlegen, IP in inventory/hosts.yml, Firewall |
| 2 Sudo | Passwortabfrage | NOPASSWD in /etc/sudoers.d/ubuntu setzen |
| 3 Ansible-Ping | UNREACHABLE! |
SSH-Benutzer (ansible_user), Host-Key (host_key_checking = True), Netz |
| 3 Ansible-Ping | /usr/bin/python3: not found |
Python auf dem Ziel installieren (Abschnitt „Python 3 auf dem Server“) |
| 5 Internet-Zugriff | Download scheitert | DNS und Proxy auf dem Server prüfen |
| 6 und 7 Speicher und RAM | zu wenig Platz oder RAM | Mindestwerte: 20 GB frei, 4 GB RAM |
| 8 und 9 Inventory und group_vars | Platzhalter (CHANGE_ME) |
Werte setzen |
| 10 Vault | Wert unverschlüsselt | ansible-vault encrypt_string |
| Galaxy-Collections | ERROR! Unknown collection |
make deps |
Weiter: Troubleshooting, Rollen: Fehlersuche.