Infrastruktur vorbereiten und Codesphere installieren

Diese Anleitung beschreibt, wie Infrastruktur für Codesphere vorbereitet wird, ohne von einem bestimmten Cloud-Anbieter abhängig zu sein.

Wähle zunächst die POC- oder Produktions-Topologie unten aus und erhöhe anschließend die Kapazität entsprechend der erwarteten Nutzerzahl, der Anzahl an Workspaces, des Speicherverbrauchs und der gewünschten Ausfalltoleranz.

Was die Installation aufbaut​

Die Installation nutzt eine Jumpbox als einzigen Einstiegspunkt in ein privates Netzwerk. Von dort aus installiert und konfiguriert OMS PostgreSQL, Ceph, k0s und die Codesphere-Plattform.

administrator
    |
    | SSH
    v
jumpbox
    |
    +-- PostgreSQL node
    +-- 3 or more Ceph nodes
    `-- 3 or more k0s nodes

Internet
    |
    +-- platform gateway IP       -> cs.<base-domain> and *.cs.<base-domain>
    +-- workspace gateway IP      -> <dc-id>.<base-domain> and *.<dc-id>.<base-domain>
    `-- workspace SSH proxy IP    -> *.<dc-id>.ssh.<base-domain>

Der Installer kann PostgreSQL, Ceph und Kubernetes auf diesen Maschinen verwalten. Alternativ kann in der Installationskonfiguration auch eine externe PostgreSQL-Datenbank oder ein bestehender Kubernetes-Cluster angegeben werden, diese Alternativen liegen jedoch außerhalb der in dieser Anleitung behandelten Topologie.

Erforderliche Angaben zusammenstellen​

Lege Folgendes fest, bevor irgendetwas bereitgestellt wird:

• Eine Basisdomain, deren DNS-Zone geändert werden kann.
• Eine Datacenter-ID, einen Namen, eine Stadt und einen Ländercode.
• Stabile private IP-Adressen für jede Maschine.
• Eine öffentliche IP-Adresse für die Jumpbox. Diese ist von den Service-Adressen getrennt und sollte SSH-Zugriffe nur aus vertrauenswürdigen Administrator-Netzwerken zulassen.
• Drei stabile, extern erreichbare Service-IP-Adressen: Platform Gateway, Workspace Gateway und Workspace SSH Proxy.
• Von Codesphere bereitgestellte GitHub Container Registry-Zugangsdaten. Codesphere-Nodes beziehen Images derzeit direkt von ghcr.io, daher müssen Kunden den erforderlichen Benutzernamen und Token bei Codesphere anfragen.
• Zugang zum Codesphere Package Portal.
• Optional eine E-Mail-Adresse für den ersten Cluster-Administrator.
• OAuth-Zugangsdaten für jeden Git-Provider oder OIDC-Provider, den Nutzer verwenden werden.
• Einen SSH-Schlüssel mit administrativem Zugriff auf alle Hosts.

Git-Provider-Zugangsdaten müssen als vollständige Sätze angegeben werden. Zum Beispiel benötigt eine GitHub App ihren App-Namen, die Client-ID und das Client-Secret; ein OIDC-Provider benötigt seine Issuer-URL, Client-ID und das Client-Secret.

Maschinen bereitstellen​

Stelle x86-64-Maschinen bereit und wähle eine Topologie entsprechend dem Zweck der Installation.

Mindestunterstützte Versionen​

Codesphere erfordert:

• Ubuntu 22.04 LTS oder eine neuere unterstützte Version
• Kubernetes 1.31 oder neuer
• Ceph 18.2 oder neuer

Die Mindestanforderungen für Kubernetes und Ceph gelten auch, wenn diese Komponenten außerhalb von OMS installiert oder verwaltet werden.

POC-Topologie​

Verwende diese kompakte Topologie für Proof-of-Concepts, Evaluierungen und andere Nicht-Produktionsumgebungen:

Alle drei k0s-Nodes nehmen an der Control Plane teil und stellen zusätzlich Workload-Kapazität bereit. Diese Topologie hält die Anzahl der Maschinen gering, bietet aber nicht denselben Wartungs- und Ausfallspielraum wie die Produktions-Topologie. Verwende sie nicht für Produktions-Workloads.

Produktions-Baseline​

Verwende in der Produktion getrennte Pools für Control Plane und Worker. Beginne mit:

Drei Control-Plane-Nodes sorgen für Control-Plane-Quorum und Hochverfügbarkeit. Beginne den separaten Worker-Pool mit mindestens drei Maschinen mit 16 vCPU und 64 GiB RAM und skaliere diesen anschließend entsprechend der Workload-CPU, des Arbeitsspeichers, des Scheduling-Spielraums und der Anzahl gleichzeitiger Node-Ausfälle, die die Plattform tolerieren muss. Skaliere Ceph über vier Nodes hinaus und füge Daten-Disks entsprechend der Ziel-Nutzkapazität, des Replikations-Overheads, des Recovery-Spielraums und des Wachstums hinzu.

