↓ Zum Hauptinhalt springen
Zyria
  1. Beiträge/
  2. Kleines Homelab/

k3s-prod: Kubernetes Cluster Konfiguration und Anwendungsbereitstellung

Inhaltsverzeichnis

Kubernetes Cluster Konfiguration und Anwendungsbereitstellung
#

Dieses Repository ist die einzige Quelle für die Konfiguration eines k3s-Produktionsclusters und aller darauf laufenden Anwendungen. Der gewünschte Zustand steht deklarativ in Git; ArgoCD gleicht den Cluster fortlaufend dagegen ab.

Zweck des Repositories
#

Daraus folgt die wichtigste Betriebsregel: Änderungen werden hier committet, nicht mit kubectl am Cluster vorbei gemacht. Was von Hand geändert wird, setzt ArgoCD beim nächsten Abgleich zurück.

Ordnerstruktur
#

Pfad Inhalt
apps/ Je ein Verzeichnis pro Anwendung, jedes mit eigener README
components/ Kustomize-Components, die mehrere Anwendungen einbinden
ansible/ Installation des Clusters, geordnetes Herunter- und Wiederanfahren
manifests.yaml Liste der Anwendungen, die ArgoCD ausrollt
init.yaml ArgoCD-ApplicationSet, das diese Liste einliest
force-sync.yaml Erzwingt einen Abgleich, wenn der reguläre nicht greift
ansible.cfg, requirements.yml Umgebung für den Ansible-Teil
renovate.json5 Renovate-Konfiguration dieses Repositories
cliff.toml git-cliff-Konfiguration für den Changelog
.forgejo/ Workflows sowie Issue- und Pull-Request-Vorlagen
CONTRIBUTING.md Konventionen für Commits und Änderungen

Wie eine Anwendung in den Cluster kommt
#

  1. Ein Verzeichnis unter apps/ anlegen, mit kustomization.yaml, namespace.yaml, den nötigen Manifesten und einer README.md.
  2. Einen Eintrag in manifests.yaml ergänzen — Name, Verzeichnis, Namespace.
  3. Committen und pushen. init.yaml erzeugt daraus ein ArgoCD-ApplicationSet, das die Anwendung anlegt und synchron hält.

Ohne Schritt 2 passiert nichts: Ein Verzeichnis unter apps/ allein wird nicht ausgerollt. Genau darum sind einige der unten aufgeführten Anwendungen vorbereitet, aber nicht aktiv — sie sind in Arbeit oder Nachfolger eines noch laufenden Dienstes.

Verwendete Technologien
#

Werkzeug Rolle
k3s Die Kubernetes-Distribution selbst
ArgoCD Gleicht den Cluster gegen dieses Repository ab
Kustomize Fasst Manifeste je Anwendung zusammen, auch Helm-Charts
Helm Bezieht die Charts, eingebunden über helmCharts in der Kustomization
Traefik Ingress-Controller
MetalLB LoadBalancer-Adressen im lokalen Netz
cert-manager TLS-Zertifikate
Longhorn Verteilter Blockspeicher für persistente Volumes
Keel Aktualisiert Images anhand von Annotationen
Renovate Hebt Chart- und Image-Versionen in diesem Repository

Anwendungen im Cluster
#

Die Spalte Aktiv sagt, ob die Anwendung in manifests.yaml eingetragen und damit tatsächlich ausgerollt ist. Einzelheiten stehen jeweils in der README des Verzeichnisses.

Cluster-Grundlage
#

App Aktiv Zweck
k3s ja Local Path Provisioner und virtuelle IP des API-Servers
metallb ja LoadBalancer-Adressen aus dem lokalen Netz
multus ja Zweites Netzwerk-Interface für Pods, mit Whereabouts als IPAM
coredns ja Cluster-interne Namensauflösung
traefik ja Ingress-Controller und gemeinsame Middlewares
cert-manager ja TLS-Zertifikate über Let’s Encrypt und DNS01
longhorn ja Verteilter Blockspeicher
descheduler ja Verteilt Pods neu, wenn die Platzierung nicht mehr passt
reloader ja Startet Workloads neu, wenn sich ConfigMap oder Secret ändert
endpoint-copier-operator ja Kopiert Endpoints über Namespace-Grenzen
system-upgrade-controller ja Aktualisiert k3s auf den Knoten
keel ja Automatische Image-Updates
argocd ja Der GitOps-Abgleich selbst

Netzwerk und Zugang
#

App Aktiv Zweck
headscale ja Selbst betriebener Tailscale-Kontrollserver
wireguard ja VPN-Server mit Web-Portal und SSH-Bastion
vpn-site-a ja Standortkopplung per WireGuard, als Subnetz-Router im Tailnet
vpn-site-b ja Dasselbe Muster mit OpenVPN als Transport
nameserver ja Autoritativer DNS für das lokale Netz
pihole ja Werbe- und Trackingfilter im DNS
authentik ja Identitätsanbieter für Single Sign-on
self-service-password — Passwortrücksetzung gegen das Verzeichnis

Mail
#

