Zum Hauptinhalt springen
Version: Weekly Build

Konfigurieren einer Landscape

Eine Landscape definiert, wie deine Services bereitgestellt und miteinander verbunden werden. Du kannst Compute Runtimes (Reactives, Managed Containers, Cloud Native Deployments) und Managed Services hinzufügen sowie deren Ressourcen, Netzwerk und Umgebung konfigurieren. Einen tiefergehenden technischen Überblick findest du unter Landscapes & Workspaces.

Jede Konfiguration beginnt im Landscape Config Editor:

  1. Klicke im Workspace in der Seitenleiste auf Deploy, um die Seite „Deployment and Execution“ 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 Using CI Profiles.
  3. Klicke auf der rechten Seite des Bereichs „Landscape Deployment“ auf + Add New Service und wähle den gewünschten Service-Typ aus.

Von hier aus kannst du deine Landscape über den visuellen Editor konfigurieren oder die Datei ci.yml direkt bearbeiten.

Speichern von Service-Konfigurationen

Die Landscape-Config-Oberfläche 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.

Codesphere Reactives​

Codesphere Reactives sind Codespheres Flaggschiff-Runtime, am besten beschrieben als zustandsbehaftetes Serverless. Sie kombinieren dauerhaften Dateisystemzugriff mit automatischer Ressourcenfreigabe während Leerlaufzeiten und nahezu sofortigem Start (Millisekunden). Einen ausführlichen Überblick findest du unter Runtimes.

Um ein Reactive hinzuzufügen, wähle Reactive Service aus der Service-Typ-Auswahl und konfiguriere es anhand der folgenden Abschnitte.

Runtime-Konfiguration​

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

Ausführungsschritte​

Ausführungsschritte definieren die Befehle, die beim Start deines Services ausgeführt werden. Diese Befehle laufen nacheinander 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 nötig sind
Service-Ausführung

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

Base-Image-Konfiguration​

Reactives verwenden standardmäßig ein gemeinsames, von Codesphere gepflegtes Ubuntu-Base-Image (Codesphere Defaults). Dieses Image ist vorgewärmt und gepoolt, um einen nahezu sofortigen Start (Millisekunden) zu ermöglichen. Du kannst die Runtime-Umgebung anpassen, indem du Abhängigkeiten über Nix installierst. Für fortgeschrittene Anwendungsfälle steht außerdem die Option Custom Base Image zur Verfügung, 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. Über die 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
  • Verbesserung der 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 über alle Services hinweg geteilt. Dateien, die an anderer Stelle geschrieben werden, existieren nur auf der lokalen Festplatte des jeweiligen Pods und sind für andere Services oder Replicas nicht verfügbar. Diese lokalen Dateien gehen außerdem bei Workspace-Neustarts verloren, die z. B. durch Skalierung oder Codesphere-Updates ausgelöst werden können.

Ressourcen​

Bereich „Resources“ im Landscape Config Editor mit Plan-Auswahl, Verfügbarkeitsmodus-Optionen, Replica-Steuerung und geschätzter monatlicher Kostenübersicht.

Jeder Service besitzt einen Resource Plan, der die zugewiesenen vCPUs, den Speicher und den Storage bestimmt. Die verfügbaren Pläne und deren Preise werden vom Cluster-Administrator konfiguriert und können je nach Installation variieren.

So konfigurierst du Ressourcen:​

  1. Wähle aus der Liste einen Plan aus (jeder Plan zeigt seine Zuteilung von vCPU, Speicher und Storage)
  2. Lege den Availability-Modus fest:
    • Always on: Der Service läuft dauerhaft – ideal für Produktions-Workloads
    • Off when unused: Der Service stoppt automatisch nach einer Phase der Inaktivität und startet neu, sobald die Domain oder der Workspace aufgerufen wird – ideal für Preview-Deployments oder Entwicklungsumgebungen
  3. Lege die Anzahl der Default Replicas 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. Diese ist möglicherweise nicht bei allen Installationen 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/Speicher durch Auswahl eines höheren PlansRechen- oder speicherintensive Workloads
Horizontale SkalierungMehrere Replicas desselben Services hinzufügenBewältigung eines erhöhten Anfragevolumens

Ports & Routen​

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

Health Check​

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

info

Für jeden Service muss mindestens eine Route definiert sein. Ohne Route erkennt der Workspace Router den Service nicht – er gilt dann nicht als „healthy“ und ist von außerhalb der Landscape nicht erreichbar.

Konfigurieren von Ports​

Dieser Abschnitt definiert die Ports, die dein Service bereitstellt. Für die interne Kommunikation zwischen Services sollten interne Port-URLs verwendet werden, während Ports über den Workspace Router unten öffentlich zugänglich gemacht werden können. Das Routing kann zudem über benutzerdefinierte Domains weiter angepasst werden.