Verwende 250 GiB Ceph-Daten-Disks als POC-Minimum und 500 GiB Daten-Disks als Produktions-Minimum. Stelle Ceph-DB/WAL- und Daten-Disks als eigenständige, ungenutzte Block-Devices bereit; formatiere oder mounte sie nicht. Validiere für die Produktion die Disk-Performance und dimensioniere das DB/WAL-Device entsprechend der ausgewählten Daten-Devices und des Workloads.

Verwende dedizierten PostgreSQL-Speicher und eine Replica, wenn Datenbankverfügbarkeit erforderlich ist. Die POC-Topologie hält PostgreSQL auf seiner Root-Disk und verzichtet auf eine Replica.

Notiere den Hostnamen und die private IP jedes Hosts. Hostnamen müssen eindeutig und konsistent auflösbar sein, entweder über internes DNS oder /etc/hosts.

Privates Netzwerk konfigurieren​

Platziere alle Maschinen in einem privaten, gerouteten Netzwerk. Verwende beispielsweise 10.10.0.0/20. Jeder nicht überlappende private CIDR-Bereich ist geeignet, sofern derselbe CIDR-Bereich als ceph.nodesSubnet in der Installationskonfiguration hinterlegt wird.

Stelle uneingeschränkte Kommunikation zwischen Codesphere-Hosts im privaten Netzwerk sicher. Kubernetes-, Ceph-, PostgreSQL-, Container-Registry- und SSH-Traffic laufen alle über dieses Netzwerk. Wenn interne Firewalls restriktiv sein müssen, leite eine explizite Port-Matrix für die ausgewählten Kubernetes- und Ceph-Versionen ab und teste sie vor der Installation.

Hosts ohne öffentliche Adressen benötigen ausgehenden Zugriff über NAT oder einen HTTP-Proxy. Sie müssen Paket-Repositorys, die ausgewählte Container-Registry, Zertifikats-Endpunkte und alle vom Installer referenzierten Quell-URLs erreichen können.

Vermeide CIDR-Überlappungen zwischen dem Host-Netzwerk, dem Kubernetes-Pod-Netzwerk, dem Kubernetes-Service-Netzwerk, verbundenen Unternehmensnetzwerken und VPNs.

Externen Zugriff und Firewalls konfigurieren​

Reserviere drei stabile externe Adressen und verbinde sie mit Kubernetes-LoadBalancer-Diensten über die Load-Balancer-Implementierung der Infrastruktur:

1. Das Platform Gateway bedient HTTP und HTTPS.
2. Das öffentliche Workspace Gateway bedient HTTP- und HTTPS-Traffic für Workspaces.
3. Der Workspace SSH Proxy bedient SSH-Traffic für Workspaces.

Installiere und konfiguriere in einer Public Cloud den Kubernetes Cloud Controller bzw. die Load-Balancer-Integration des jeweiligen Anbieters. Bei Bare Metal oder anderer Infrastruktur ohne native Implementierung konfiguriere MetalLB mit einem Adresspool, der die reservierten Adressen enthält. Die Adressen müssen über Service- und Node-Neustarts hinweg stabil bleiben. Wenn die Integration erst abgeschlossen werden kann, nachdem Kubernetes läuft, schließe sie unter Infrastrukturintegration abschließen ab.

Wende folgende Firewall-Regeln an der Netzwerkgrenze an:

Exponiere SSH oder PostgreSQL nicht gegenüber 0.0.0.0/0. PostgreSQL TCP 5432 muss normalerweise nur von Codesphere-Hosts und freigegebenen Administrations- oder Monitoring-Netzwerken erreichbar sein.

Administrativen SSH-Zugriff einrichten​

Konfiguriere die Jumpbox als einzigen öffentlichen SSH-Einstiegspunkt. Die Jumpbox muss sich als administrativer Benutzer mit jedem privaten Host verbinden können, und die Hosts müssen sich, wo von Ceph und der k0s-Installation gefordert, untereinander verbinden können.

Der Installationsworkflow verwendet direktes Root-SSH und SSH-Agent-Forwarding. Falls die Organisationsrichtlinie Root-SSH untersagt, stelle einen gleichwertigen privilegierten Automatisierungspfad bereit und verifiziere ihn vor der weiteren Durchführung mit dem Installer. Schütze den privaten Schlüssel, beschränke eingehenden Zugriff auf vertrauenswürdige Quellbereiche und verwende in einem Produktionsworkflow Host-Key-Verifizierung.

Überprüfe von der Jumpbox aus jeden Host:

