Zum Hauptinhalt springen
Version: Weekly Build

Konfigurieren einer Landscape

Eine Landscape definiert, wie Services bereitgestellt und verbunden werden. Du kannst Compute Runtimes (Reactives, Managed Containers, Cloud Native Deployments) und Managed Services hinzufügen und deren Ressourcen, Netzwerk und Umgebung konfigurieren. Für einen tieferen technischen Überblick siehe Landscapes & Workspaces.

Jede Konfiguration beginnt im Landscape Config Editor:

  1. Klicke im Workspace in der Seitenleiste auf Deploy, um die Deployment- und Ausführungsseite zu öffnen, und klicke dann auf Landscape Config Editor.
  2. Stelle sicher, dass das richtige CI Profile ausgewählt ist (z. B. default oder dev). Falls du eines erstellen musst, siehe Verwenden von CI Profiles.
  3. Klicke auf der rechten Seite des Bereichs Landscape Deployment auf die Schaltfläche + Add New Service und wähle den gewünschten Servicetyp aus.

Von hier aus kannst du deine Landscape über den visuellen Editor oder durch direktes Bearbeiten der Datei ci.yml konfigurieren.

Speichern von Service-Konfigurationen

Die Landscape-Config-UI verhält sich wie ein großes Formular, das deine ci.yml-Datei konfiguriert. Die Konfiguration kann nur auf der obersten Ebene des Formulars gespeichert werden.

Exportieren einer Landscape als vorgefertigte Images

Ein Profil mit schemaVersion: v0.5 kann als statischer Build exportiert werden: eine Sammlung von Container-Images plus einer reinen Run-Konfiguration, die in eine Registry gepusht wird und ohne das Source-Repository bereitgestellt werden kann. Siehe Static Builds.

Codesphere Reactives​

Codesphere Reactives sind die Flaggschiff-Runtime von Codesphere und lassen sich am besten als zustandsbehaftetes Serverless beschreiben. Sie kombinieren persistenten Dateisystemzugriff mit automatischer Freigabe von Ressourcen während inaktiver Phasen und nahezu sofortigem Start (im Millisekundenbereich). Für einen detaillierten Überblick siehe Runtimes.

Um ein Reactive hinzuzufügen, wähle Reactive Service im Servicetyp-Auswahlmenü aus und konfiguriere es anschließend anhand der folgenden Abschnitte.

Runtime-Konfiguration​

Landscape Config Editor mit Runtime-Konfigurationsfeldern für einen Reactive Service, einschließlich Ausführungsschritten, Basis-Image-Auswahl und Mounting-Pfaden.

Ausführungsschritte​

Ausführungsschritte definieren die Befehle, die beim Start deines Services ausgeführt werden. Diese Befehle laufen sequenziell ab und sollten deinen Anwendungsprozess starten.

So fügst du Ausführungsschritte hinzu:​
  1. Klicke auf + Add Execution Step
  2. Gib einen Namen für den Schritt ein (z. B. „Start Server“)
  3. Gib den auszuführenden Befehl ein (z. B. npm start oder node server.js)
  4. Wiederhole dies, falls weitere Schritte benötigt werden
Service-Ausführung

Der letzte Schritt sollte in der Regel ein langlaufender Prozess sein (wie ein Webserver). Wenn alle Befehle beendet werden, wird der Service als „unhealthy“ markiert: Der Service läuft zwar, aber seine Pipeline wird nicht mehr ausgeführt.

Basis-Image-Konfiguration​

Reactives verwenden standardmäßig ein von Codesphere gepflegtes, gemeinsames Ubuntu-Basis-Image (Codesphere Defaults). Dieses Image ist vorgewärmt und gepoolt, um nahezu sofortigen Start (im Millisekundenbereich) zu ermöglichen. Du kannst die Runtime-Umgebung anpassen, indem du Abhängigkeiten über Nix installierst. Für fortgeschrittene Anwendungsfälle gibt es zudem die Option Custom Base Image, die als Grundlage für Managed Containers dient.

Mounting-Pfade​

Standardmäßig mounten alle Reactive Services das gesamte Verzeichnis /home/user/app aus dem gemeinsamen Netzwerkdateisystem. Mithilfe der Einstellung Mounting Paths kannst du einen Service so einschränken, dass nur ein bestimmtes Unterverzeichnis gemountet wird.

