PKR-Lab

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

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

  1. Auf tailscale.com registrieren (kostenlos für Personal Use).
  2. Settings → Keys im Tailscale-Admin-Panel öffnen.
  3. Generate auth key anklicken.
  4. Optionen wählen:
    • Reusable: Nein (Single-Use ist sicherer)
    • Ephemeral: Nein (der Server soll im Netz bleiben)
    • Tags: optional (z. B. tag:homeserver)
  5. Key kopieren (beginnt mit tskey-auth-…).
  6. Mit Ansible-Vault verschlüsseln (siehe Installation Guide).

Git-Repository für GitOps

ArgoCD zieht die Manifests aus einem Git-Repository. Möglichkeiten:

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


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.