Reactives innerhalb einer Landscape kommunizieren über interne URLs: http://ws-server-[WorkspaceId]-[serviceName].workspaces:[port]. Du kannst die interne URL eines Services über die Schaltfläche Copy auf der rechten Seite kopieren.

So gibst du einen neuen Port frei:​
  1. Klicke rechts auf + Add New Port
  2. Gib die Port-Nummer ein, auf der deine Anwendung lauscht
  3. Optional kannst du über das Aktionsmenü (Drei-Punkte-Symbol) in der Portzeile eine Public Port URL freigeben. Dadurch wird direkt eine öffentliche URL für den Port exponiert, die über das Kontextmenü kopiert werden kann. Dies ist weniger sicher als die Verwendung von Path Routing und wird in der Regel nur bei älteren Legacy-Frameworks benötigt.

Workspace Router​

Routen ordnen eingehende HTTP-Anfragen anhand von URL-Pfadpräfixen deinen Services zu. Der Router unterstützt zudem eine Strip Path-Option, die das übereinstimmende Präfix entfernt, bevor die Anfrage an deinen Service weitergeleitet wird.

So fügst du eine Route hinzu:​
  1. Klicke auf + Add New Route
  2. Gib das Path-Präfix ein (z. B. /, /api, /admin)
  3. Wähle den Port aus, an den der Traffic geleitet werden soll
  4. Aktiviere optional Strip Path, um das Präfix vor der Weiterleitung zu entfernen

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

Umgebungsvariablen​

Bereich „Environment Variables“ im Landscape Config Editor mit Schlüssel-Wert-Einträgen und auswählbaren Quellen wie Secrets, Workspace-Werten und Team-IDs.

Mit Umgebungsvariablen kannst du Konfigurationen an deine Services übergeben, ohne Werte 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 (Variablenname) ein
  4. Gib den Value ein – entweder als reinen Text oder durch Auswahl aus den Dropdown-Kategorien: User Inputs, Global Values, Secrets, Global Constants, Team ID oder Workspace ID

Weitere Details findest du unter Environment Variables.

Managed Containers​

Managed Containers basieren im Kern auf Reactives, ermöglichen dir aber, ein eigenes Docker-Image mitzubringen, anstatt das von Codesphere gepflegte Base-Image zu verwenden. Das bedeutet, du erhältst dieselbe Plattform-Orchestrierung, Netzwerk- und Monitoring-Funktionalität, während du einen eigenen Container betreibst. Einen ausführlichen Überblick findest du unter Runtimes.

Um einen Managed Container hinzuzufügen, wähle Managed Container aus der Service-Typ-Auswahl.

Runtime-Konfigurationsansicht für Managed Containers mit Image-Referenz, Startargumenten, Mounting-Pfaden sowie Einstellungen für Run-as-User und -Group.

Entsprechende barrierefreie Textbeschreibung

Base-Image-Konfiguration:​

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

Run As User/Group:​

  • Setze die User ID (runAsUser), um festzulegen, unter welchem Benutzerkonto der Service innerhalb des Containers läuft.
  • Setze die Group ID (runAsGroup), um festzulegen, zu welcher Benutzergruppe der Service innerhalb des Containers gehört.
  • Diese Einstellungen steuern den Dateizugriff und die Berechtigungen auf Prozessebene und sollten den Besitzverhältnissen deiner Anwendung und der gemounteten Dateien entsprechen.

Der Zugriffslevel 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 Root-Verzeichnis des gemounteten Volumes, jedoch nicht auf Unterverzeichnisse.
  • Unabhängig von der konfigurierten Group ID fügt Codesphere für das Workspace-FS direkt die GID 1010 hinzu. Die definierte GID beeinflusst die Besitzergruppe der von deinen Services erstellten Dateien.
  • Du kannst den Schreibzugriff auf ein bestimmtes Unterverzeichnis für die Group ID setzen, indem du im Prepare-Stage chmod g+w some-dir ausführst.
Startleistung

Managed Containers haben Startzeiten im Sekundenbereich (im Vergleich zu Millisekunden bei Reactives), bedingt durch das Pullen und Initialisieren des Images. Die tatsächliche Geschwindigkeit hängt von der Image-Größe und der Netzwerkperformance zur Registry ab.

Alle weiteren Konfigurationsoptionen (Ressourcen, Ports, Routen, Umgebungsvariablen) funktionieren genauso wie bei Codesphere Reactives – siehe die obigen Abschnitte.

Cloud Native Deployments​

Cloud Native Deployments stellen einen virtuellen Managed Kubernetes-Cluster mit vollständigem kubectl-Zugriff bereit, konzipiert für fortgeschrittene Orchestrierungsszenarien. Einen ausführlichen Überblick findest du unter Virtual Clusters.

Runtime für Fortgeschrittene

Diese Runtime richtet sich an Nutzer mit Vorerfahrung in Kubernetes. Wenn du neu in der Container-Orchestrierung bist, empfiehlt sich der Einstieg über Codesphere Reactives oder Managed Containers.

