PKR-Lab

Nutzung

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/nutzung.md

Nutzung

Typische Abläufe im Betrieb. Befehle für Hosts (Playbooks, make …) laufen im Verzeichnis von capulus-ansible.

Lokale Prüfungen vor dem Commit

make lint
python3 scripts/check-token-register.py
(cd argocd/apps/tech/pacman/server && go build ./... && go vet ./... && go test ./... && go mod tidy -diff)
(cd argocd/apps/tech/carplay-api/src && go build ./... && go vet ./... && go test ./... && go mod tidy -diff)
(cd argocd/apps/tech/isc-news-bot && npm ci && npm test)
helm template argocd/apps/<cluster>/<app> | kubeconform -strict -ignore-missing-schemas -summary

make lint führt yamllint über argocd/ und helm lint über alle Charts aus. Nur die betroffenen Teile prüfen, nicht immer alles.

Application hinzufügen

Erst entscheiden, in welchen Cluster die App gehört: ENTW (Entwicklung/Test, der übliche Startpunkt), TECH (Infrastruktur und Betriebsdienste) oder PROD (Apps mit echtem Nutzerkreis). Die Projekte, Ordner und Pflichtschritte je Cluster stehen in b0020 ArgoCD-Projekte.

Cluster Ordner Zusätzlich nötig
TECH argocd/apps/tech/<app>/ Namespace in argocd_platform_apps oder argocd_workloads_apps (roles/argocd/defaults/main.yml in capulus-ansible), danach dort make render-bootstrap CORE_DIR=<Pfad zu capulus-core>
PROD argocd/apps/prod/<app>/ Namespace in argocd/bootstrap-prod/appproject.yaml (im Hub anwenden), bei reinen Manifest-Ordnern Pfad im ApplicationSet, interner Host in dnsmasq_prod_vm_hosts (capulus-ansible)
ENTW argocd/apps/entw/<app>/ auf dem Branch entw nichts

Beispiel TECH:

cd capulus-core
git checkout -b feat/my-app
mkdir -p argocd/apps/tech/my-app

cd ../capulus-ansible
$EDITOR roles/argocd/defaults/main.yml
make render-bootstrap CORE_DIR=../capulus-core

Danach in beiden Repos je einen Commit und PR (feat(apps): my-app hinzufügen). main ist geschützt, ein Merge rollt sofort aus. Innerhalb von etwa 3 Minuten erkennt ArgoCD das neue Verzeichnis, legt eine Application my-app im Namespace my-app an (PROD-Applications heißen prod-<app>) und synct sie. Hostnamen immer im Tier-Schema (<app>.tech.homeserver, <app>.prod.homeserver, <app>.dev.homeserver).

Mehr: b0010 ArgoCD, f00b0 Promotion-Kette.

Secret versiegeln

printf '%s' "$WERT" | kubeseal --raw --namespace <ns> --name <secret> \
  --controller-namespace sealed-secrets --controller-name sealed-secrets-controller \
  --from-file=/dev/stdin

Hilfsskripte in scripts/: seal-*.sh für einzelne Secrets, reseal-for-prod.sh für den Umzug eines SealedSecrets in den PROD-Cluster. Neue Tokens werden in ops/token-register.yaml eingetragen.

Promotion ENTW → TECH → PROD

Eine Änderung läuft zuerst über den Branch entw in den ENTW-Cluster, nach 24 Stunden Gesundheit als PR nach main (TECH), nach weiteren 2 Stunden als PR für PROD. Details und Voraussetzungen: f0080 ENTW-Promotion, f00b0 Promotion-Kette.

Images bauen

build-images.yml baut die selbst gehosteten Images (pacman, carplay-api, n8n, alert-caller, isc-news-bot) bei Änderungen am Dockerfile oder Quellcode und schreibt den Tag sha-<commit> nach image.tag in der values.yaml (scripts/bump-image-tag.py). Registry: ghcr.io/pkr-lab. Manuell: Workflow Build Workload Images mit Auswahl der App starten. Details: f0060 Images bauen.

Monitoring

Ein schlanker VictoriaMetrics-+-Grafana-Stack lebt unter argocd/apps/tech/monitoring/ und wird automatisch von ArgoCD ausgerollt. Er überwacht alle drei Cluster, das NAS und die Kiosk-Geräte; Logs laufen zentral in VictoriaLogs (argocd/apps/tech/logging/, Doku).

Stack-Details
Komponente Detail
TSDB VMSingle — 15 Tage Retention, 10 Gi local-path-PVC
Scrapers VMAgent scrapet alle VMServiceScrape/VMPodScrape + Prometheus ServiceMonitor-CRDs
Host-Metriken prometheus-node-exporter als DaemonSet auf den TECH-Knoten, node_exporter auf prod-vm/entw-vm, smartctl-Exporter für die Platten
Cluster-Metriken kubelet/cAdvisor, kube-apiserver, kube-state-metrics, CoreDNS
Alerts Default-kube-prometheus-Rules; ntfy-Alertmanager-Bridge
Dashboards Ordner Hardware (Mainboard, Übersicht mit Waben, Server-Detail, Speicher & Lebensdauer), Anwendungen (TECH) (nur Rhein-Pegel), Node Exporter Full, VictoriaMetrics + Kubernetes Views, siehe Hardware-Monitoring

Grafana öffnen unter https://grafana.tech.homeserver — Admin-Passwort abfragen (auf dem TECH-Cluster):

kubectl -n monitoring get secret grafana-admin \
  -o jsonpath='{.data.admin-password}' | base64 -d; echo

Tokens rotieren

scripts/token-watch.py meldet täglich ablaufende oder zu alte Tokens. Rotationsanleitungen stehen im Feld rotation.runbook des Registers; das Terminal-Werkzeug cubi zeigt Alter und Ablauf an und führt durch die Rotation.


Fehlersuche

Symptom Ursache Lösung
make lint meldet helm: not found (Chart-Lint übersprungen) Helm fehlt lokal Helm installieren, helm dependency build wird je Chart automatisch ausgeführt
helm lint meldet fehlende Abhängigkeiten Chart.lock oder charts/ fehlt helm dependency update argocd/apps/<cluster>/<app> und Chart.lock committen
Neue App erscheint nicht in ArgoCD Namespace fehlt in der Liste, Bootstrap nicht neu erzeugt oder nicht committet Abschnitt „Application hinzufügen“, ArgoCD: Fehlersuche
kubeseal-Wert nicht entschlüsselbar falscher Cluster, Name oder Namespace Sealed Secrets: Fehlersuche
Merge nach main nicht möglich Pflicht-Checks rot oder pending Branch-Schutz, CI-Lint
Image wird nicht gebaut Pfadfilter des Workflows Images bauen
Promotion hängt Gate, Token, Konflikt ENTW-Promotion, Promotion-Kette, Skripte-Referenz
Skript meldet Fehler: … Voraussetzung fehlt (Datei, Werkzeug, Kontext) Skripte-Referenz: Meldungen
Token läuft ab Register Secrets-Rotation

Zentrale Anlaufstelle: Fehlersuche.