ssh root@<postgres-private-ip> hostname
ssh root@<ceph-private-ip> hostname
ssh root@<k0s-private-ip> hostname

Jeden Installations-Host abstimmen​

Wende die folgenden Kernel-Einstellungen auf den PostgreSQL-, Ceph- und k0s-Hosts an und mache sie dauerhaft:

cat >/etc/sysctl.d/99-codesphere.conf <<'EOF'
fs.inotify.max_user_watches=1048576
fs.inotify.max_user_instances=8192
vm.max_map_count=262144
EOF

sysctl --system

Überprüfe die aktiven Werte:

sysctl fs.inotify.max_user_watches
sysctl fs.inotify.max_user_instances
sysctl vm.max_map_count

Halte die Zeit auf jedem Host synchron. Stelle vor der Installation von Codesphere sicher, dass Hostnamen, private Adressen, angeschlossene Disks, DNS-Auflösung, ausgehende Konnektivität und SSH-Zugriff einen Neustart überstehen.

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 genügend freien Speicherplatz für das Installer-Paket und extrahierte Installationsabhängigkeiten haben. Erstelle ein nur für Root zugängliches Secrets-Verzeichnis:

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

Installer-Pakete werden immer über das Codesphere Package Portal 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 gesetzt bleiben. Stelle ihn über einen freigegebenen Secret Manager oder eine geschützte Sitzungseinrichtung bereit und committe ihn nicht in ein Shell-Profil, Image oder Quell-Repository.

Zugriff auf GitHub Container Registry vorbereiten​

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

Fordere den GHCR-Benutzernamen und -Token bei Codesphere an, bevor die Installationskonfiguration erzeugt wird. Von Kunden selbst erstellte GitHub Personal Access Tokens haben nicht automatisch Zugriff auf die privaten Codesphere-Packages.

Die Registry-Authentifizierung befindet sich derzeit in einer Übergangsphase. Vorerst stellt Codesphere separate GHCR-Zugangsdaten bereit, und der Token muss dem Workflow zur Erzeugung der Installationskonfiguration 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 den Token für den Konfigurationserzeugungsschritt bereit, schreibe ihn aber nicht in die Shell-History oder config.yaml. Speichere ihn nur wie unten gezeigt in prod.vault.yaml als registryPassword. Nicht authentifizierte Pulls oder ein Token ohne Package-Zugriff führen dazu, dass die Plattforminstallation fehlschlägt.

Installationskonfiguration und Secrets erzeugen​

Der OMS-Befehl zur Konfigurationserzeugung 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, Authentifizierungs-Provider, Pläne und aktivierte Funktionen.
• prod.vault.yaml enthält generierte Passwörter, private Schlüssel, Zertifikate und Provider-Zugangsdaten. Sie liegt bei der Erzeugung 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-Nodes verwendet werden. Der Assistent oder die Befehls-Flags müssen weiterhin die tatsächliche Topologie und die IP-Adressen beschreiben.

Die Profile verhalten sich derzeit wie folgt:

Das von dev und minimal verwendete noRequests-Ressourcenprofil entfernt CPU- und Memory-Requests von Codesphere-Diensten und unterstützenden Charts. Außerdem reduziert es mehrere unterstützende Komponenten auf eine Replica, einschließlich Ingress-Controller, Loki-Komponenten, RGW-Load-Balancer und Managed-Service-Backends. Ausgewählte Kern-Codesphere-Dienste behalten zwei Replicas, ihre Ressourcen-Requests werden jedoch auf null gesetzt. Dadurch akzeptiert der Kubernetes-Scheduler einen kleineren Cluster, es entfallen jedoch Ressourcengarantien und die Ausfalltoleranz sinkt. Interpretiere ein erfolgreiches Scheduling mit diesem Profil nicht als Beleg dafür, dass die Hosts unter Last über ausreichend tatsächliche CPU oder Arbeitsspeicher verfügen.

Alle Profile starten mit denselben gemeinsamen Infrastruktur-Standardwerten, einschließlich Codesphere-verwaltetem Kubernetes, installiertem PostgreSQL, Ceph, LoadBalancer-Gateways, deaktiviertem MetalLB und Platzhalter-Localhost-Adressen. Sie starten außerdem mit den Standard-Workspace- und Hosting-Plan-Vorgaben. Ersetze alle Platzhalterwerte für Topologie, Domain, Registry und Secrets während des Assistenten oder der Konfigurationsüberprüfung.

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

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 dient das Profil als Grundlage für den Assistenten, während einzelne nicht-interaktive Konfigurations-Flags nicht angewendet werden. Übergib für Automatisierung --interactive=false und stelle jeden erforderlichen Wert über Flags und das Profil bereit. Behandle einen Fehler bei der nicht-interaktiven Validierung 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 als Teil 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 bewusst im password-Feld gespeichert, das vom Installer-Secret-Format verwendet wird. Bewahre beide Werte im Vault auf und platziere den Token niemals direkt in config.yaml.

