Podlily einrichten

Um zu beginnen, klone das podlily Repository:

git clone https://0xacab.org/leap/container-platform/podlily.git

Das Repository enthält 4 Verzeichnisse:

• clusters: Eine Struktur, die alle Dateien enthält, die du benötigst, um die Backend- und Gateway-k3s-Cluster bereitzustellen und zu organisieren. Du wirst dich in diesem Verzeichnis bewegen, um deine Cluster zu installieren, bereitzustellen und zu verwalten.
• scripts: Skripte zum Erstellen von Zertifikaten für die TLS-Kommunikation zwischen Backend und Gateways und um sie den Deployments über Secrets zur Verfügung zu stellen.
• templates: Eine Kopie der Struktur in clusters, die Template-Dateien und Hilfsskripte enthält, um dir beim Einstieg in die Bereitstellung zu helfen.
• docs: Dokumentation zu podlily: Architektur, TLS-Zertifikate, Skripte. Wenn du auf Probleme bei der Befolgung dieses READMEs stößt, schau dir die Troubleshootingseite an.

Dieses README führt dich durch den Prozess der Einrichtung eines leap-backend k3s Clusters und eines leap-gateway k3s Clusters sowie der Installation von Monitoring auf ihnen.

Es basiert direkt auf diesen 4 Repositories im leap-Bereich:

• terraform-hetzner-k3s-vpn : Terraform-Modul mit Ressourcen zur Bereitstellung von Backend- und Gateway-k3s-Clustern mit Hetzner
• terraform-ovh-k3s-vpn : Terraform-Modul mit Ressourcen zur Bereitstellung von Backend- und Gateway-k3s-Clustern mit OVH
• leap-backend: Helm-Chart für leap-backend
• leap-gateway : Helm-Chart für leap-gateway

Bitte schau dir deren Dokumentation für zusätzliche Informationen an.

Du musst folgende Programme installiert haben:

• helm3 (https://helm.sh/docs/intro/install/)
• terraform (https://developer.hashicorp.com/terraform/install)
• kubectl (https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)

Bitte kopiere alle Dateien unter templates/backend/helm und templates/backend/scripts an die entsprechenden Orte in der Dateistruktur unter clusters. Wähle den Cloud-Provider aus, den du verwenden möchtest, und kopiere die entsprechende Terraform-Template-Datei nach clusters/backend/terraform.

Wechsle in clusters/backend/terraform. Hier befindet sich die Terraform-Datei, die deinen Backend-Cluster definiert. Je nach dem gewählten Cloud-Provider, folge den Schritten in dem README von entweder terraform-hetzner-k3s-vpn oder terraform-ovh-k3s-vpn, um einen Multi-Node-Backend-Cluster bereitzustellen. Am Ende solltest du einen k3s-Cluster haben, das läuft und bereit ist.

Um einfachen Zugriff auf den Cluster von deinem Rechner aus zu haben, kannst du das Skript clusters/backend/scripts/access_cluster.sh verwenden. Es erstellt einen SSH-Tunnel zum Controller-Knoten, mit dem du Cluster-Ressourcen von deinem lokalen Rechner aus erstellen und verwalten kannst. Du kannst die Dokumentation für dieses Skript im docs-Ordner finden.

Um es zu verwenden, wechsle in clusters/backend und führe aus

eval $(./scripts/access_cluster.sh --start)

Überprüfe, ob dein Cluster gesund ist und du Zugriff darauf hast, indem du ausführst

kubectl get nodes -o wide

Wenn du die Standardwerte gewählt hast, solltest du die 3 Knoten sehen, die du bereitgestellt hast.

Erstelle einen A-Record-Subdomain und verweise ihn auf die öffentliche IP des Controller-Knotens deines Backend-Clusters. Du kannst diese IP über die Cloud-Provider-Konsole herausfinden oder durch das Betrachten der Ausgabe deines terraform apply-Befehls oder durch Suchen nach ‘k3s_controller_ip’ in clusters/backend/terraform/terraform.tfstate. Es gibt mehrere Dienste im Internet, mit denen du kostenlos Subdomains erstellen kannst.

Konfiguriere deinen Provider im Abschnitt ‘Provider configuration’.Überprüfe auch alle Zeilen mit ⚠️:Fülle deine neu erstellte Subdomain in domain ein.Gib eine gültige E-Mail in acme/email ein, um Erinnerungen an die Erneuerung des TLS-Zertifikats zu erhalten.Füge einen zufälligen String unter MENSHEN_AGENT_SHARED_KEY hinzu. Dies ermöglicht die Kommunikation zwischen menshen im Backend und menshen-agent in Gateway-Clustern. Stelle sicher, dass du einen ausreichend langen zufälligen String verwendest, z. B. mit pwgen -s 30 1. Weitere Informationen darüber, was bereitgestellt wird und welche Konfigurationsoptionen zur Verfügung stehen, findest du in der README.

Dieses Skript generiert 2 Zertifikatsketten. Eine ist die Provider-CA und die andere ist die Menshen-CA. Führe das Skript im Basisverzeichnis aus:

bash scripts/gen-provider-certs.sh

Es wird dich nach 3 Dingen fragen:* Certificate output directory: Du kannst optional ein anderes Ausgabeverzeichnis für die vom Skript erstellten Secrets wählen* Provider CA subject: Optional kannst du einen Betreff für die CA-Generierung festlegen* Menshen domain: Setze dies auf die Domain, die du in diesem Schritt erstellt hast Du wirst die erstellten Zertifikate im Ausgabeverzeichnis sehen, das du gewählt hast, oder in einem neu erstellten Top-Level-Verzeichnis namens secrets.

Das nächste Skript erstellt Secrets im Backend-Cluster, die die neu erstellten Zertifikate enthalten. Wechsle in das Top-Level-Verzeichnis und führe aus:

bash scripts/create-backend-secrets.sh

Du wirst zweimal aufgefordert:* Certificates directory: Das im letzten Schritt erstellte, standardmäßig secrets* Kubernetes namespace: Der Namespace, in dem du die Secrets erstellen möchtest. Er muss mit dem Namespace übereinstimmen, in dem du menshen bereitstellen wirst, aber ‘default’ ist auch in Ordnung.

Jetzt können wir endlich alle Backend-Services bereitstellen, indem wir in clusters/backend/helm wechseln und ausführen

helm upgrade --install -f ./values.yaml leap-backend https://0xacab.org/api/v4/projects/6134/packages/generic/helm-chart/v0.1.1/provider-backend-v0.1.1.tgz

Du kannst überprüfen, ob alles reibungslos läuft, indem du die Pods überprüfst:

kubectl get pods

Du solltest 2 laufende Pods sehen: provider-backend-menshen und traefik.

Du kannst auch überprüfen, ob die Services wie erwartet laufen, indem du mit der Menshen-API herumspielst. Du findest die Dokumentation hier.

Erstelle noch eine A-Record-Subdomain, die auf die gleiche IP-Adresse deines Controller-Knotens verweist. Du kannst sie nennen, wie du möchtest, musst sie aber in clusters/backend/helm/monitoring.values.yaml konfigurieren. Vorerst nennen wir sie <prom.yourdomain.com>.

Fülle deine neu erstellte Prometheus-Subdomain und alle anderen Zeilen, die mit ⚠️ gekennzeichnet sind, aus. Weitere Informationen findest du in der offiziellen kube-prometheus-stack README.

Du musst ein Secret einrichten, um den Prometheus-Endpunkt auf deinem Backend zu sichern, auf den Grafana Alloy auf den Gateways schreiben wird. Vorerst kannst du eine Umgebungsvariable verwenden. Stelle sicher, dass du einen ausreichend langen zufälligen String verwendest, z. B. mit pwgen -s 30 1. Ersetze dann <your-password> durch das sichere Passwort und führe aus:

export REMOTE_WRITE_PASSWORD=<your-password>

Stelle sicher, dass du dieses Passwort irgendwo sicher speicherst, da du es später benötigen wirst. Das Skript erstellt das Secret, um deinen Prometheus-Endpunkt zu sichern, installiert kube-prometheus-stack und erstellt ein benutzerdefiniertes Dashboard in Grafana für Gateway-Metriken. Damit es funktioniert, benötigst du Zugriff auf deinen Backend-Cluster, also stelle sicher, dass du clusters/backend/scripts/access_cluster.sh erneut ausführst, falls nötig. Wenn kubectl-Befehle deine Cluster-Ressourcen anzeigen, wechsle in clusters/backend und führe aus:

./scripts/deploy_monitoring.sh

Nach der Bereitstellung kannst du die neu laufenden Pods überprüfen:

kubectl get pods -n monitoring

Da das kube-prometheus-stack-Chart und alle Monitoring-Ressourcen in einem neuen Namespace monitoring installiert wurden, stelle sicher, dass du immer -n monitoring zu kubectl-Befehlen hinzufügst, die für Monitoring-Ressourcen bestimmt sind.

Du kannst auf Grafana mit dem bereitgestellten Skript zugreifen. Es gibt dein Grafana-Passwort aus und startet Port-Forwarding der Grafana-Instanz, die auf deinem Cluster läuft, zu localhost. In clusters/backend führe aus:

bash scripts/port_forward_grafana.sh

Um die Dashboards anzuschauen, öffne einfach diesen Port in deinem Browser: http://localhost:3000/

Wenn du zum ersten Mal besuchst, gib ‘admin’ als Benutzernamen und das vom Skript ausgegebene Passwort an. Unter Dashboards findest du alle Standard-Dashboards von kube-prometheus-stack, die dir tonnenweise Informationen über die Gesundheit deines Clusters geben, plus eines für die Überwachung von Gateway-Metriken. Dies wird leer sein, bis du irgendwelche Gateways bereitgestellt hast, was der nächste Schritt ist.

Kopiere alle Dateien unter templates/gateway/helm und templates/gateway/scripts an die entsprechenden Stellen in deinem clusters-Verzeichnis. Wähle den Cloud-Provider aus, den du für diesen Gateway nutzen möchtest, und kopiere die entsprechende Terraform-Template-Datei nach clusters/gateway/terraform. Wenn du vorhast, mehr als einen Gateway bereitzustellen, ist es sinnvoll, clusters/gateway in einen aussagekräftigeren Namen umzubenennen, damit du sie später nicht verwechselst.

Wechsle in das Verzeichnis clusters/gateway/terraform. Hier befindet sich die Terraform-Datei, die deinen Gateway-Cluster definiert. Je nachdem, welchen Cloud-Provider du gewählt hast, folge den Schritten im README von entweder terraform-hetzner-k3s-vpn oder terraform-ovh-k3s-vpn, um einen Single-Node-Gateway-Cluster zu erstellen. Am Ende solltest du einen k3s-Cluster mit einem Node haben, der läuft.

Bevor du auf den Gateway-Cluster zugreifst, musst du die Port-Weiterleitung zu deinem Backend-Cluster stoppen, falls sie noch aktiv ist. Wechsle zu clusters/backend und führe aus:

./scripts/access_cluster.sh --stop

Dann gehe zurück zu clusters/gateway und greife auf deinen neu bereitgestellten Cluster zu:

eval $(./scripts/access_cluster.sh --start)

Überprüfe erneut, dass dein Single-Node-Cluster läuft mit:

kubectl get nodes -o wide

Du kannst die Konfiguration aller Gateway-Deployments in dieser Datei ändern: openvpn, obfsvpn, ovpn-addons und menshenAgent. Für weitere Hilfe zur Konfiguration dieser Services schau in die leap-gateway-Dokumentation.

Damit das Gateway-Deployment funktioniert, ist es notwendig, alle Zeilen auszufüllen, die mit ⚠️ gekennzeichnet sind:

• obfsvpn.OBFSVPN_LOCATION oder menshenAgent.location: Der Standort deines bereitgestellten Gateway-Servers in Kleinbuchstaben, z.B. london
• obfsvpn.MENSHEN_URL oder menshenAgent.menshenUrl_: Die URL zu dem Domänennamen, den du für deinen Backend-Controller-Node registriert hast, z.B. ‘https://thisis.yourdomain.com’
• obfsvpn.MENSHEN_SHARED_KEY oder menshenAgent.presharedKey: Der gemeinsame Schlüssel, der in backend/helm/values.yaml unter menshen.env.MENSHEN_AGENT_SHARED_KEY konfiguriert ist
• obfsvpn.OBFSVPN_HOSTNAME: Wähle einen eindeutigen Bezeichner für den Gateway. Er wird an den Client übergeben, also sollte der Name nicht zu viel über die zugrunde liegende Infrastruktur verraten.
• menshenAgent.externalIp: Die Floating IP, die deinem Gateway-Server zugewiesen ist. Schau sie in der Konsole deines Cloud-Providers nach. Falls du keine Floating IP zugewiesen hast, nimm einfach die öffentliche IP deines Gateway-Controller-Nodes.

Dieses Skript erstellt OpenVPN-Gateway-Zertifikate, die von der Provider-CA signiert sind, die von Clients verwendet werden, um die Authentizität von Gateways zu überprüfen.

Es ist notwendig, dass Provider-Zertifikate bereits erstellt wurden. Wir gehen davon aus, dass sie im Top-Level-Verzeichnis secrets verfügbar sind. Falls sie fehlen, führe zunächst scripts/gen-provider-certs.sh aus. Die Anleitung für dieses Skript findest du hier.

Führe im Top-Level-Verzeichnis podlily aus:

bash scripts/gen-gateway-certs.sh

Zu folgenden Angeben wirst du aufgefordert:

• Provider CA certificate path: Der Pfad, wo die Zertifikate gespeichert sind. Der Standard sollte korrekt sein, falls du den Pfad im gen-provider-certs-Skript nicht geändert hast
• Menshen CA certificate path: dasselbe
• Provider CA key path: dasselbe
• Gateway domain or a unique name for the gateway: Wähle einen eindeutigen Namen für deinen Gateway
• Certificates output directory: Der Standard ist gut, aber du kannst auch einen anderen Ort wählen, falls du möchtest

Falls alles wie erwartet funktioniert, solltest du ein neues Verzeichnis unter secrets sehen, das nach deinem Gateway-Namen benannt ist.

Das nächste Skript erstellt Secrets aus den Zertifikaten, die gerade erstellt wurden, damit die Deployments auf dem k3s-Cluster sie nutzen können.

Stelle sicher, dass du Zugriff auf deinen Gateway-Cluster hast (`kubectl get nodes` funktioniert) und führe aus:

bash scripts/create-gateway-secrets.sh

Du wirst aufgefordert:

• Certificates directory: Falls du es in den vorherigen Skripten nicht geändert hast, ist der Standard korrekt
• Kubernetes namespace: Der Namespace, in dem die Secrets erstellt werden. Muss mit dem Namespace übereinstimmen, in dem leap-gateway bereitgestellt wird. ‘default’ ist in Ordnung
• Gateway domain: Wähle den Gateway-Namen oder die Domain aus, für die du die Zertifikate im vorherigen Schritt generiert hast

Wechsle zu clusters/gateway/helm, fülle deinen Gateway-Namen oder deine Domain in den folgenden Befehl ein und führe ihn aus:

helm upgrade --install -f ./gw.values.yaml <your-gateway-name> https://0xacab.org/api/v4/projects/6095/packages/generic/helm-chart/v0.1.3/leap-gateway-v0.1.3.tgz

Du kannst überprüfen, ob alles reibungslos läuft, indem du die Pods überprüfst:

kubectl get pods

Du solltest 4 Pods sehen, die laufen: menshen-agent, obfsvpn, openvpn-tcp und openvpn-udp.

Damit der Bitmask-Client den am nächsten befindlichen Gateway vorschlagen kann und den korrekten Gateway-Standort anzeigt, benötigt die Menshen-Instanz, die auf dem Backend-Cluster läuft, allgemeine Informationen über den Gateway-Standort. Dieser Schritt geht darum, Menshen mit diesen Informationen zu versorgen.

Stoppe die Port-Weiterleitung zum Gateway-Cluster, indem du zu clusters/gateway wechselst und ausführst:

./scripts/access_cluster.sh --stop

Dann gehe zurück zu clusters/backend und greife auf diesen Cluster zu:

eval $(./scripts/access_cluster.sh --start)

Allgemeine Standortinformationen werden in einer ConfigMap gespeichert, die von Menshen genutzt wird. Bearbeite sie, indem du ausführst:

kubectl edit cm eip-service-config

Dies öffnet die ConfigMap in einem Editor. Finde diese Zeilen:

      "locations": {
        "seattle": {
          "country_code": "US",
          "hemisphere": "N",
          "name": "Seattle",
          "timezone": "-7"
        },
        "amsterdam": {
          "country_code": "NL",
          "hemisphere": "N",
          "name": "Amsterdam",
          "timezone": "+1"
        }
      }

Das ist das JSON-Format, in dem Standorte von Menshen gelesen werden. Du kannst entweder einen der Beispielstandorte bearbeiten oder deinen Standort hinzufügen, indem du den Beispielen folgst, innerhalb der “locations”-Klammern.

Achte darauf, dass der Schlüssel komplett in Kleinbuchstaben geschrieben ist und mit den Variablen obfsvpn.OBFSVPN_LOCATION und menshenAgent.location übereinstimmt, die in clusters/gateway/helm/gw.values.yaml in diesem Schritt konfiguriert sind. Das name-Attribut ist der Name der Stadt, den die Bitmask-App für deinen Gateway anzeigt. Das timezone-Attribut beschreibt die Zeitzone im Vergleich zu UTC.

Achte auch besonders darauf, dass alles korrekt eingerückt ist, da Einrückungsfehler die Datei schnell für Menshen unlesbar machen können.

Speichere die geänderte Datei.

Anschließend musst du den Menshen-Pod neu starten, damit die Änderungen in Kraft treten. Finde zuerst den Pod-Namen heraus, indem du ausführst:

kubectl get pods

Kopiere den Namen des Pods, der mit ’leap-backend-provider-backend-menshen’ beginnt, und lösche ihn mit:

kubectl delete pod <pod-name>

Du kannst überprüfen, ob alles reibungslos funktioniert hat, indem du in deinem Browser `https://your.domain.com/api/5/service` eingibst und schaust, ob dein Standort korrekt im “locations”-Teil angezeigt wird.

Hurra, alles ist bereit, um dich mit deinem Gateway über die Bitmask-App zu verbinden. Füge im Provider-Auswahlmenü einen neuen Provider hinzu, indem du <your.domain.com> in das URL-Feld eingibst. Falls alles funktioniert hat, sollte Bitmask dich zu deinem neu bereitgestellten Gateway verbinden und den korrekten Standort anzeigen. Du kannst überprüfen, ob sich deine IP tatsächlich geändert hat, indem du https://myip.wtf in deinem Browser öffnest 🎉.

Fülle die Prometheus-Subdomain aus, die in diesem Schritt während der Backend-Monitoring-Installation erstellt wurde, sowie alle anderen Zeilen, die mit ⚠️ gekennzeichnet sind.

Weitere Alloy-Konfigurationsoptionen findest du in der offiziellen Dokumentation.

Um auf den gesicherten Prometheus-Endpunkt auf deinem Backend zu schreiben, nutzt Grafana Alloy Basic-Authentifizierung mit einem Benutzernamen und einem Passwort. Der Benutzername ist in alloy.values.yaml angegeben, das Passwort wird als Secret zur Verfügung gestellt. Es ist wichtig, das gleiche Passwort zu verwenden, das du aus diesem Grund in diesem Schritt während der Vorbereitung der Backend-Monitoring-Installation erstellt hast.

Ersetze erneut <your-password> durch das sichere Passwort und führe aus:

export REMOTE_WRITE_PASSWORD=<your-password>

Das Skript erstellt das Secret, welches das Authentifizierungspasswort für die Kommunikation mit dem Backend-Prometheus enthält, und installiert Grafana Alloy.

Damit es funktioniert, brauchst du Zugriff auf dein Gateway-Cluster sichstellen, also stelle sicher, dass du die Port-Weiterleitung zum Backend-Cluster stoppst und clusters/gateway/scripts/access_cluster.sh erneut ausführst. Dann wechsle zu clusters/gateway und führe aus:

./scripts/deploy_alloy.sh

Nach der Bereitstellung kannst du den neu laufenden Pod überprüfen:

kubectl get pods

Du solltest den alloy-Pod zusätzlich zu den 4 leap-gateway-Pods sehen.

Da Grafana auf dem Backend-Cluster läuft, musst du zunächst die Port-Weiterleitung zu deinem Gateway-Cluster stoppen, um darauf zuzugreifen. Wechsle zu clusters/gateway und führe aus:

./scripts/access_cluster.sh --stop

Folge dann den Anweisungen in diesem Schritt, um die Grafana-Instanz, die auf deinem Backend-Cluster läuft, weiterzuleiten.

Öffne das ‘Gateway metrics’-Dashboard, um Daten deiner Gateway(s) zu sehen. Alloy sammelt Metriken von den Nodes, die auf deinem Gateway-Cluster laufen, und schickt sie an den Prometheus-Endpunkt auf deinem Backend-Cluster, wodurch sie in Grafana sichtbar werden. Falls alles gut gelaufen ist, solltest du die Anzahl der verbundenen Clients und Informationen zu Traffic und Last sehen können, was dieses Dashboard zu einem wichtigen Werkzeug für die Überwachung der Gesundheit deiner Gateways macht.