Einrichten eines Cloud Native Deployments​

  1. Cluster bereitstellen: Füge über den Bereich „Managed Services“ der UI oder API einen virtuellen Kubernetes-Cluster hinzu. Beachte, dass jedes Team nur jeweils einen virtuellen Cluster besitzen 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: Nutze kubectl-Befehle in den Prepare- oder Run-Schritten oder interagiere direkt über das Terminal.

Plattformintegration​

Die tiefe Lifecycle-Integration in die Codesphere ci.yml befindet sich derzeit in Entwicklung. Verfügbare Funktionen:

FunktionStatus
Bereitstellung eines virtuellen Clusters✅ Verfügbar
kubectl-Zugriff✅ Verfügbar
Helm-Deployments✅ Verfügbar
Monitoring-IntegrationManuelle Konfiguration erforderlich
NetzwerkintegrationManuelle Konfiguration erforderlich

Für den vollen Funktionsumfang der Plattform (automatisches Monitoring, integriertes Netzwerk, „Off when unused“) verwende Reactives oder Managed Containers.

Managed Services in Landscapes​

Du kannst zwar eigenständige Managed Services erstellen, die unbegrenzt bestehen bleiben, für viele Anwendungsfälle ist es jedoch Best Practice, Managed Services als Teil deiner Landscape-Konfiguration zu definieren. Dies stellt sicher, dass deine Anwendungsumgebungen in sich geschlossen 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 entfernen, 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 spezifischen 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 Databases & More aus dem Dropdown-/Modal-Menü.
  2. Provider auswählen: Wähle den benötigten Service aus (z. B. PostgreSQL, Redis, S3).
  3. Konfigurieren: Lege Version, Plan und Konfigurationsparameter fest.
    • Name: Vergib einen Namen (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 Secrets auf Projektebene referenzieren oder neue generieren.
  5. Speichern: Der Service ist nun deinem Landscape-Profil hinzugefügt. Er wird beim nächsten Deployment dieser Landscape bereitgestellt.

Verbinden mit dem Service​

Sobald ein Managed Service bereitgestellt ist, kann sich deine Anwendung damit verbinden. Siehe die Managed Service Provider Reference für providerspezifische Verbindungsdetails.

Service Discovery & Umgebungsvariablen​

Codesphere ermöglicht es dir, Verbindungsdetails über Umgebungsvariablen in deine Anwendung zu injizieren.

  1. Secrets: Die im Managed Service definierten Secrets können direkt an die Umgebungsvariablen deiner Anwendung übergeben werden.
  2. Hostnamen: Konkrete Beispiele zur Hostnamen-Konstruktion für einen bestimmten Service findest du auf der jeweiligen Provider-Seite in der Provider-Referenz.

Lifecycle-Management​

  • Erstellung: Der Managed Service wird erstellt, wenn das jeweilige Landscape-Profil (z. B. dev) deployt wird.
  • Updates: Änderungen an der ci.yml-Konfiguration (z. B. Änderung des Plans oder der Konfiguration) aktualisieren den Service beim nächsten Deployment.
  • Pausieren: Falls die Landscape „Off when unused“ unterstützt, 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​

MerkmalLandscape Managed ServiceEigenständiger Managed Service
DefinitionIn ci.yml definiertManuell über UI/API erstellt
LifecycleAn die Landscape gebunden (wird mit ihr erstellt/gelöscht)Unabhängig (bleibt bestehen, bis manuell gelöscht)
AnwendungsfallDev-, Test-, Review-UmgebungenProduktion, langlebige gemeinsam genutzte Datenbanken
KonfigurationInfrastructure as Code (Git-verfolgt)Manuelle Konfiguration

Versionierte ci.yml-Schemas​

# Example fixture for the current schema after the managed-service provider schemaVersion rename.
# `schemaVersion` pins the fixture to the current pipeline schema.
schemaVersion: v0.4

# `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
    # `isPublic` is ignored when advanced `network` settings are present.
    isPublic: true
    # `network` defines exposed ports and routed paths.
    network:
      # `ports` exposes raw runtime ports.
      ports:
        # `port` is the runtime port number to expose.
        - port: 3000
          # `isPublic` makes the port reachable from outside the workspace.
          isPublic: true
        - port: 9229
          isPublic: false
      # `paths` maps HTTP prefixes onto runtime ports.
      paths:
        # Route the root path to port `3000`.
        - port: 3000
          path: /
          stripPath: false
        # Route `/api` to port `3000` and strip the prefix.
        - port: 3000
          path: /api
          stripPath: true
    # `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
    # `isPublic` allows the routed service to be reachable externally.
    isPublic: true
    # This simple network shape publishes one routed path.
    network:
      # `path` is the public prefix for this service.
      path: /container
      # `stripPath` controls whether the prefix is preserved upstream.
      stripPath: false
    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: ""

  # Managed service runtime in 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