App Aktiv Zweck
mailstack ja Postfix, Dovecot, Rspamd, ClamAV und Unbound als Verbund
mailstack-new — Nachfolgeaufbau desselben Stapels
roundcube ja Webmail
dmarc-report ja Wertet eingehende DMARC-Berichte aus
mta-sts ja Liefert die MTA-STS-Richtlinie aller Maildomains aus

Entwicklung und Betrieb
#

App Aktiv Zweck
forgejo ja Git-Hosting, Registry und CI
forgejo-runner ja CI-Runner für die eigene Instanz und für Codeberg
git-pages ja Statische Seiten aus Forgejo-Repositories
renovate ja Abhängigkeits-Updates über alle Repositories
ansible-semaphore ja Weboberfläche für Ansible-Läufe
ittools ja Sammlung kleiner Werkzeuge, läuft im Browser
hedgedoc ja Gemeinsames Schreiben in Markdown

Beobachtung
#

App Aktiv Zweck
prometheus ja Metriken des Clusters
uptime-kuma ja Erreichbarkeitsprüfung und Statusseite
openobserve — Ablage und Auswertung von Logs
fluent-bit — Sammelt die Logs und liefert sie dorthin
trivy — Schwachstellen- und Konfigurationsprüfung der Images
zabbix — Überwachung außerhalb des Clusters
whoami ja Kleiner Testdienst, zeigt die eigene Anfrage zurück

Kommunikation und Zusammenarbeit
#

App Aktiv Zweck
matrix ja Synapse-Homeserver mit Element-Web-Client
matrix-new — Migration auf das offizielle ESS-Chart
matrix-admin ja Verwaltungsoberfläche des Homeservers
mastodon ja Föderiertes soziales Netzwerk
nextcloud ja Dateien, Kalender, Kontakte
nextcloud-new — Umzug auf das offizielle Nextcloud-Chart
paperless ja Dokumentenarchiv mit Volltextsuche
zammad — Ticketsystem

Haus und Energie
#

App Aktiv Zweck
home-assistant ja Hausautomatisierung samt Matter, Thread und MQTT
opendtu ja Veröffentlicht die Oberfläche eines Wechselrichter-Auslesegeräts
ace1500 — MQTT-Themenabbildung für einen Zendure-Speicher
sf1200 — Dasselbe für den Solarflow Hub 1200
sf2000 — Dasselbe für den Hub 2000
sf2000-2 — Zweiter Hub 2000
music-assistant — Musikwiedergabe im Haus
plex ja Medienserver mit Hardware-Transkodierung
unifi-controller ja Verwaltung der Netzwerkgeräte

Webseiten
#

App Aktiv Zweck
zyria-de ja Hauptwebseite, Inhalt fortlaufend per git-sync
quaecki-de ja Statische Seite, Inhalt beim Start geklont
hx53-de ja Statische Seite, Inhalt beim Start geklont
solarchart-de ja Ertragsprognose, unter einem Pfad der Hauptdomain
maintenance-page ja Wartungsseite, die bei Ausfall einspringt

Eine App zu einem Kunden kopieren
#

Der Cluster ist Test- und Entwicklungsumgebung: Die App-Verzeichnisse sind so geschrieben, dass sie sich als Ganzes in einen Kundencluster kopieren lassen. Die READMEs beschreiben deshalb den Dienst, nicht diese Installation — sie müssen beim Kopieren nicht angefasst werden.

Anzupassen sind die Manifeste:

Stelle Was
values.yaml → ingress.hosts Hostnamen des Kunden
certs.yaml commonName und dnsNames
namespace.yaml, Eintrag in manifests.yaml Name, falls er abweichen soll
Zugangsdaten in values.yaml Durchgängig neu setzen
storage.yaml Größen und StorageClass des Zielclusters

Ausgenommen sind die Verzeichnisse der eigenen Webseiten und der eigenen Hausinstallation — die sind auf diesen Standort zugeschnitten und nicht als Vorlage gedacht.

Installation und Bereitstellung
#

Eine Anwendung rendern, ohne sie anzuwenden:

1kubectl kustomize --enable-helm apps/<app>

--enable-helm ist nötig, sobald die Kustomization einen helmCharts-Block enthält — ohne das Flag bleibt der Block stillschweigend unbeachtet und das Ergebnis ist unvollständig.

Von Hand anwenden, falls ArgoCD nicht zur Verfügung steht:

1kubectl kustomize --enable-helm apps/<app> | kubectl apply -n <namespace> -f -

Testen von Anwendungen lokal (z.B. mit Podman)
#

Eine Anwendung außerhalb des Clusters ausprobieren, etwa unter Podman:

1helm template <projekt> bjw-s-labs/app-template --values <datei.yaml> | podman play kube -

Beitrag und Richtlinien
#

Die Konventionen für Commits und Änderungen stehen in CONTRIBUTING.md. Für die READMEs unter apps/ gilt der gemeinsame Aufbau: Quelle, Dokumentation, Funktion, Lokale Anpassungen, Installation, Abhängigkeiten.

Diese Dateien werden als Hugo-Modul in die öffentliche Webseite eingebunden. Was hier steht, ist damit öffentlich — Zugangsdaten, interne Adressen und Hostnamen gehören nicht hinein.

Lizenz
#

Siehe LICENSE.