Anwendungsfälle für Mount-Unterpfade:​
  • Isolierung des Dateizugriffs zwischen Services, um versehentliches Überschreiben zu verhindern
  • Verbesserte Sicherheit durch Einschränkung des Dateisystemzugriffs je Service
  • Organisation von Multi-Service-Architekturen mit dedizierten Verzeichnissen
warnung

Nur Dateien, die unter /home/user/app geschrieben werden, werden im Netzwerkdateisystem persistiert und zwischen allen Services geteilt. Dateien, die an anderer Stelle geschrieben werden, existieren nur auf der lokalen Festplatte des jeweiligen Pods und stehen anderen Services oder Replicas nicht zur Verfügung. Diese lokalen Dateien gehen auch bei Workspace-Neustarts verloren, die etwa durch Skalierung oder Codesphere-Updates ausgelöst werden können.

Ressourcen​

Ressourcen-Bereich des Landscape Config Editors mit Plan-Auswahl, Optionen für den Verfügbarkeitsmodus, Steuerung der Replica-Anzahl und geschätzter monatlicher Kostenübersicht.

Jeder Service verfügt über einen Ressourcenplan, der die zugewiesenen vCPUs, den Arbeitsspeicher und den Speicherplatz festlegt. Die verfügbaren Pläne und ihre Preise werden vom Cluster-Administrator konfiguriert und können je nach Installation variieren.

So konfigurierst du Ressourcen:​

  1. Wähle einen Plan aus der Liste aus (jeder Plan zeigt seine vCPU-, Arbeitsspeicher- und Speicherzuteilung)
  2. Lege den Availability-Modus fest:
    • Always on: Der Service läuft kontinuierlich, ideal für Produktions-Workloads
    • Off when unused: Der Service stoppt automatisch nach einer Phase der Inaktivität und startet neu, sobald auf die Domain oder den Workspace zugegriffen wird – ideal für Preview-Deployments oder Entwicklungsumgebungen
  3. Lege die Default Replicas-Anzahl für horizontale Skalierung über die Steuerelemente − / + fest
info

Der Screenshot zeigt unten eine Kostenübersicht mit geschätzten Kosten pro Ressource und den monatlichen Gesamtkosten. Dies ist möglicherweise nicht bei jeder Installation sichtbar.

Details zur Definition und Anpassung von Plänen findest du unter Workspace and Hosting Plans.

Skalierungsstrategien:​

TypBeschreibungAm besten geeignet für
Vertikale SkalierungErhöhung von vCPUs/Arbeitsspeicher durch Auswahl eines höheren PlansRechen- oder speicherintensive Workloads
Horizontale SkalierungHinzufügen mehrerer Replicas desselben ServicesBewältigung eines erhöhten Anfragevolumens

Netzwerkeinstellungen​

Bereich „Ports and Routes“ des Landscape Config Editors mit Health-Check-Einstellungen, exponierten Service-Ports und Pfadzuordnungen des Workspace Routers.

Health Check​

Standardmäßig pingt Codesphere deine Reactive Services auf Port 3000 an, um deren Zustand zu prüfen. Du kannst einen benutzerdefinierten Health-Endpoint konfigurieren, z. B. http://localhost:8080/health, falls deine Anwendung einen anderen Port oder Pfad für Health Checks verwendet. Die Anfrage wird zudem aus dem Service-Container heraus ausgeführt, sodass die Anwendung unter localhost erreichbar sein muss. Ist sie an eine andere Schnittstelle gebunden, gib stattdessen die passende IP-Adresse oder den Hostnamen an.

Routen und externe Erreichbarkeit

Ein Service ist von außerhalb der Landscape nur erreichbar, wenn Traffic zu ihm geroutet wird – entweder weil er das Landscape-Gateway ist oder weil eine Pfadzuordnung im Workspace Router auf ihn verweist. Services ohne Route bleiben für die anderen Services innerhalb der Landscape erreichbar.

Ports konfigurieren​

Dieser Abschnitt definiert die Ports, die dein Service exponiert. Andere Services innerhalb derselben Landscape erreichen diesen Service über diese Ports unter seinem internen Hostnamen. Siehe Landscape Networking für Details.