Überprüfe die erzeugten 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 stimmt mit dem privaten Host-Netzwerk überein.

• ceph.hosts listet drei Hosts für einen POC oder mindestens vier Hosts für die 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-Devices aus.

• kubernetes.apiServerHost ist die private IP des ersten Control-Plane-Nodes, oder eine stabile Load-Balancer-Adresse bzw. ein DNS-Name bei mehreren Control-Plane-Nodes.

• kubernetes.controlPlanes und kubernetes.workers weisen jedem k0s-Node seine vorgesehene Rolle zu. Die Produktions-Baseline verwendet drei dedizierte Control-Plane-Nodes 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 gehören unter workers; erhöhe diese Liste entsprechend der erwarteten Workload-CPU, des Arbeitsspeichers und der Ausfalltoleranz.

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

  k0s unterstützt kombinierte Control-Plane-/Worker-Nodes. Der aktuelle OMS-k0sctl-Konfigurationsgenerator behandelt eine in beiden Listen vorhandene IP jedoch als reinen Control-Plane-Eintrag 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.

• Das Platform Gateway und die öffentlichen Gateways verwenden LoadBalancer, oder ExternalIP, wenn dies die gewählte Integration ist.

• codesphere.domain ist cs.<base-domain>.

• codesphere.workspaceHostingBaseDomain und die CNAME-Basis für benutzerdefinierte Domains sind <dc-id>.<base-domain>.

• 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.

• Git-Provider- und OIDC-Redirect-URLs verwenden die finale Adresse https://cs.<base-domain>.

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

Secrets verschlüsseln und ablegen​

Erzeuge eine age-Identität auf der Jumpbox und mache sie nur für Root lesbar:

age-keygen -o /etc/codesphere/secrets/age_key.txt
chmod 0600 /etc/codesphere/secrets/age_key.txt

Kopiere die erzeugten Dateien auf die Jumpbox und verschlüssele dort anschließend den Vault:

install -m 0600 config.yaml /etc/codesphere/config.yaml
install -m 0600 prod.vault.yaml /etc/codesphere/secrets/prod.vault.yaml

sops --encrypt --in-place \
  --age "$(age-keygen -y /etc/codesphere/secrets/age_key.txt)" \
  /etc/codesphere/secrets/prod.vault.yaml

Sichere config.yaml, den verschlüsselten Vault und die age-Identität in einem freigegebenen Secret-Speicher. Die age-Identität wird benötigt, um die Installation wiederherzustellen oder zu aktualisieren. Committe niemals den Klartext-Vault oder die age-Identität in die Versionsverwaltung.

DNS konfigurieren​

Erstelle diese Einträge, nachdem die drei stabilen Adressen zugewiesen wurden:

Verwende während der Ersteinrichtung eine kurze TTL wie 300 Sekunden. Je nach DNS-Anbieter und Netzwerkdesign können die Einträge A/AAAA-, Alias- oder Load-Balancer-Einträge sein. Stelle sicher, dass der Zertifikats-Solver DNS bei Verwendung von DNS-01 aktualisieren kann, oder dass TCP 80 das Platform Gateway bei Verwendung von HTTP-01 erreicht.

Einige Cloud-Controller- und Load-Balancer-Integrationen weisen externe IP-Adressen erst zu, nachdem Kubernetes und die Provider-Integration laufen. Wenn die drei Adressen noch nicht bekannt sind, verschiebe das Erstellen und Verifizieren dieser Einträge auf Infrastrukturintegration abschließen und kehre danach mit den zugewiesenen Adressen zu dieser Tabelle zurück. Andernfalls verifiziere jeden Eintrag von außerhalb des privaten Netzwerks, bevor du fortfährst.

Installer-Paket beziehen​

Durchsuche die verfügbaren Codesphere-Packages und lade den ausgewählten Installer-Build auf der Jumpbox herunter:

oms list packages
oms download package --version <version>

Codesphere installieren​

Codesphere benötigt ein Secrets-Verzeichnis, aber oms install codesphere verfügt über kein separates --secrets-dir-Flag. Lege das Verzeichnis in /etc/codesphere/config.yaml fest:

secrets:
  baseDir: /etc/codesphere/secrets

Das konfigurierte Verzeichnis sollte mit dem Verzeichnis übereinstimmen, das die über --vault übergebene Datei enthält. Bestätige vor der Installation, dass das Verzeichnis und die erforderlichen Dateien vorhanden und nur für Root lesbar sind:

install -d -m 0700 /etc/codesphere/secrets
chmod 0600 /etc/codesphere/secrets/age_key.txt
chmod 0600 /etc/codesphere/secrets/prod.vault.yaml
test -r /etc/codesphere/secrets/age_key.txt
test -r /etc/codesphere/secrets/prod.vault.yaml

