Zum Hauptinhalt springen
Version: Weekly Build

Jumpbox vorbereiten und Konfiguration generieren

Bevor du beginnst​

Die Hosts aus Hosts bereitstellen sollten von der Jumpbox aus über SSH erreichbar, optimiert und zeitsynchronisiert sein.

Jumpbox vorbereiten​

Installiere OMS auf der Jumpbox zusammen mit sops und age, um den Secrets-Vault zu verschlüsseln.

Die Jumpbox muss über genügend freien Speicherplatz für das Installationspaket und die extrahierten Installationsabhängigkeiten verfügen. Erstelle ein nur für root zugängliches Secrets-Verzeichnis:

install -d -m 0700 /etc/codesphere/secrets

Installationspakete werden immer über das Codesphere-Paketportal durchsucht und heruntergeladen. Setze den Portal-API-Schlüssel in der Umgebung des Benutzers, der OMS auf der Jumpbox ausführt:

export OMS_PORTAL_API_KEY='<portal-api-key>'

Der API-Schlüssel muss für nachfolgende OMS-Portal-Operationen weiterhin gesetzt bleiben. Stelle ihn über einen zugelassenen Secret-Manager oder ein geschütztes Session-Setup bereit und committe ihn niemals in ein Shell-Profil, Image oder Quell-Repository.

Zugriff auf die GitHub Container Registry vorbereiten​

Codesphere-Images werden direkt aus der GitHub Container Registry gezogen. Jeder k0s-Knoten muss ausgehenden HTTPS-Zugriff auf ghcr.io und die zugehörigen GitHub-Package-Endpunkte haben.

Fordere den GHCR-Benutzernamen und das Token bei Codesphere an, bevor die Installationskonfiguration generiert wird. Von Kunden erstellte persönliche GitHub-Access-Tokens haben nicht automatisch Zugriff auf die privaten Codesphere-Pakete.

hinweis

Die Registry-Authentifizierung befindet sich derzeit in einer Übergangsphase. Aktuell stellt Codesphere separate GHCR-Zugangsdaten bereit, und das Token muss dem Konfigurationsgenerierungs-Workflow als Registry-Passwort übergeben werden. Eine zukünftige Version wird die OMS-Portal-Authentifizierung für den Registry-Zugriff verwenden, wodurch die Anforderung und Konfiguration eines separaten GHCR-Tokens entfällt.

Halte das Token für den Schritt der Konfigurationsgenerierung bereit, schreibe es aber nicht in den Shell-Verlauf oder in config.yaml. Speichere es nur in prod.vault.yaml als registryPassword, wie unten gezeigt. Nicht authentifizierte Pulls oder ein Token ohne Paketzugriff führen dazu, dass die Plattforminstallation fehlschlägt.

Installationskonfiguration und Secrets generieren​

Der OMS-Befehl für die Konfigurationsgenerierung lautet oms init install-config. Er erstellt beide vom Installer benötigten Eingaben:

  • config.yaml beschreibt die Infrastruktur, das Netzwerk, den Speicher, die Registry, Domains, Authentifizierungsanbieter, Pläne und aktivierte Funktionen. Die vollständige Feldstruktur findet sich in der Referenz zur Private-Cloud-Installer-Konfiguration.
  • prod.vault.yaml enthält generierte Passwörter, private Schlüssel, Zertifikate und Provider-Zugangsdaten. Sie liegt bei der Erstellung im Klartext vor und muss verschlüsselt werden, bevor sie gespeichert oder über ein nicht vertrauenswürdiges System kopiert wird.

Führe den interaktiven Generator von einer vertrauenswürdigen Workstation oder der Jumpbox aus:

oms init install-config \
  --profile production \
  --config config.yaml \
  --vault prod.vault.yaml \
  --with-comments

Ein Installationskonfigurationsprofil wählen​

Das Profil steuert den standardmäßigen Codesphere-Software-Fußabdruck und ermöglicht es der Installation, sich an unterschiedlich große Infrastrukturen anzupassen. Es provisioniert keine Maschinen und entscheidet nicht automatisch, wie viele PostgreSQL-, Ceph-, Control-Plane- oder Worker-Knoten verwendet werden sollen. Der Assistent oder die Befehlsoptionen müssen weiterhin die tatsächliche Topologie und die IP-Adressen beschreiben.

Die vollständige Profilvergleichstabelle sowie das dabei angewendete noRequests-Ressourcenprofil findest du unter Installationsschritte und Profile.

Verwende production für die Produktions-Baseline und minimal für die POC-Topologie. Verwende dev nur, wenn es sinnvoll ist, die mitgelieferten Monitoring-Komponenten zu deaktivieren.

Optionales Ansible-Inventar

Nutzer, die die Host-Topologie bereits in einem Ansible-Inventar pflegen, können dieses mit --ansible-inventory inventory.yaml importieren. OMS liest die optionalen Gruppen k8s-cp, k8s-workers und ceph; jeder Host benötigt eine private_ip. Beispiel:

k8s-cp:
  hosts:
    cp-1:
      private_ip: 10.10.0.11