Den internen Hostnamen eines Services kannst du über die Copy-Schaltfläche auf der rechten Seite kopieren.

So exponierst du einen neuen Port:​
  1. Klicke rechts auf + Add New Port
  2. Gib die Port-Nummer ein, auf der deine Anwendung lauscht

Workspace Router​

In der UI des Services kannst du die Pfadzuordnungen des Services im Workspace Router konfigurieren. Jede Zuordnung leitet ein eingehendes HTTP-Pfadpräfix an einen der Ports des Services weiter.

Der Abschnitt Routing for Other Services am unteren Rand zeigt Routen, die von anderen Services innerhalb derselben Landscape definiert wurden – hilfreich, um Konflikte zu erkennen oder einen Überblick über die gesamte Routing-Tabelle zu erhalten.

Das vollständige Routing-Modell, einschließlich benutzerdefiniertem Zielrouting, des Landscape-Gateways und der stripPath-Option, findest du unter Landscape Networking.

Umgebungsvariablen​

Bereich „Environment Variables“ des Landscape Config Editors mit Schlüssel-Wert-Einträgen und auswählbaren Quellen wie Secrets, Workspace-Werten und Resource-Group-Kennungen.

Mit Umgebungsvariablen kannst du Konfigurationswerte an deine Services übergeben, ohne diese fest im Code zu hinterlegen. Sie werden zur Laufzeit injiziert.

So fügst du Umgebungsvariablen hinzu:​

  1. Öffne den Abschnitt Environment Variables in der Service-Konfiguration
  2. Klicke auf + Add New Variable
  3. Gib den Key ein (Variablenname)
  4. Gib den Value entweder als Klartext ein oder wähle aus den Dropdown-Kategorien: User Inputs, Global Values, Secrets, Global Constants, Resource Group ID oder Workspace ID

Weitere Details findest du unter Environment Variables.

Managed Containers​

Managed Containers basieren im Kern auf Reactives, erlauben dir jedoch, ein eigenes Docker-Image mitzubringen, anstatt das von Codesphere gepflegte Basis-Image zu verwenden. Das bedeutet, du erhältst dieselbe Plattform-Orchestrierung, Netzwerkanbindung und Überwachung, während ein eigener Container ausgeführt wird. Für einen detaillierten Überblick siehe Runtimes.

Um einen Managed Container hinzuzufügen, wähle Managed Container im Servicetyp-Auswahlmenü aus.

Runtime-Konfigurationsansicht für Managed Container mit Image-Referenz, Startup-Argumenten, Mounting-Pfaden sowie Einstellungen für Run-As-User und -Gruppe.

Entsprechende barrierefreie Textbeschreibung

Basis-Image-Konfiguration:​

  • Gib die vollständige Image-Referenz ein (z. B. nginx:1.25-alpine, node:20-slim)
  • Stelle bei privaten Registries sicher, dass entsprechende Zugangsdaten konfiguriert sind
  • Lege Startup Args fest, um den Standardbefehl des Containers bei Bedarf zu überschreiben. Der Entrypoint bleibt der Standard des Images. Möchtest du den Entrypoint überschreiben, musst du stattdessen Codesphere Reactives verwenden und dein Image als Custom Base Image einsetzen.
  • Lege Mounting Paths (volumeMounts) fest, um zu steuern, welche Verzeichnisse oder Dateien aus dem Workspace in den Container gemountet werden und wohin.

Run As User/Group:​

  • Lege die User ID (runAsUser) fest, um zu bestimmen, unter welchem Benutzerkonto der Service im Container läuft.
  • Lege die Group ID (runAsGroup) fest, um zu bestimmen, welcher Benutzergruppe der Service im Container angehört.
  • Diese Einstellungen steuern den Dateizugriff und die Berechtigungen auf Prozessebene und sollten den Eigentumserwartungen deiner Anwendung und der gemounteten Dateien entsprechen.