Führe die Installation von der Jumpbox aus durch. Das Lite-Paket enthält nicht die Container-Images der Plattform, überspringe daher load-container-images; der Cluster bezieht sie direkt von GHCR unter Verwendung der Zugangsdaten im Vault:

oms install codesphere \
  --config /etc/codesphere/config.yaml \
  --priv-key /etc/codesphere/secrets/age_key.txt \
  --vault /etc/codesphere/secrets/prod.vault.yaml \
  --package <downloaded-installer-lite-package>.tar.gz \
  --skip-steps load-container-images

Installationsschritte überspringen​

Übersprungene Schritte machen den Installer fortsetzbar und ermöglichen die Arbeit mit Voraussetzungen, die bereits installiert oder außerhalb von OMS verwaltet werden. Sie sind auch nützlich, wenn nach einer Konfigurationsänderung nur eine spätere Phase erneut ausgeführt werden soll. Ein übersprungener Schritt wird von OMS nicht validiert oder ersetzt. Überspringe ihn daher nur, wenn sein Ergebnis bereits vorhanden oder bewusst nicht erforderlich ist; das Überspringen einer erforderlichen Voraussetzung kann einen späteren Schritt fehlschlagen lassen.

Verwende --skip-steps für einen einzelnen Aufruf, mit mehreren durch Kommas getrennten Namen. Um Überspringungen über zukünftige Läufe hinweg dauerhaft zu machen, füge sie zu config.yaml hinzu:

operations:
  skip:
    - load-container-images

Die unterstützten Namen für zu überspringende Schritte sind:

Das vollständige Installer-Paket ist veraltet. Aktuelle Installationen sollten installer-lite.tar.gz verwenden und load-container-images überspringen. Der Schritt bleibt nur aus Kompatibilitätsgründen mit älteren vollständigen Paketen verfügbar.

Für die Installation in dieser Anleitung wird nur load-container-images übersprungen, da installer-lite.tar.gz keine Plattform-Images enthält. Übernimm keine anderen Skip-Schritte in einen erneuten Lauf, ohne zu prüfen, welche Voraussetzungen bereits vorhanden sind.

Der kombinierte Befehl installiert in dieser Reihenfolge:

1. Kopiert und extrahiert Abhängigkeiten.
2. Überspringt das Laden mitgelieferter Container-Images, da die Nodes sie von GHCR beziehen.
3. Installiert SOPS und die Container-Runtime-Abhängigkeiten.
4. Installiert oder konfiguriert PostgreSQL.
5. Installiert und konfiguriert Ceph.
6. Installiert und konfiguriert k0s, wenn Kubernetes von Codesphere verwaltet wird.
7. Installiert Argo CD, Cluster-Abhängigkeiten und Managed-Service-Backends.
8. Installiert die Codesphere-Plattform.

Die Installation kann auch als separate Phasen infra, dependencies und platform ausgeführt werden, wenn die betriebliche Änderungskontrolle eigene Kontrollpunkte erfordert.

Infrastrukturintegration abschließen​

Wenn die ausgewählte Infrastruktur einen Kubernetes Cloud Controller benötigt, installiere dessen unterstützte Provider-Integration und aktiviere den externen Cloud-Provider-Modus auf dem k0s-Controller und den Workern. Verwende nur Manifeste und Service-Annotationen, die für diese Infrastruktur vorgesehen sind.

Bestätige, dass die drei Dienste die reservierten Adressen erhalten:

alias kubectl='/etc/codesphere/deps/kubernetes/files/k0s kubectl' 
kubectl get services -n codesphere -o wide | grep LoadBalancer

Die Dienste gateway-controller, public-gateway-controller und ssh-workspace-proxy müssen ihre vorgesehenen Adressen behalten. Wenn die Load-Balancer-Implementierung sie nicht aus config.yaml zuweist, patche oder annotiere die Dienste über den von dieser Implementierung unterstützten Mechanismus und mache die Änderung anschließend in der Installationskonfiguration dauerhaft.

Falls die DNS-Konfiguration verschoben wurde, weil diese externen Adressen zuvor nicht verfügbar waren, erstelle und verifiziere jetzt die unter DNS konfigurieren beschriebenen Einträge.

Installation überprüfen​

Führe folgende Prüfungen durch, bevor die Umgebung übergeben wird:

1. Alle k0s-Nodes sind Ready.
2. Ceph meldet einen gesunden Zustand, und alle erwarteten OSDs sind auf allen drei POC-Hosts bzw. mindestens vier Produktions-Hosts vorhanden.
3. Die drei Load-Balancer-Dienste besitzen die reservierten externen Adressen.
4. https://cs.<base-domain> präsentiert ein vertrauenswürdiges Zertifikat und lädt Codesphere.
5. Ein Workspace kann erstellt, über HTTPS erreicht und über den Workspace-SSH-Proxy erreicht werden.