k8s-workers:
  hosts:
    worker-1:
      private_ip: 10.10.0.21
ceph:
  hosts:
    ceph-1:
      private_ip: 10.10.0.31

Der interaktive Modus ist standardmäßig aktiviert. In diesem Modus liefert das Profil die Ausgangswerte für den Assistenten, während einzelne nicht-interaktive Konfigurationsoptionen nicht angewendet werden. Für Automatisierung --interactive=false übergeben und jeden erforderlichen Wert über Optionen und das Profil bereitstellen. Behandle einen Validierungsfehler im nicht-interaktiven Modus als fehlende oder inkonsistente Eingabe, anstatt ihn zu umgehen.

Setze nach der Generierung den Registry-Abschnitt in config.yaml auf:

registry:
  server: ghcr.io
  replaceImagesInBom: false
  loadContainerImages: false

Setze als Teil der Generierung der Installationskonfiguration die vorhandenen Registry-Einträge in prod.vault.yaml auf den von Codesphere bereitgestellten GHCR-Benutzernamen und das Token. Das Token ist das Registry-Passwort:

secrets:
  - name: registryUsername
    fields:
      password: <codesphere-provided-ghcr-username>
  - name: registryPassword
    fields:
      password: <codesphere-provided-ghcr-token>

Der Benutzername wird bewusst im password-Feld gespeichert, das vom Installer-Secret-Format verwendet wird. Bewahre beide Werte im Vault auf und platziere das Token niemals direkt in config.yaml.

Einen bestehenden Kubernetes-Cluster verwenden​

Bringe einen bereits laufenden Kubernetes-Cluster mit, anstatt OMS k0s installieren zu lassen. Dies gilt für einen cloud-verwalteten Cluster, einen von einem anderen Tool bereitgestellten Cluster oder jeden Cluster, dessen Lebenszyklus Codesphere nicht verwalten soll.

Setze kubernetes.managedByCodesphere auf false und ersetze die Felder für den verwalteten Cluster durch die tatsächlichen Pod- und Service-Netzwerkbereiche des Clusters:

kubernetes:
  managedByCodesphere: false
  podCidr: "100.96.0.0/11"     # Pod-Netzwerk-CIDR des bestehenden Clusters
  serviceCidr: "100.64.0.0/13" # Service-Netzwerk-CIDR des bestehenden Clusters

podCidr und serviceCidr sind für diese Option erforderlich und haben keine Standardwerte. Sie müssen mit den tatsächlichen Netzwerkbereichen des Clusters übereinstimmen, da Codesphere sie zur Konfiguration der Workspace-Netzwerkrichtlinien verwendet; ein falscher Wert blockiert den Workspace-Traffic oder gewährt zu weitreichende Berechtigungen. apiServerHost, controlPlanes und workers gelten nur für die von Codesphere verwaltete Option und werden hier nicht verwendet.

Stelle den Administratorzugriff auf den Cluster als kubeConfig-Secret in prod.vault.yaml bereit, anstatt Control-Plane- und Worker-Hosts zu provisionieren:

secrets:
  - name: kubeConfig
    file:
      name: kubeConfig # Interner Name, muss nicht mit einem Dateinamen übereinstimmen
      content: |
        apiVersion: v1
        kind: Config
        clusters:
        - cluster:
            certificate-authority-data: ...
            server: https://<your-k8s-api-server>
          name: external-cluster
        contexts:
        - context:
            cluster: external-cluster
            user: external-admin
          name: external-context
        current-context: external-context
        users:
        - name: external-admin
          user:
            client-certificate-data: ...
            client-key-data: ...

Die kubeconfig muss Zugriff auf Administratorebene gewähren. OMS verwendet sie direkt, um Argo CD, Cluster-Abhängigkeiten, Managed-Service-Backends und die Codesphere-Plattform zu installieren; es erstellt, ändert oder übernimmt anderweitig nicht die Verwaltung des Clusters. Vor dem Deployment prüft OMS nur, ob das kubeConfig-Secret vorhanden ist und ob die Kubernetes-Serverversion des Clusters die minimal unterstützten Versionen erfüllt (dieselbe Hauptversion und eine Nebenversion, die der konfigurierten Mindestversion des Installers entspricht oder darüber liegt). Es ist kein --skip-steps-Flag erforderlich, um die k0s-Installation zu überspringen; OMS überspringt sie automatisch basierend auf managedByCodesphere.

Prüfe den Cluster vor der Installation auf einen bereits vorhandenen monitoring-Namespace — Codesphere geht davon aus, diesen Namespace zu besitzen, und das Auflösen eines Konflikts mit einem bereits vorhandenen Namespace ist nach der Installation kein einfaches Umbenennen mehr; siehe Cluster-Monitoring.

Setze außerdem ceph.csiKubeletDir auf das tatsächliche kubelet-Verzeichnis des Clusters (zum Beispiel /var/lib/kubelet bei den meisten Nicht-k0s-Distributionen) anstelle des k0s-Standardwerts /var/lib/k0s/kubelet, und schließe die Infrastrukturintegration abschließen mit dem Load-Balancer- oder Ingress-Mechanismus ab, den der Cluster bereits bereitstellt.