Die Zugriffsebene auf das Workspace-Dateisystem hängt davon ab, welche User ID oder Group ID hier festgelegt wird:

  • Bei Verwendung der User ID 1501 erhält der Container-Prozess denselben Lese-/Schreibzugriff auf die Workspace-Dateien.
  • Bei Verwendung einer anderen User ID erhält der Container-Prozess Lesezugriff auf alle Dateien sowie Schreibzugriff auf das Stammverzeichnis des gemounteten Volumes, jedoch nicht auf Unterverzeichnisse.
  • Unabhängig von der konfigurierten Group ID fügt Codesphere für das Workspace-Dateisystem direkt die GID 1010 hinzu. Die festgelegte GID beeinflusst die Eigentümergruppe der von deinen Services erstellten Dateien.
  • Du kannst Schreibzugriff auf ein bestimmtes Unterverzeichnis für die Group ID einrichten, indem du im Prepare-Stage chmod g+w some-dir ausführst.
Startgeschwindigkeit

Managed Containers haben aufgrund des Image-Pulls und der Initialisierung Startzeiten im Sekundenbereich (im Vergleich zu Millisekunden bei Reactives). Die tatsächliche Geschwindigkeit hängt von der Image-Größe und der Netzwerkleistung zur Registry ab.

Alle übrigen Konfigurationsoptionen (Ressourcen, Ports, Routen, Umgebungsvariablen) funktionieren genauso wie bei Codesphere Reactives — siehe die Abschnitte oben.

Cloud Native Deployments​

Cloud Native Deployments stellen einen virtuellen, verwalteten Kubernetes-Cluster mit vollständigem kubectl-Zugriff bereit, konzipiert für fortgeschrittene Orchestrierungsszenarien. Für einen detaillierten Überblick siehe Virtual Clusters.

Expertenruntime

Diese Runtime richtet sich an Nutzer mit vorheriger Kubernetes-Erfahrung. Wenn du neu in der Container-Orchestrierung bist, solltest du mit Codesphere Reactives oder Managed Containers beginnen.

Einrichten eines Cloud Native Deployments​

  1. Cluster bereitstellen: Füge im Bereich Managed Services der UI oder API einen virtuellen Kubernetes-Cluster hinzu. Beachte, dass jede Resource Group jeweils nur einen virtuellen Cluster haben kann.
  2. Auf den Cluster zugreifen: Nach der Bereitstellung kannst du die kubeconfig über die API abrufen, um dich mit kubectl zu verbinden.
  3. Workloads bereitstellen: Verwende kubectl-Befehle in den Prepare- oder Run-Schritten, oder interagiere direkt über das Terminal.

Plattformintegration​

Eine tiefe Integration des Lebenszyklus in die Codesphere-ci.yml befindet sich derzeit in Entwicklung. Verfügbare Funktionen:

FunktionStatus
Bereitstellung virtueller Cluster✅ Verfügbar
kubectl-Zugriff✅ Verfügbar
Helm-Deployments✅ Verfügbar
Monitoring-IntegrationManuelle Konfiguration erforderlich
NetzwerkintegrationManuelle Konfiguration erforderlich

Für volle Plattformfunktionen (automatisches Monitoring, integrierte Netzwerkanbindung, Off-when-unused) verwende Reactives oder Managed Containers.

Managed Services in Landscapes​

Obwohl du eigenständige Managed Services erstellen kannst, die dauerhaft bestehen bleiben, ist es für viele Anwendungsfälle Best Practice, Managed Services als Teil deiner Landscape-Konfiguration zu definieren. So stellst du sicher, dass deine Anwendungsumgebungen eigenständig und reproduzierbar sind.

Wenn du beispielsweise eine Development- oder Staging-Landscape startest, kann Codesphere automatisch eine dedizierte PostgreSQL-Datenbank für diese spezifische Umgebung bereitstellen und sie wieder abbauen, sobald die Landscape nicht mehr benötigt wird.

Hinzufügen eines Managed Service zu einer Landscape​

Du kannst Managed Services in deiner ci.yml (oder einem bestimmten CI Profile wie ci.dev.yml) über den Landscape Config Editor definieren oder die YAML-Datei direkt bearbeiten.

