Zum Hauptinhalt springen
Version: Weekly Build

Jumpbox vorbereiten und Konfiguration erzeugen

Bevor du beginnst​

Die Hosts aus Hosts bereitstellen sollten von der Jumpbox aus per SSH erreichbar, getunt und zeitsynchronisiert sein.

Die Jumpbox vorbereiten​

Installiere OMS zusammen mit sops und age auf der Jumpbox. Fixiere und verifiziere freigegebene Versionen, damit die Umgebung reproduzierbar ist.

Die Jumpbox muss über genügend freien Speicherplatz für das Installer-Paket und die extrahierten Installationsabhängigkeiten verfügen. Lege ein nur für Root zugängliches Secrets-Verzeichnis an:

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ühren wird:

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

Der API-Key muss für weitere OMS-Portal-Operationen gesetzt bleiben. Stelle ihn über einen genehmigten Secret-Manager oder ein geschütztes Sitzungs-Setup bereit, und committe ihn nicht in ein Shell-Profil, Image oder Quell-Repository.

Zugriff auf die GitHub Container Registry vorbereiten​

Codesphere-Images werden direkt von der GitHub Container Registry bezogen. Jeder k0s-Knoten benötigt ausgehenden HTTPS-Zugriff auf ghcr.io und die zugehörigen GitHub-Paket-Endpunkte.

Fordere den GHCR-Benutzernamen und -Token bei Codesphere an, bevor du die Installationskonfiguration erzeugst. 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. Vorerst stellt Codesphere separate GHCR-Zugangsdaten bereit, und der Token muss dem Konfigurationserzeugungs-Workflow als Registry-Passwort übergeben werden. Eine zukünftige Version wird die OMS-Portal-Authentifizierung für den Registry-Zugriff verwenden, wodurch das Anfordern und Konfigurieren eines separaten GHCR-Tokens entfällt.

Halte den Token für den Konfigurationserzeugungs-Schritt bereit, schreibe ihn aber nicht in den Shell-Verlauf oder in config.yaml. Speichere ihn nur in prod.vault.yaml als registryPassword, wie unten gezeigt. Nicht authentifizierte Pulls oder ein Token ohne Paketzugriff führen zum Scheitern der Plattforminstallation.

Die Installationskonfiguration und Secrets erzeugen​

Der OMS-Befehl zur Konfigurationserzeugung ist oms init install-config. Er erzeugt beide vom Installer benötigten Eingaben:

  • config.yaml beschreibt Infrastruktur, Netzwerk, Storage, Registry, Domains, Authentifizierungs-Provider, Pläne und aktivierte Features. Siehe Konfigurationsreferenz des Private-Cloud-Installers für die vollständige Feldstruktur.
  • prod.vault.yaml enthält generierte Passwörter, private Schlüssel, Zertifikate und Provider-Zugangsdaten. Sie ist bei der Erzeugung unverschlüsselt 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 Arbeitsstation 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, sodass sich die Installation an unterschiedlich große Infrastruktur anpassen lässt. Es stellt keine Maschinen bereit und entscheidet nicht automatisch, wie viele PostgreSQL-, Ceph-, Control-Plane- oder Worker-Knoten verwendet werden. Der Assistent oder die Befehlsflags müssen weiterhin die tatsächliche Topologie und IP-Adressen beschreiben.

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

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

Optionales Ansible-Inventory

Nutzer, die die Host-Topologie bereits in einem Ansible-Inventory pflegen, können es mit --ansible-inventory inventory.yaml importieren. OMS liest die optionalen Gruppen k8s-cp, k8s-workers und ceph; jeder Host benötigt eine private_ip. Zum 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 speist das Profil den Assistenten, während einzelne nicht-interaktive Konfigurationsflags nicht angewendet werden. Übergib für Automatisierung --interactive=false und stelle jeden erforderlichen Wert über Flags und das Profil bereit. Behandle einen nicht-interaktiven Validierungsfehler als fehlende oder inkonsistente Eingabe, statt ihn zu umgehen.

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

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

Setze im Rahmen der Erzeugung der Installationskonfiguration die vorhandenen Registry-Einträge in prod.vault.yaml auf den von Codesphere bereitgestellten GHCR-Benutzernamen und -Token. Der 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 absichtlich im Feld password des vom Installer verwendeten Secret-Formats gespeichert. Halte beide Werte im Vault und platziere den 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 besitzen soll.

Setze kubernetes.managedByCodesphere auf false und ersetze die verwaltungsbezogenen Felder 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 von Workspace-Netzwerkrichtlinien verwendet; ein falscher Wert blockiert Workspace-Traffic oder lässt ihn übermäßig zu. apiServerHost, controlPlanes und workers gelten nur für die Codesphere-verwaltete Option und werden hier nicht verwendet.

Stelle den Administratorzugriff auf den Cluster als Secret kubeConfig in prod.vault.yaml bereit, statt 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 nicht auf andere Weise die Verwaltung des Clusters. Vor dem Deployment überprüft OMS nur, dass das Secret kubeConfig vorhanden ist und die Kubernetes-Serverversion des Clusters die Mindestversionsanforderungen erfüllt (dieselbe Hauptversion und eine Nebenversion, die mindestens der konfigurierten Mindestversion des Installers entspricht). Es ist kein --skip-steps-Flag nötig, um die k0s-Installation zu überspringen; OMS überspringt sie automatisch basierend auf managedByCodesphere.

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 vom Cluster bereits bereitgestellten Lastverteilungs- oder Ingress-Mechanismus ab.

Die erzeugte Konfiguration überprüfen​

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

  • dataCenter enthält die beabsichtigte ID, Name, Stadt und Ländercode.

  • secrets.baseDir ist /etc/codesphere/secrets, wenn dieser Aufbau verwendet wird.

  • postgres.primary enthält Hostname und private IP von PostgreSQL, 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, mit genau einem initialen Master.

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

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

  • kubernetes.apiServerHost ist die private IP des ersten Control-Plane-Knotens oder eine stabile Lastverteiler-Adresse bzw. ein DNS-Name bei mehreren Control-Plane-Knoten.

  • kubernetes.controlPlanes und kubernetes.workers weisen jedem k0s-Knoten seine beabsichtigte 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. Dedizierte Worker-Adressen kommen unter workers; erweitere diese Liste für den erwarteten Workload an CPU, Memory und Ausfalltoleranz.

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

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

    Um statt der k0s-Installation einen bestehenden Kubernetes-Cluster zu verwenden, siehe Einen bestehenden Kubernetes-Cluster verwenden.

  • Die Platform- und Public-Gateways verwenden LoadBalancer oder ExternalIP, je nach gewählter Integration. Siehe Gateway und Lastverteilung.

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

  • codesphere.workspaceHostingBaseDomain und die CNAME-Basis für benutzerdefinierte Domains sind <dc-id>.<base-domain>, der Hostname, der per Wildcard zum Workspace-Gateway geroutet wird.

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

  • ACME oder ein anderer Zertifikats-Issuer ist für das gewählte DNS- und Lastverteilungs-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 Identity-Provider.

  • 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 Lastverteilungs-Implementierung unterstützt werden, oder lasse Annotationen weg, wenn die Implementierung loadBalancerIP direkt berücksichtigt.

Diesen Schritt verifizieren​

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

Was du jetzt haben solltest​

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

Weiter geht's​

Weiter geht es mit Secrets verschlüsseln und DNS konfigurieren.