Führe den Codesphere-Smoke-Test aus, sobald ein API-Schlüssel für die Umgebung verfügbar ist:

oms smoketest codesphere --help

Anhang​

Codesphere-Plänekonfiguration​

Pläne definieren die für Entwickler-Workspaces verfügbaren Ressourcen. Konfiguriere diese im Abschnitt codesphere.plans in der config.yaml.

• hostingPlans: Definiert rohe Ressourcenzuweisungen. IDs müssen Zahlen sein.
  • cpuTenth: CPU-Kerne in Zehnteln (z. B. 10 = 1 Kern, 25 = 2,5 Kerne).
  • gpuParts: GPU-Zuweisung (spezifisch für die jeweilige GPU-Konfiguration).
  • memoryMb: Arbeitsspeicher in Megabyte.
  • storageMb: Persistenter Speicher für den Workspace in Megabyte.
  • tempStorageMb: Flüchtiger Speicher in Megabyte.
  • pooledInstances: Anzahl vorab aufgewärmter Instanzen dieses Plans, die bereitgehalten werden.
• workspacePlans: Definiert vom Nutzer wählbare Pläne, die auf hostingPlans verweisen. IDs müssen Zahlen sein.
  • name: Anzeigename des Plans.
  • hostingPlanId: Verweist auf eine ID in hostingPlans.
  • maxReplicas: Maximale Anzahl gleichzeitiger Instanzen für einen einzelnen Workspace in diesem Plan.
  • onDemand: true, wenn Nutzer diese Workspaces starten/stoppen können, false für dauerhaft aktive Workspaces.

Beispiel: (bereits im Haupt-config.yaml-Beispiel enthalten)

codesphere:
  # ... other codesphere settings ...
  plans:
    hostingPlans:
      1:
        cpuTenth: 10
        gpuParts: 0
        memoryMb: 2048
        storageMb: 20480
        tempStorageMb: 1024
      2:
        cpuTenth: 20
        memoryMb: 4096
        storageMb: 51200
        tempStorageMb: 2048
    workspacePlans:
      1:
        name: "Basic"
        hostingPlanId: 1
        maxReplicas: 1
        onDemand: true
      2:
        name: "Pro"
        hostingPlanId: 2
        maxReplicas: 3
        onDemand: true

Git-Provider-Konfiguration​

Konfiguriere Git-Provider-Integrationen unter codesphere.gitProviders in config.yaml. Für jeden aktivierten Provider müssen auch die entsprechenden clientId- und clientSecret-Werte in der Secrets-Datei prod.vault.yaml hinzugefügt werden (siehe Abschnitt 3.2).

Allgemeine Struktur für jeden Provider:

# providerName e.g., github, gitlab
# providerName:
#   enabled: true # or false
#   url: "Base URL of the provider"
#   api:
#     baseUrl: "API base URL"
#   oauth:
#     issuer: "OAuth issuer URL"
#     authorizationEndpoint: "OAuth authorization URL"
#     tokenEndpoint: "OAuth token URL"
#     # Other provider-specific OAuth settings like scope, clientAuthMethod

Zugangsdaten erzeugen (Beispiele):​

• GitLab:

  1. Gehe zur GitLab-Gruppe (oder zu den Benutzereinstellungen für eine App auf Benutzerebene) > Settings > Applications.
  2. Erstelle eine neue Anwendung (z. B. "Codesphere Git Integration").
  3. Redirect URI / Callback URL: https://<codesphere.domain>/ide/auth/gitlab/callback (ersetze <codesphere.domain> durch die eigene Codesphere-Domain).
  4. Scopes: Wähle api, read_repository, write_repository. (Stelle sicher, dass openid, profile, email ebenfalls verfügbar/ausgewählt sind, falls für Nutzerprofil-Informationen benötigt).
  5. Speichere die Anwendung. Du erhältst eine "Application ID" (gitlabAppClientId) und ein "Secret" (gitlabAppClientSecret).

• GitHub:

  1. Gehe zu den GitHub-Organisationseinstellungen > Developer settings > GitHub Apps > New GitHub App.
  2. Application name: z. B. "Codesphere Git Integration"
  3. Homepage URL: https://<your-codesphere.domain>
  4. Authorization callback URL: https://<your-codesphere.domain>/ide/auth/github/callback
  5. Du erhältst eine "Client ID" (githubAppsClientId) und erzeugst ein "Client Secret" (githubAppsClientSecret).
  6. Optional kann ein Bild als Logo hochgeladen werden.