Ansicht des Landscape-Editors zur Konfiguration eines Managed-Service-Eintrags im ci.yml-Formular.

  1. Typ auswählen: Wähle im Dropdown/Modal Databases & More aus.
  2. Anbieter auswählen: Wähle den benötigten Service aus (z. B. PostgreSQL, Redis, S3).
  3. Konfigurieren: Lege Version, Plan und Konfigurationsparameter fest.
    • Name: Gib einen Namen an (z. B. primary-db). Dieser Name wird verwendet, um den Service innerhalb deiner Landscape zu referenzieren.
  4. Secrets: Definiere die vom Service benötigten Secrets (z. B. Passwörter). Du kannst auf projektweite Secrets verweisen oder neue erstellen.
  5. Speichern: Der Service wird nun zu deinem Landscape-Profil hinzugefügt. Er wird beim nächsten Deployment dieser Landscape bereitgestellt.

Verbindung mit dem Service herstellen​

Sobald ein Managed Service bereitgestellt wurde, kann sich deine Anwendung mit ihm verbinden. Anbieterspezifische Verbindungsdetails findest du in der Managed Service Provider Reference.

Service Discovery & Umgebungsvariablen​

Mit Codesphere kannst du Verbindungsdetails über Umgebungsvariablen in deine Anwendung injizieren.

  1. Secrets: Du kannst die im Managed Service definierten Secrets direkt an die Umgebungsvariablen deiner Anwendung übergeben.
  2. Hostnamen: Konkrete Beispiele für die Konstruktion von Hostnamen für einen bestimmten Service findest du auf der entsprechenden Anbieterseite in der Provider Reference.

Lebenszyklusverwaltung​

  • Erstellung: Der Managed Service wird erstellt, wenn das jeweilige Landscape Profile (z. B. dev) bereitgestellt wird.
  • Aktualisierungen: Änderungen an der ci.yml-Konfiguration (z. B. Änderung des Plans oder der Konfiguration) aktualisieren den Service beim nächsten Deployment.
  • Pausieren: Unterstützt die Landscape „Off when unused“, können auch die Managed Services pausiert werden, um Kosten zu sparen (abhängig von den Fähigkeiten des jeweiligen Services).
  • Löschen: Wird die Landscape gelöscht, werden die zugehörigen Managed Services automatisch entfernt, um verwaiste Ressourcen und zusätzliche Kosten zu vermeiden.
Umbenennen von Services

Das Umbenennen eines Managed Service in der ci.yml-Datei erfordert, dass das System ihn neu erstellt, was zu Datenverlust führen kann.

Unterschiede zu eigenständigen Services​

FunktionLandscape Managed ServiceEigenständiger Managed Service
DefinitionDefiniert in ci.ymlManuell über UI/API erstellt
LebenszyklusAn Landscape gebunden (wird mit ihr erstellt/gelöscht)Unabhängig (bleibt bis zur manuellen Löschung bestehen)
AnwendungsfallDev-, Test-, Review-UmgebungenProduktion, langlaufende gemeinsam genutzte Datenbanken
KonfigurationInfrastructure as Code (Git-verfolgt)Manuelle Konfiguration

Versionierte ci.yml-Schemas​

# Example fixture for the current schema with the Landscape gateway and the Workspace Router.
# `schemaVersion` pins the fixture to the current pipeline schema.
schemaVersion: v0.5

# `prepare` runs setup before tests and deploys.
prepare:
  # `steps` lists sequential setup commands.
  steps:
    # `name` is a descriptive label only.
    - name: Install dependencies
      # `command` is the shell command to execute.
      command: yarn install

# `test` runs verification commands after setup.
test:
  # `steps` keeps the same stage shape as `prepare`.
  steps:
    # `name` documents the test step.
    - name: Run unit tests
      # `command` runs the example test suite.
      command: yarn test --run