Die generierte Konfiguration überprüfen​

Überprüfe die generierten Dateien und stelle sicher, dass sie die tatsächliche Infrastruktur beschreiben:

  • dataCenter enthält die vorgesehene ID, den Namen, die Stadt und den Ländercode.

  • secrets.baseDir ist /etc/codesphere/secrets, wenn diesem Layout gefolgt wird.

  • postgres.primary enthält den PostgreSQL-Hostnamen und die private IP, oder postgres.mode beschreibt die externe Datenbank.

  • ceph.nodesSubnet entspricht dem privaten Host-Netzwerk.

  • ceph.hosts listet drei Hosts für einen POC oder mindestens vier Hosts für die Produktion auf, mit genau einem initialen Master.

  • ceph.csiKubeletDir ist /var/lib/k0s/kubelet, wenn Codesphere k0s verwaltet.

  • Jede Ceph-OSD-Definition wählt nur die vorgesehenen, leeren Daten- und DB/WAL-Geräte aus.

  • kubernetes.apiServerHost ist die private IP des ersten Control-Plane-Knotens oder eine stabile Load-Balancer-Adresse bzw. ein DNS-Name, wenn mehrere Control-Plane-Knoten verwendet werden.

  • kubernetes.controlPlanes und kubernetes.workers weisen jedem k0s-Knoten seine vorgesehene Rolle zu. Die Produktions-Baseline verwendet drei dedizierte Control-Plane-Knoten und einen separaten Worker-Pool:

    kubernetes:
      managedByCodesphere: true
      apiServerHost: 10.10.0.11
      controlPlanes:
        - ipAddress: 10.10.0.11
        - ipAddress: 10.10.0.12
        - ipAddress: 10.10.0.13
      workers:
        - ipAddress: 10.10.0.14
        - ipAddress: 10.10.0.15
        - ipAddress: 10.10.0.16

    Liste für eine hochverfügbare Control Plane immer mindestens drei Adressen unter controlPlanes auf. Dedizierte Worker-Adressen kommen unter workers; erweitere diese Liste entsprechend der erwarteten CPU- und Speicherauslastung sowie der gewünschten Ausfalltoleranz der Workloads.

    Der interaktive Assistent oms init install-config fragt separat nach den kommagetrennten Control-Plane- und Worker-IPs.

    k0s unterstützt kombinierte Control-Plane-/Worker-Knoten. Der aktuelle OMS-k0sctl-Konfigurationsgenerator behandelt jedoch eine IP, die in beiden Listen vorkommt, als reinen Control-Plane-Knoten und ignoriert den doppelten Worker-Eintrag. Bis die Generierung kombinierter Rollen von OMS unterstützt wird, verwende in diesem Workflow dedizierte Einträge für Control-Plane und Worker.

  • Die Plattform- und öffentlichen Gateways verwenden LoadBalancer oder ExternalIP, je nachdem, welche Integration gewählt wurde. Siehe Gateway und Load Balancing.

  • codesphere.domain ist <base-domain> und löst sich zum Plattform-Gateway auf.

  • codesphere.workspaceHostingBaseDomain und die Basis für den Custom-Domain-CNAME sind <dc-id>.<base-domain>, der Hostname mit Wildcard zum Workspace-Gateway.

  • Die Workspace-SSH-Proxy-Anwendung ist aktiviert und ihre reservierte Adresse zugewiesen.

  • ACME oder ein anderer Zertifikatsaussteller ist für das gewählte DNS- und Load-Balancer-Design konfiguriert; siehe Optionen für Cluster-Ingress-CA.

  • Git-Provider- und OIDC-Redirect-URLs verwenden die endgültige https://<base-domain>-Adresse; siehe Git-Provider und Identitätsanbieter.

  • Alle benötigten Einträge unter codesphere.internal/experiments, codesphere.preview oder pcApps sind vorhanden — oms init install-config generiert diese Abschnitte nicht, sie müssen manuell hinzugefügt werden; siehe Feature-Flags.

  • Der Registry-Server ist ghcr.io, replaceImagesInBom und loadContainerImages sind false, und der Vault enthält gültige Einträge für registryUsername und registryPassword.

Verwende nur Annotationen, die von der gewählten Load-Balancer-Implementierung unterstützt werden, oder lasse Annotationen weg, wenn die Implementierung loadBalancerIP direkt berücksichtigt.

Diesen Schritt überprüfen​

oms init install-config --validate --config config.yaml --vault prod.vault.yaml

Dieser Befehl benötigt zur Ausführung ein erreichbares Secrets-Backend; ist zu diesem Zeitpunkt im Ablauf noch keins verfügbar, verlasse dich stattdessen auf die oben genannte Prüfliste.

Was du jetzt haben solltest​

  • OMS, sops und age auf der Jumpbox installiert.
  • config.yaml und prod.vault.yaml generiert und anhand der obigen Prüfliste überprüft.
  • Von Codesphere bereitgestellte Registry-Zugangsdaten für den Vault vorbereitet.

Weiter​

Fahre fort mit Secrets-Vault vorbereiten und DNS konfigurieren.