• Bitbucket (Server/Data Center - in der Regel Application Links für OAuth 1.0a oder OAuth 2.0, falls unterstützt):

  1. Admin Settings > System > Application Links.
  2. Erstelle einen neuen Link. Wähle "External Application", "Incoming".
  3. Redirect URL: https://<codesphere.domain>/ide/auth/bitbucket/callback
  4. Berechtigungen: Repository Lese-/Schreibzugriff.
  5. Du erhältst einen "Consumer Key" (bitbucketAppsClientId) und ein "Consumer Secret" (bitbucketAppsClientSecret) oder Ähnliches, je nach OAuth-Version.

• Azure DevOps:

  1. Registriere eine Anwendung in Azure Active Directory.
  2. Redirect URI: https://<codesphere.domain>/ide/auth/azureDevOps/callback (stelle sicher, dass sie als Web-Redirect-URI hinzugefügt wird).
  3. Notiere die "Application (client) ID" (azureDevOpsAppClientId).
  4. Gehe zu "Certificates & secrets" -> "New client secret", um azureDevOpsAppClientSecret zu erzeugen. Setze eine Erinnerung, dieses Secret zu rotieren, da es ein Ablaufdatum hat.
  5. API-Berechtigungen: Füge Berechtigungen für "Azure DevOps" -> user_impersonation hinzu und stelle sicher, dass vso.code_full im Scope in config.yaml enthalten ist.

Denke daran, diese Client-IDs und Secrets zur Datei prod.vault.yaml hinzuzufügen und sie zu verschlüsseln. Beispielnamen für Secrets:

• githubAppsClientId, githubAppsClientSecret
• gitlabAppClientId, gitlabAppClientSecret
• bitbucketAppsClientId, bitbucketAppsClientSecret
• azureDevOpsAppClientId, azureDevOpsAppClientSecret

Konfiguration von Managed Services​

Jeder über den Bereich Managed Services angebotene Dienst wird als einzelner Managed Service Provider im Array codesphere.managedServices in config.yaml konfiguriert. Die Konfiguration folgt einem bestimmten Schema.

Managed Service Providers können extern zu Codesphere sein, d. h. es wird eine externe API aufgerufen, es gibt aber auch integrierte Managed Services, bei denen der Provider innerhalb von Codesphere läuft. Mit dem aktuellen Release gibt es einen solchen Provider für PostgreSQL.

Codesphere wird mit einer Reihe vorkonfigurierter Provider ausgeliefert. Um einen dieser Provider zu aktivieren, gib einfach Name und Version an:

  managedServices:
    - name: postgres
      schemaVersion: v1
    - name: babelfish
      schemaVersion: v1
    - name: s3
      schemaVersion: v1
    - name: virtualK8sV1
      schemaVersion: v1

Wenn einer dieser Provider verwendet wird, stelle sicher, dass auch das entsprechende Backend im Abschnitt managedServiceBackends aktiviert ist.