# `run` contains the named deploy targets for the workspace.
run:
  # Reactive runtime with the full set of supported server fields.
  reactive-app:
    # `steps` defines the lifecycle commands for a reactive runtime.
    steps:
      # Build the app before startup.
      - name: Build app
        # Produce deployable build output.
        command: yarn build
      # Start the application process.
      - name: Start app
        # Launch the runtime server.
        command: yarn start
    # `image` optionally customizes the reactive base image.
    image: ghcr.io/codesphere-cloud/example-reactive:latest
    # `healthEndpoint` is probed to determine readiness.
    healthEndpoint: http://127.0.0.1:3000/healthz/app
    # `plan` selects the workspace plan.
    plan: 20
    # `replicas` requests horizontal scaling.
    replicas: 2
    # `network` defines the ports other services in the Landscape can reach.
    network:
      # `ports` exposes raw runtime ports.
      ports: [3000, 9229]
    # `env` injects runtime environment variables.
    env:
      # Example string env var.
      NODE_ENV: production
      # Example numeric env var.
      PORT: 3000
    # `runAsUser` sets the runtime UID.
    runAsUser: 1000
    # `runAsGroup` sets the runtime GID.
    runAsGroup: 1000
    # `volumeMounts` attaches workspace storage into the runtime.
    volumeMounts:
      # `name` selects the workspace volume.
      - name: _workspace
        # `mountPath` is the destination inside the runtime.
        mountPath: /home/user/app
        # `workspacePath` selects which subdirectory to mount.
        workspacePath: ""

  # Container runtime with the full set of supported server fields.
  container-app:
    # `image` is required for container runtimes.
    image: ghcr.io/codesphere-cloud/example-container:latest
    # `command` overrides the image entrypoint/command.
    command:
      # First argv entry.
      - node
      # Second argv entry.
      - server.js
    # The rest of the fields are shared with reactive runtimes.
    healthEndpoint: http://127.0.0.1:8080/healthz/app
    # `plan` selects the workspace plan.
    plan: 20
    # `replicas` requests horizontal scaling for this runtime.
    replicas: 1
    # `network` defines the ports other services in the Landscape can reach.
    network:
      # `ports` exposes raw runtime ports.
      ports: [8080]
    env:
      # Example string env var.
      NODE_ENV: production
      # Example numeric env var.
      PORT: 8080
    # `runAsUser` sets the runtime UID.
    runAsUser: 1000
    # `runAsGroup` sets the runtime GID.
    runAsGroup: 1000
    # `volumeMounts` attaches workspace storage into the runtime.
    volumeMounts:
      # `name` selects the workspace volume.
      - name: _workspace
        # `mountPath` is the destination inside the runtime.
        mountPath: /home/user/app
        # `workspacePath` selects which subdirectory to mount.
        workspacePath: ""

  # Workspace Router:
  # - identified by `type: router`
  # - image and startup commands are managed by Codesphere
  # - holds all path mappings of the Landscape
  cs-router:
    # `type: router` deploys the Codesphere Workspace Router.
    type: router
    # `plan` selects the workspace plan for the router.
    plan: 101
    # `replicaCount` sets the number of router instances.
    replicaCount: 1
    network:
      # `isLandscapeGateway` routes all external traffic to the router.
      isLandscapeGateway: true
      # `paths` maps HTTP prefixes to services and ports in the Landscape.
      paths:
        # Route `/` to port `3000` of `reactive-app`.
        - path: /
          service: reactive-app
          port: 3000
          stripPath: false
        # Route `/container` to port `8080` of `container-app` and keep the prefix.
        - path: /container
          service: container-app
          port: 8080
          stripPath: false
      # `externalTargets` maps HTTP prefixes to URLs outside the Landscape.
      externalTargets:
        # Forward `/dashboard` to an endpoint in a Virtual Cluster.
        - path: /dashboard
          target: http://my-headlamp-x-kube-system-x-k8s.rg-${{ resourceGroup.id }}.svc.cluster.local
          stripPath: false

  # Managed service runtime (since v0.4):
  # - `provider.version` was renamed to `provider.schemaVersion`
  # This key names the managed service instance.
  postgres:
    # `provider` identifies the catalog entry to provision.
    provider:
      # `name` selects the managed service type.
      name: postgres
      # `schemaVersion` is the renamed provider version field in v0.4.
      schemaVersion: "14"
    # `plan` selects the service plan and sizing.
    plan:
      # `id` identifies the chosen catalog plan.
      id: 1
      # `parameters` contains provider-specific numeric options.
      parameters:
        # `storage` requests disk capacity.
        storage: 1024
        # `cpu` requests compute capacity.
        cpu: 1
        # `memory` requests RAM capacity.
        memory: 512
    # `config` contains non-secret provider configuration.
    config:
      # `database` is an example provider config key.
      database: app
      # `extensions` shows that lists are allowed in config payloads.
      extensions:
        - pgcrypto
    # `secrets` contains secret provider configuration.
    secrets:
      # `password` is an example secret key.
      password: secret