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
https://semaphore.tech.homeserverim LAN und im Tailnet — dnsmasq
hört auf der LAN-IP und auftailscale0, also kommt jeder
Tailscale-Client an die*.homeserver-Namen ran.
(Wichtiger Hintergrund zur DNS-Topologie und warum der Home-Server
nicht der LAN-DNS-Server sein sollte → capulus-core/c-netzwerk-dns/c0000-dns-architecture.md)- Ein-Klick-Run von Playbooks aus beliebigen Git-Repos
(z.B.home-server,worker-0, später beliebig viele mehr). - Geteilter SSH-Key, der von Ansible verwaltet und automatisch auf alle
konfigurierten Targets (Homeserver, Worker, Raspberry-/Banana-Pi-Kiosks, …) verteilt wird. - Geteiltes Ansible-Vault-Password, sicher in einem k8s Secret abgelegt.
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.
- 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 - 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
- Fertig. Du brauchst keinen Global Nameserver und auch nicht
"Override DNS servers" — Split DNS reicht aus. Alle Queries auf
*.homeservergehen 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_nasim 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
- Browser auf
https://semaphore.tech.homeserver. - Login mit
admin+ Passwort aus/etc/semaphore-secrets/admin_password:ssh ubuntu@homeserver "sudo cat /etc/semaphore-secrets/admin_password" - Passwort sofort ändern (oben rechts → Settings → Change Password).
⚠️ Wenn du das tust, kann das nächstemake semaphore-bootstrapsich
nicht mehr einloggen, bis du das neue Passwort wieder in
/etc/semaphore-secrets/admin_passwordablegst. - 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-bootstrapkommentarlos gelöscht — der Bootstrap entfernt
alle Projekte, die nicht insemaphore_projects(group_vars/all.yml) definiert
sind. Für persistente Projekte immersemaphore_projectserweitern.
Wenn du ein Einmal-Projekt willst, das nicht in Git stehen soll, kannst
du es per UI anlegen:
- Create New Project → Name vergeben.
- Key Store:
semaphore-ssh-key(Type SSH Key) — Inhalt aus
/etc/semaphore-secrets/id_ed25519einfügen.git-none(Type None) für öffentliche Repos.
- Repository → URL, Branch, Access Key =
git-none. - Inventory → Type Static, Inhalt im INI-Format, SSH Key =
semaphore-ssh-key. - Task Template → Playbook-Pfad, Inventory + Repository auswählen.
- Save → ▶ Run.
Tipps
- Mehrere Repos: Pro Repo ein eigenes Semaphore-Project anlegen.
Den selben SSH-Key (semaphore-ssh-key) kannst du in jedes Project
importieren. - Neuer Target-Host: in
capulus-ansible/inventory/hosts.ymleintragen,
make semaphore-targetslaufen lassen. Der Public Key landet
automatisch in dessenauthorized_keys. In der Semaphore-Inventory
ergänzen — fertig. - SSH-Key rotieren:
sudo rm -rf /etc/semaphore-secrets/id_ed25519*
auf dem Home-Server,make semaphore && make semaphore-targetsneu
laufen lassen. Dann Key in Semaphore Key Store einmal neu pasten. - Backups: Sichere
/etc/semaphore-secrets/(Passwörter & Keys)
und das PVCsemaphore-dataim Namespacesemaphore(Projects,
Inventories, History).
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!). |