PKR-Lab

b0030 - Semaphore UI — One-Click Ansible für deine Heimnetz-Targets

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-ansible/b-kubernetes-gitops/b0030-semaphore.md

Semaphore UI — One-Click Ansible für deine Heimnetz-Targets

Semaphore ist eine schlanke Web UI, die deine Ansible-Repos ausschert,
gegen ein gewähltes Inventory laufen lässt und dir das Live-Log im Browser
zeigt. In diesem Setup läuft Semaphore als Pod im k3s-Cluster auf dem
Home Server und wird über ArgoCD gepflegt — du fasst nach dem Erst-Setup
nie wieder eine YAML-Datei an, um eine neue Aktion auszulösen.


Was du am Ende hast

Zugriff über Tailscale (einmaliger Admin-Schritt)

dnsmasq lauscht serverseitig schon auf tailscale0 — fehlt nur noch,
dass deine Tailscale-Clients den Home-Server als Nameserver für die
homeserver-Domain nutzen.

  1. Tailscale-IP des Home-Servers ablesen (nicht die LAN-IP — die
    Tailscale-IP ist aus dem Tailnet überall direkt erreichbar, ohne
    dass Subnet-Routes auf jedem Client aktiviert werden müssen):
    ssh ubuntu@homeserver "tailscale ip -4"
    # z.B. 100.78.12.34
    
  2. Tailscale Admin Console → DNS
    öffnen → Abschnitt Nameservers:
    • Add nameserver → Custom...
    • Nameserver IP: Wert aus Schritt 1
    • Restrict to search domains anklicken (oder "Split DNS"
      toggle, je nach UI-Version) → Domain: homeserver
    • Save
  3. Fertig. Du brauchst keinen Global Nameserver und auch nicht
    "Override DNS servers" — Split DNS reicht aus. Alle Queries auf
    *.homeserver gehen jetzt vom Tailscale-Client direkt an dnsmasq
    auf dem Home-Server, alle anderen Queries bleiben beim normalen
    System-Resolver des Clients.

Test (vom Tailscale-Client):

nslookup semaphore.tech.homeserver
# Expected: 192.168.178.94  (von dnsmasq aufgelöst)

Falls die Auflösung nicht klappt: prüfe auf dem Server
sudo ss -lntu | grep :53 — dnsmasq sollte sowohl auf
192.168.178.94:53 als auch auf 100.x.y.z:53 (tailscale0) lauschen.


Architektur in zehn Sekunden

Browser  ──▶  Traefik (k3s ingress)  ──▶  semaphore Pod
                                              │
                                              ├─▶ Git clone (jedes Run)
                                              └─▶ SSH ──▶ Raspi, NAS, …

Der semaphore-bootstrap Secret im Namespace semaphore hält:

Key Inhalt
admin_username admin (Default)
admin_password Auto-generiert, liegt unter /etc/semaphore-secrets/admin_password
access_key_encryption 32-byte base64, verschlüsselt Semaphores DB-Secrets
ansible_vault_password Dein Master-Vault-Password (erforderlich)
ssh_private_key Ed25519-Key — Semaphore SSH-t damit raus
ssh_public_key Gegenstück, wird auf die Targets verteilt

Erst-Setup (einmalig, ~5 Min)

1. Vault-Password vorbereiten

Wenn du in irgendeinem Repo ansible-vault encrypt_string benutzt, muss
Semaphore das Vault-Password kennen. Verschlüssele es mit sich selbst:

ansible-vault encrypt_string 'DEIN_VAULT_PW' \
  --name 'semaphore_vault_password' --ask-vault-pass

Den !vault |…-Block über den leeren Wert in
capulus-ansible/group_vars/all.yml (semaphore_vault_password) pasten.

2. Targets in der Inventory eintragen

capulus-ansible/inventory/hosts.yml:

xibo_displays:
  hosts:
    pi-livingroom:
      ansible_host: 192.168.178.50
      ansible_user: pi
      ansible_ssh_private_key_file: ~/.ssh/id_ed25519

Die UGREEN NAS (ugreen_nas im Inventory) ist kein Semaphore-Target: sie läuft mit der Firmware UGOS, RAID
und NFS werden manuell über deren Web-UI eingerichtet, es gibt kein Playbook dafür.

3. Playbook laufen lassen

make install        # Vollständig (inkl. Semaphore + Targets-Verteilung)
# oder gezielt:
make semaphore             # nur Secret auf dem Home-Server bauen
make semaphore-targets     # nur SSH-Key auf die Targets pushen

Ausgabe am Ende:

==================================================
Semaphore UI bootstrap material ready
==================================================
URL:        https://semaphore.tech.homeserver
Username:   admin
Password:   stored in /etc/semaphore-secrets/admin_password
SSH pubkey: /etc/semaphore-secrets/id_ed25519.pub
==================================================

Admin-Passwort einmalig auslesen:

ssh ubuntu@homeserver "sudo cat /etc/semaphore-secrets/admin_password"

4. ArgoCD wartet & deployt

Nach max. 3 Minuten erscheint in ArgoCD eine neue Application semaphore,
ein Pod startet, Traefik routet semaphore.tech.homeserver darauf.

kubectl -n semaphore get pods,svc,ingress

Projekte werden automatisch angelegt

