Zum Hauptinhalt springen
Version: Weekly Build

Vorbereitung der Jumpbox und Generierung der Konfiguration

Bevor du beginnst​

Die Hosts aus Hosts bereitstellen sollten über SSH von der Jumpbox aus erreichbar, angepasst 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 ausreichend freien Speicherplatz für das Installer-Paket und die extrahierten Installationsabhängigkeiten verfügen. Erstelle ein nur für root zugängliches Secrets-Verzeichnis:

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

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

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

Der API-Key muss für nachfolgende OMS-Portal-Vorgänge gesetzt bleiben. Stelle ihn über einen genehmigten Secret-Manager oder ein geschütztes Sitzungssetup bereit und committe ihn nicht in ein Shell-Profil, ein Image oder ein 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 von Codesphere an, bevor die Installationskonfiguration generiert wird. Von Kunden selbst erstellte GitHub Personal 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 Install-Configuration-Workflow als Registry-Passwort übergeben werden. Eine zukünftige Version wird für den Registry-Zugriff die OMS-Portal-Authentifizierung verwenden, wodurch das Anfordern und Konfigurieren eines separaten GHCR-Tokens entfällt.

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

Installationskonfiguration und Secrets generieren​

Der OMS-Befehl zur Konfigurationsgenerierung ist 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 Features. Siehe Referenz zur Private-Cloud-Installer-Konfiguration für die vollständige Feldstruktur.
  • prod.vault.yaml enthält generierte Passwörter, private Schlüssel, Zertifikate und Anbieter-Zugangsdaten. Sie liegt bei der Generierung 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-Footprint und ermöglicht es, die Installation an unterschiedlich große Infrastrukturen anzupassen. Es stellt keine Maschinen bereit und entscheidet nicht automatisch, wie viele PostgreSQL-, Ceph-, Control-Plane- oder Worker-Knoten verwendet werden sollen. Der Assistent oder die Befehls-Flags müssen weiterhin die tatsächliche Topologie und die IP-Adressen beschreiben.

Siehe Installationsschritte und Profile für die vollständige Profilvergleichstabelle und das dabei angewendete noRequests-Ressourcenprofil.

Verwende production für die Produktionsbasis und minimal für die POC-Topologie. Verwende dev nur, wenn das Deaktivieren der mitgelieferten Monitoring-Komponenten angemessen ist.

Optionales Ansible-Inventar

Wer die Host-Topologie bereits in einem Ansible-Inventar pflegt, kann 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 dient das Profil als Ausgangsbasis für den Assistenten, während einzelne nicht-interaktive Konfigurations-Flags nicht angewendet werden. Für die Automatisierung --interactive=false übergeben und jeden benötigten Wert über Flags und das Profil bereitstellen. Behandle einen nicht-interaktiven Validierungsfehler als fehlende oder inkonsistente Eingabe, statt ihn zu umgehen.

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

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

Setze im Rahmen der Install-Config-Generierung die bestehenden 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 Feld password 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, statt 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 den tatsächlichen Netzwerkbereichen des Clusters entsprechen, da Codesphere sie zur Konfiguration der Workspace-Netzwerkrichtlinien verwendet; ein falscher Wert blockiert oder erlaubt Workspace-Traffic zu großzügig. 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 bereitzustellen:

secrets:
  - name: kubeConfig
    file:
      name: kubeConfig # Interner Name, muss keinem Dateinamen entsprechen
      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; sie erstellt, ändert oder übernimmt den Cluster ansonsten nicht in dessen Verwaltung. Vor dem Deployment prüft OMS lediglich, 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 nötig, um die k0s-Installation zu überspringen; OMS überspringt sie automatisch basierend auf managedByCodesphere.

Prüfe den Cluster vor der Installation auf einen bereits bestehenden monitoring-Namespace — Codesphere geht davon aus, diesen Namespace zu besitzen, und das Auflösen eines Konflikts mit einem bestehenden Namespace ist nach der Installation keine einfache Umbenennung; 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) statt des k0s-Standards /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 dieser Aufbau befolgt 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 Produktion, 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 bei Verwendung mehrerer Control-Plane-Knoten.

  • kubernetes.controlPlanes und kubernetes.workers weisen jedem k0s-Knoten seine vorgesehene Rolle zu. Die Produktionsbasis 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 unter controlPlanes immer mindestens drei Adressen für eine hochverfügbare Control Plane auf. Dedizierte Worker-Adressen kommen unter workers; erweitere diese Liste entsprechend der erwarteten CPU-, Speicher- und Ausfalltoleranzanforderungen der Workload.

    Der interaktive Assistent von oms init install-config fragt separat nach den durch Kommas getrennten Control-Plane- und Worker-IPs.

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

  • Das Plattform- und das öffentliche Gateway verwenden LoadBalancer oder ExternalIP, je nach gewählter Integration. Siehe Gateway und Lastverteilung.

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

  • codesphere.workspaceHostingBaseDomain und die Basis des CNAME für benutzerdefinierte Domains sind <dc-id>.<base-domain>, der als Platzhalter auf das Workspace-Gateway zeigende Hostname.

  • Die Workspace-SSH-Proxy-Anwendung ist aktiviert und ihrer reservierten Adresse zugewiesen.

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

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

  • Der E-Mail-Versand ist entweder über ein sendGridApiKey-Vault-Secret oder den Block codesphere.email und ein optionales smtpPassword-Vault-Secret konfiguriert, oder bewusst deaktiviert; siehe E-Mail-Versand.

  • 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; wenn an dieser Stelle im Ablauf noch keines verfügbar ist, verwende stattdessen die obige Überprüfungscheckliste.

Was du jetzt haben solltest​

  • OMS, sops und age auf der Jumpbox installiert.
  • config.yaml und prod.vault.yaml generiert und anhand der obigen Checkliste überprüft.
  • Registry-Zugangsdaten von Codesphere für den Vault bereitgestellt.

Nächster Schritt​

Weiter zu Secrets-Vault vorbereiten und DNS konfigurieren.