Es ist möglich, Eigenschaften der vorkonfigurierten Provider zu überschreiben oder sogar eigene Provider zu implementieren und hinzuzufügen (siehe Eigenes REST-Backend erstellen). Der folgende Ausschnitt zeigt eine beispielhafte vollständige Konfiguration des Postgres-Managed-Service-Providers.

  managedServices:
    - name: postgres
      schemaVersion: v1
      backend:
        api:
          endpoint: "http://ms-backend-postgres.postgres-operator:3000/api/v1/postgres"
      author: Codesphere
      category: Database
      displayName: PostgreSQL
      iconUrl: /ide/assets/managed-services/postgresql.svg
      configSchema:
        type: object
        properties:
          version:
            type: string
            description: Version of the Postgres DB. Includes pre-installed extensions compatible with this version. Extension versions are managed and cannot be customized.
            enum:
              - '17.6'
              - '16.10'
            default: '17.6'
            readOnly: false
          userName:
            type: string
            default: app
            pattern: '^(?!postgres$)'
          databaseName:
            type: string
            default: app
        required: []
        additionalProperties: false
      detailsSchema:
        type: object
        properties:
          port:
            type: integer
          hostname:
            type: string
          dsn:
            type: string
          ready:
            type: boolean
        required:
          - port
          - hostname
          - dsn
          - ready
        additionalProperties: false
      secretsSchema:
        type: object
        properties:
          userPassword:
            type: string
            format: password
          superuserPassword:
            type: string
            format: password
        required:
          - userPassword
          - superuserPassword
        additionalProperties: false
      description: >-
        Open-source database system tailored for efficient data management and
        scalability. Deployed on Codesphere using the CNPG K8s Operator.
      plans:
        - id: 0
          description: 0.5 vCPU / 500 MB Memory
          name: Small
          parameters:
            storage:
              pricedAs: storage-mb
              schema:
                description: Storage (MB)
                type: integer
                default: 10000
                readOnly: false
            cpu:
              pricedAs: cpu-tenths
              schema:
                description: CPU Tenths
                type: number
                default: 5
                readOnly: true
            memory:
              pricedAs: ram-mb
              schema:
                description: Memory (MB)
                type: integer
                default: 500
                readOnly: true
        - id: 1
          description: 1 vCPU / 1 GB Memory
          name: Medium
          parameters:
            storage:
              pricedAs: storage-mb
              schema:
                description: Storage (MB)
                type: integer
                default: 25000
                readOnly: false
            cpu:
              pricedAs: cpu-tenths
              schema:
                description: CPU Tenths
                type: number
                default: 10
                readOnly: true
            memory:
              pricedAs: ram-mb
              schema:
                description: Memory (MB)
                type: integer
                default: 1000
                readOnly: true
        - id: 2
          description: 1 vCPU / 2 GB Memory
          name: Medium High-Mem
          parameters:
            storage:
              pricedAs: storage-mb
              schema:
                type: integer
                default: 25000
                readOnly: false
            cpu:
              pricedAs: cpu-tenths
              schema:
                type: number
                default: 10
                readOnly: true
            memory:
              pricedAs: ram-mb
              schema:
                type: integer
                default: 2000
                readOnly: true
        - id: 3
          description: 2 vCPU / 4 GB Memory
          name: Large
          parameters:
            storage:
              pricedAs: storage-mb
              schema:
                type: integer
                default: 50000
                readOnly: false
            cpu:
              pricedAs: cpu-tenths
              schema:
                type: number
                default: 20
                readOnly: true
            memory:
              pricedAs: ram-mb
              schema:
                type: integer
                default: 4000
                readOnly: true
        - id: 4
          description: 4 vCPU / 8 GB Memory
          name: Extra Large
          parameters:
            storage:
              pricedAs: storage-mb
              schema:
                type: integer
                default: 150000
                readOnly: false
            cpu:
              pricedAs: cpu-tenths
              schema:
                type: number
                default: 40
                readOnly: true
            memory:
              pricedAs: ram-mb
              schema:
                type: integer
                default: 8000
                readOnly: true

Benutzerdefinierte Workspace-Basis-Images erstellen​

Das Standard-Basis-Image für Workspaces bringt bereits viele nützliche Tools und Bibliotheken mit. Es ist jedoch möglich, eigene benutzerdefinierte Basis-Images zu erstellen. Ein Grund für die Anpassung von Basis-Images sind Pakete, die nicht über Nix verfügbar sind, aber über apt installiert werden müssen.

Das Codesphere-OMS CLI bietet eine praktische Möglichkeit, mit der Erstellung eigener benutzerdefinierter Basis-Images zu beginnen.

Voraussetzungen:

1. Installiere auf dem Host Docker und das Buildx-Plugin (falls noch nicht installiert):
   sudo apt install docker.io docker-buildx
2. Installiere die OMS CLI wie unter https://github.com/codesphere-cloud/oms beschrieben
3. Verwende den Befehl extend baseimage in der OMS CLI, siehe
   oms-cli beta extend baseimage -h
4. Dieser Befehl extrahiert das Standard-Basis-Image aus dem Codesphere-Installer-Bundle, lädt es in den lokalen Docker-Image-Cache und generiert ein Dockerfile, das erweitert werden kann.
5. Bestätige mit docker image ls, dass das Basis-Image (ghcr.io/codesphere-cloud/codesphere-monorepo/workspace-agent-VERSION) lokal verfügbar ist.
6. Bearbeite das generierte Dockerfile, um eigene Abhängigkeiten hinzuzufügen.
7. Als bewährte Vorgehensweise sollte das Dockerfile in einem Unterverzeichnis abgelegt werden, z. B. ./docker. Dies stellt sicher, dass beim folgenden Docker-Build-Befehl nur die notwendigen Dateien an den Docker-Daemon gesendet werden.
8. Ermittle das Basis-Image-Tag aus dem Dockerfile, z. B. codesphere-1-67-1-4dd9b346cc, und verwende dasselbe Tag für das eigene Image.
9. Baue das benutzerdefinierte Image mit folgendem Befehl:
   docker buildx build -f ./docker/custom.Dockerfile -t workspace-agent-24.04-mycorp:<TAG_TO_USE> --load ./docker
10. Tagge und push das Image mit demselben Tag wie das Original-Image in die eigene Registry:
    docker tag workspace-agent-24.04-mycorp:<TAG_TO_USE> <YOUR_REGISTRY_URL>/workspace-agent-24.04-mycorp:<TAG_TO_USE>
docker login <YOUR_REGISTRY_URL> # if not already logged in
docker push <YOUR_REGISTRY_URL>/workspace-agent-24.04-mycorp:<TAG_TO_USE>