Nach make install (genauer: nach der Rolle semaphore_bootstrap) sind in
Semaphore zwei Projekte schon vollständig konfiguriert — Key Store,
Repository, Inventory und Task Template inklusive. Du musst in der UI
nichts mehr klicken außer ▶ Run.

Project Repository Inventory Template Playbook Schedule
home-server dieses Repo (argocd_repo_url aus group_vars/all.yml) homeservers (Gruppen k3s_servers, k3s_primary, k3s_agents) Deploy Home Server capulus-ansible/site.yml täglich 06:00
worker-0 dieses Repo (argocd_repo_url aus group_vars/all.yml) worker_0_only (Gruppe k3s_servers mit controlplane-1, 192.168.178.95) Deploy worker-0 capulus-ansible/controlplane-1.yml —

Workflow

  1. Browser auf https://semaphore.tech.homeserver.
  2. Login mit admin + Passwort aus /etc/semaphore-secrets/admin_password:
    ssh ubuntu@homeserver "sudo cat /etc/semaphore-secrets/admin_password"
    
  3. Passwort sofort ändern (oben rechts → Settings → Change Password).
    ⚠️ Wenn du das tust, kann das nächste make semaphore-bootstrap sich
    nicht mehr einloggen, bis du das neue Passwort wieder in
    /etc/semaphore-secrets/admin_password ablegst.
  4. Projekt auswählen → Template → ▶ Run. Live-Log erscheint sofort.

Weitere Projekte hinzufügen

semaphore_projects in capulus-ansible/group_vars/all.yml (oder direkt in der
Default-Liste in capulus-ansible/roles/semaphore_bootstrap/defaults/main.yml)
erweitern und make semaphore-bootstrap laufen lassen:

semaphore_projects:
  - name: home-server          # existierende Defaults beibehalten
    # ...
  - name: worker-0             # existierende Defaults beibehalten
    # ...
  - name: my-new-project       # neu
    repository:
      name: my-new-project-git
      url: https://github.com/me/my-repo.git
      branch: main
    inventories:
      - name: my-targets
        type: static
        ssh_key: semaphore-ssh-key
        content: |
          [targets]
          host1 ansible_host=192.168.178.150
    templates:
      - name: "Deploy My Thing"
        playbook: site.yml
        inventory: my-targets
    schedules:                        # optional — weglassen für kein Cron
      - name: "Daily 06:00"
        template: "Deploy My Thing"
        cron: "0 6 * * *"
        active: true

Schedules werden in der Zeitzone Europe/Berlin ausgewertet (via SEMAPHORE_SCHEDULE_TIMEZONE im Semaphore-Deployment). Das Cron-Format ist Standard-5-Feld. Das Auto-Bootstrap ist idempotent: bei jedem make semaphore-bootstrap wird ein vorhandener Schedule per PUT aktualisiert (self-healing).

Wichtig: das Auto-Bootstrap ist vollständig idempotent — Ressourcen werden
bei jedem Run via PUT aktualisiert (self-healing). Ein manuelles Löschen in der UI
ist nicht nötig. Einzige Ausnahme: Umbenennen eines Projekts/Inventories/Templates
erzeugt einen Orphan-Eintrag, der beim nächsten Run automatisch gelöscht wird.


Manuelles Anlegen (Fallback / ad-hoc)

⚠️ Warnung: Manuell in der UI angelegte Projekte werden beim nächsten
make semaphore-bootstrap kommentarlos gelöscht — der Bootstrap entfernt
alle Projekte, die nicht in semaphore_projects (group_vars/all.yml) definiert
sind. Für persistente Projekte immer semaphore_projects erweitern.

Wenn du ein Einmal-Projekt willst, das nicht in Git stehen soll, kannst
du es per UI anlegen:

  1. Create New Project → Name vergeben.
  2. Key Store:
    • semaphore-ssh-key (Type SSH Key) — Inhalt aus
      /etc/semaphore-secrets/id_ed25519 einfügen.
    • git-none (Type None) für öffentliche Repos.
  3. Repository → URL, Branch, Access Key = git-none.
  4. Inventory → Type Static, Inhalt im INI-Format, SSH Key = semaphore-ssh-key.
  5. Task Template → Playbook-Pfad, Inventory + Repository auswählen.
  6. Save → ▶ Run.

Tipps


Troubleshooting

Symptom Check
semaphore.tech.homeserver löst nicht dig +short semaphore.tech.homeserver @192.168.178.94 prüfen (Wildcard *.homeserver), sonst make dnsmasq erneut ausführen
Pod CrashLoopBackOff kubectl -n semaphore logs deploy/semaphore — meist fehlt das Bootstrap-Secret
Playbook scheitert mit "Permission denied (publickey)" make semaphore-targets lief nicht — Public Key fehlt in authorized_keys auf dem Ziel
Vault-Passwort wird nicht erkannt semaphore_vault_password ist leer oder mit falschem PW verschlüsselt; sicherstellen dass ANSIBLE_VAULT_PASSWORD_FILE im Semaphore Default-Environment gesetzt ist (wird ab Bootstrap automatisch injiziert)
semaphore-bootstrap failt beim Login Admin-PW in der UI geändert ohne /etc/semaphore-secrets/admin_password zu syncen, oder PVC enthält noch alte DB. Fix: PW dort hinterlegen oder PVC neu (löscht alle Projekte!).