Landscapes & Workspaces

Landscapes und Workspaces sind zwei zentrale Bausteine von Codesphere. Eine Landscape ist eine Deployment-Konfiguration deiner Anwendung und ihrer Architektur, die deklarativ in einer einzigen Konfigurationsdatei (ci.yml) definiert wird. Jede bereitgestellte Instanz einer Landscape ist mit einem Workspace verknüpft, der die Werkzeuge zum Konfigurieren, Anpassen, Bereitstellen und Verwalten der Landscape bereitstellt.

Was ist eine Landscape

Eine Landscape ist eine Deployment-Konfiguration deiner Anwendung und ihrer Architektur, die vollständig durch eine einzige ci.yml-Datei in deinem Repository definiert wird. Dieser Infrastructure-as-Code-(IaC)-Bauplan legt deine Deployments, Abhängigkeiten zu Managed Services sowie deren Verbindung über ein sicheres privates Netzwerk fest. Da alles versionskontrolliert ist, kannst du dasselbe Rezept auf jeder beliebigen Codesphere-Instanz bereitstellen.

Was ist ein Workspace

Der Workspace ist ein dediziertes Cockpit für die Interaktion mit einer bestimmten Landscape-Instanz. Er läuft auf eigenen Compute-Ressourcen, ist aber an denselben Dateisystem-Mount wie deine Landscape angebunden.

Wenn ein Workspace nicht aktiv genutzt wird, fährt er automatisch herunter, um Ressourcen zu sparen. Kehrst du zurück, wacht er wieder auf und stellt deine Sitzung wieder her. Durch dieses bedarfsgesteuerte Modell verbrauchen Workspaces nur dann Rechenleistung, wenn sie tatsächlich aktiv genutzt werden.

Jeder Workspace verfügt über ein integriertes Set an Werkzeugen (das Workspace Toolkit), mit denen du deine Landscape erstellen, bereitstellen und überwachen kannst. Alle Werkzeuge befinden sich als flache Liste von Icons direkt in der Seitenleiste — die Benutzeroberfläche gruppiert sie nicht in Abschnitte, diese Dokumentation ordnet sie jedoch zur besseren Navigation in drei Kategorien ein:

• Development: Eine vollwertige Cloud-IDE mit Anbindung an lokale IDEs, Git-Integration und Echtzeit-Teamzusammenarbeit
• Deployment: CI-Pipelines und CI-Profile konfigurieren, Umgebungsvariablen verwalten und Deployments steuern
• Monitoring: Anwendungszustand und Logs verfolgen, Requests nachverfolgen sowie Workspace- und Anwendungsperformance überwachen

Um loszulegen, schau dir den Leitfaden Quickstart: Deploy your first Application an.

Hast du einen Feature-Wunsch?

Hilf uns, die Zukunft von Codesphere mitzugestalten. Du kannst neue Features vorschlagen oder über die Community-Roadmap abstimmen unter feedback.codesphere.com.

Der Landscape-Lebenszyklus

Der Lebenszyklus einer Landscape wird über das Workspace Toolkit verwaltet und lässt sich in vier Phasen unterteilen:

1. Landscape definieren
   Mithilfe der Workspace-Werkzeuge oder durch Bearbeiten der IaC-Datei ci.yml setzt du deine Landscape aus den Bausteinen von Codesphere zusammen: Compute-Runtimes, Managed Services, Routing-Regeln und Speicheroptionen. Dieser deklarative Ansatz sorgt dafür, dass dein Deployment versionskontrolliert und reproduzierbar bleibt.

2. Codesphere instanziiert die Landscape
   Wenn eine Landscape synchronisiert wird, stellt Codesphere alle Ressourcen bereit und startet deine Dienste. Die Plattform verfolgt alle Änderungen an deiner ci.yml-Datei nach. Um deine laufende Landscape zu aktualisieren, klicke im Execution Manager auf die Schaltfläche Sync. Details findest du unter Landscape Lifecycle.

3. Verwaltung über den Workspace
   Das Workspace Toolkit gibt dir die volle Kontrolle über deine Landscape. Schreibe und teste Code oder Konfigurationen in der Cloud-IDE, löse Builds aus und verwalte Secrets über die Icons Deploy und Env Vars in der Seitenleiste, und nutze Werkzeuge wie Logs und Requests, um Aktivitäten in Echtzeit zu überprüfen und Probleme zu beheben.

4. Nutzerzugriff auf die Anwendung
   Nach dem Deployment läuft der gesamte externe Traffic über einen einzigen Einstiegspunkt in die Landscape, das Landscape-Gateway. Nutzer erreichen deine Anwendung über eine eigene Domain oder die Dev-Domain, während interne Dienste sicher innerhalb des privaten Netzwerks isoliert bleiben.

Architekturüberblick

Der Workspace und die zugehörige Landscape-Instanz sind an dasselbe Netzwerkdateisystem angebunden, laufen jedoch auf getrennten Compute-Ressourcen. Diese Isolierung stellt sicher, dass Workspace-Aktivitäten (wie Builds, Abhängigkeitsinstallationen oder IDE-Operationen) niemals die Performance oder Verfügbarkeit deiner Live-Anwendung beeinträchtigen.

Entsprechende barrierefreie Textbeschreibung

Was wo läuft:

• Workspace: Übernimmt Builds, Abhängigkeitsinstallationen, Dateibaum-Interaktionen, Language Server und Terminal-Sitzungen.
• Jeder Dienst in deiner Landscape: Läuft auf eigenen dedizierten Ressourcen und bedient deine Live-Anwendung unabhängig.
• Workspace Router: Läuft als Dienst in der Landscape, mit eigenem Plan und eigenen Replikaten. Als Landscape-Gateway empfängt er den gesamten externen Traffic von der eigenen Domain und der Dev-Domain. Er leitet jede Anfrage anhand des Pfads an einen Dienst weiter, zum Beispiel /foo an foo, oder an ein benutzerdefiniertes Ziel wie eine Helm-/Kubernetes-Workload. Der Router ist optional. In einer Landscape mit nur einem Dienst kann der Dienst selbst als Gateway fungieren.

Das bedeutet: Selbst wenn dein Workspace-Deployment auf Fehler stößt (z. B. weil es für die Art der laufenden Workload zu klein dimensioniert ist), bleiben die bereitgestellten Landscape-Dienste davon unberührt. Außerdem kannst du den Workspace neu starten (z. B. um die neueste Codesphere-Version zu erhalten), ohne die Landscape-Workloads zu beeinträchtigen.

Landscape-Bausteine

Dieser Abschnitt behandelt die Kernkomponenten, aus denen eine Landscape besteht. Eine schrittweise Anleitung zur Konfiguration dieser Elemente findest du im Artikel Landscape Configuration.

Die Datei ci.yml

Die ci.yml-Datei bietet ein standardisiertes Format zur Definition deiner Landscape. Du kannst sie über die Benutzeroberfläche konfigurieren oder die Datei manuell in deinem Repository bearbeiten. Eine schrittweise Anleitung findest du unter Landscape Configuration. Die Datei besteht aus zwei Hauptabschnitten:

• prepare: Definiert die Runtime-Umgebung sowie alle Abhängigkeiten und baut deine Anwendung
• run: Definiert die Deployment-Artefakte und ihre Konfiguration

Im Folgenden findest du ein Beispiel für eine ci.yml-Datei, die eine Nextcloud-Anwendung definiert.

• Prepare: Lädt den Anwendungsquellcode herunter und installiert die erforderlichen Runtime-Abhängigkeiten mit Nix, um Reproduzierbarkeit der Umgebung sicherzustellen.
• Run: Konfiguriert die Deployment-Ressourcen, Umgebungsvariablen und das Netzwerk und führt anschließend den Befehl zum Starten des Dienstes aus.

schemaVersion: v0.5

# 1. PREPARE: Define the runtime environment
prepare:
  steps:
    - name: Download Nextcloud
      command: wget -O nextcloud.zip https://download.nextcloud.com/server/releases/nextcloud-31.0.8.zip
    - name: Install Dependencies
      # We define the environment using Nix for reproducibility
      command: nix-env -iA nixpkgs.php83 nixpkgs.php83Extensions.pgsql nixpkgs.nginx

# 2. RUN: Orchestrate the Landscape
run:
  nextcloud:
    plan: 21
    env:
      # Internal networking is handled automatically
      PG_HOST: ms-postgres-internal-dns-string
      PG_PASSWORD: VAULT_PG_PASSWORD
    network:
      ports: [3000]
      # This single service receives all external traffic
      landscapeGateway:
        httpPort: 3000
    steps:
      - name: Start Stack
        command: |
          php-fpm -y ./nextcloud/php/nextcloud.conf
          nginx -c $(pwd)/nextcloud/nginx/nextcloud.conf

  pgnext:
    provider:
      name: postgres
      version: v1
    plan:
      id: 0

tipp

Diese Beispieldatei verwendet unterschiedliche Runtime-Typen (Codesphere Reactive, Managed Service), um die Landscape zu definieren. Eine detaillierte Übersicht der einzelnen Runtime-Typen findest du im Artikel Runtimes oder weiter unten in Kurzform.

Runtimes

Codesphere unterstützt mehrere Runtime-Typen innerhalb deiner Landscape:

• Codesphere Reactives: Eine containerisierte Umgebung auf Basis eines gemeinsamen Codesphere-Basis-Images mit zustandsbehafteten Serverless-Fähigkeiten und Startzeiten im Millisekundenbereich.
• Managed Containers: Bringe deine eigenen Docker-Images mit, während Codesphere die Orchestrierung übernimmt (Skalierung, IDE-Zugriff, Netzwerk und Monitoring).
• Cloud Native Deployments: Ein virtueller Managed-Kubernetes-Cluster, mit dem Cloud-Native-Anwendungen mit vollem kubectl-Zugriff bereitgestellt werden können.
• Virtual Machines: Eine auf Kubevirt basierende virtuelle Maschine, die mit jedem beliebigen benutzerdefinierten Image konfiguriert werden kann.
• Managed Services: Vorkonfigurierte Dienste aus dem Marketplace (Datenbanken, Message Queues, Caches), die bereitgestellt und mit deiner Landscape verbunden werden können.

Eine detaillierte Übersicht der einzelnen Runtime-Typen findest du im Artikel Runtimes.

Privates Networking

Standardmäßig werden Landscapes innerhalb eines sicheren privaten Netzwerks bereitgestellt. Jeder Dienst kann jeden anderen Dienst innerhalb derselben Landscape erreichen, während die Landscape als Ganzes nach außen isoliert ist. Externer Traffic gelangt ausschließlich über das Landscape-Gateway hinein. Ein Dienst ist nur dann aus dem öffentlichen Internet erreichbar, wenn er das Gateway ist oder der Workspace Router einen Pfad an ihn weiterleitet. So könntest du beispielsweise externen Traffic nur an ein API-Gateway leiten, während die Backend-Microservices vor externem Traffic abgeschirmt bleiben.

info

Container-Dienste (Reactives / Docker-Deployments) innerhalb einer Landscape kommunizieren über interne URLs: http://ws-server-[WorkspaceId]-[serviceName].workspaces:[port]. Du kannst die interne URL eines Dienstes über die Schaltfläche Copy im Port-Konfigurationsbereich kopieren.

Diese internen URLs können nur innerhalb des privaten Netzwerks der Landscape aufgelöst werden und sind weder aus dem öffentlichen Internet noch aus dem Browser eines Nutzers erreichbar. Details findest du unter Landscape Networking.

Ingress und der Workspace Router

Externer Traffic erreicht deine Landscape über zwei Arten von URLs:

• Eigene Domain: customdomain.com/* – deine eigene Domain, konfiguriert in den Domaineinstellungen
• Dev-Domain: https://[workspace-id]-3000.[datacenter-id].[your instance url]/* – deinem Workspace standardmäßig zugewiesen

Beide URLs führen zu einem einzigen Endpunkt innerhalb der Landscape, dem Landscape-Gateway. In der Landscape-Konfiguration legst du fest, welcher Dienst und welcher Port als Gateway fungieren. Eine Landscape hat höchstens ein Gateway.

• Landscapes mit einem Dienst: Der Dienst selbst ist das Gateway und empfängt alle eingehenden Anfragen. Es ist kein Router erforderlich.
• Landscapes mit mehreren Diensten: Füge der Landscape einen Codesphere Workspace Router hinzu und mache ihn zum Gateway. Der Router prüft den Anfragepfad und leitet die Anfrage an den passenden Dienst weiter oder an ein benutzerdefiniertes Ziel außerhalb der Landscape.

Definiert deine Landscape beispielsweise drei Dienste (foo, bar und tea), ordnet der Router eingehende Anfragen wie folgt zu:

• /foo/* → leitet an den Dienst foo weiter
• /bar/* → leitet an den Dienst bar weiter
• /tea/* → leitet an den Dienst tea weiter

Der Workspace Router ist in deiner ci.yml-Datei ein Dienst vom Typ router. Alle Pfadzuordnungen befinden sich in seinem Abschnitt network.paths, nicht bei den einzelnen Diensten:

run:
  cs-router:
    type: router
    plan: 101
    replicaCount: 1
    network:
      isLandscapeGateway: true
      paths:
        - path: /foo
          service: foo
          port: 3000
        - path: /bar
          service: bar
          port: 3000
        - path: /tea
          service: tea
          port: 3000

Der Router läuft als regulärer Dienst in deiner Landscape. Du skalierst ihn wie jeden anderen Dienst mit einem Plan und einer Anzahl von Replikaten. Image oder Startbefehle musst du nicht konfigurieren. Codesphere baut und betreibt den Router für dich, basierend auf den von dir definierten Pfaden.

Jede Landscape hat ihr eigenes Gateway und ihre eigene Routing-Konfiguration, sodass mehrere Landscapes identische Pfadstrukturen verwenden können, ohne dass es zu Konflikten kommt. Anfragen an einen Dienst mit mehreren Replikaten werden auf alle laufenden Instanzen verteilt.

Eigenes Gateway verwenden

Du kannst einen deiner eigenen Dienste, zum Beispiel einen benutzerdefinierten Reverse-Proxy, anstelle des Workspace Routers zum Landscape-Gateway machen. In diesem Fall übernimmst du das Routing selbst. Pfadzuordnungen und Funktionen, die auf dem Workspace Router basieren, wie die automatische Trace-Erfassung für den Request Browser, stehen dann nicht zur Verfügung.

Die vollständige Konfigurationsreferenz findest du unter Landscape Networking.

info

Standardmäßig prüft Codesphere die Health deiner Reactive-Dienste über Pings auf Port 3000. Du kannst einen benutzerdefinierten Health-Endpunkt in der Dienstkonfiguration festlegen.

Netzwerkdateisystem

Jedes Codesphere Reactive (einschließlich des Workspace-Deployments selbst) ist mit einem Netzwerkdateisystem verbunden. Der insgesamt verfügbare Speicherplatz wird auf Workspace-Ebene festgelegt und von allen Reactive-Diensten der Landscape gemeinsam genutzt. Er kann in den Workspace-Einstellungen über die Workspace-Tabelle geändert werden.

Achte beim Einrichten deiner Anwendung darauf, dass Dienste zur Laufzeit nicht gleichzeitig in dieselben Dateien schreiben, um Datenkorruption zu vermeiden. Es empfiehlt sich, jeden Dienst in einem eigenen Verzeichnis auszuführen und dieses Verzeichnis als Mount-Punkt zu konfigurieren.

warnung

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

Fehlerbehebung & häufige Probleme

Problem	Ursache	Lösung
Dienste bleiben im Zustand „unhealthy“	Der Health Check kann deine Anwendung nicht erreichen	Stelle sicher, dass deine Anwendung auf Port 3000 läuft, oder konfiguriere einen benutzerdefinierten Health-Endpunkt in der Dienstkonfiguration
Dateien gehen nach Workspace-Neustart verloren	Schreiben außerhalb von /home/user/app	Speichere alle persistenten Daten innerhalb des App-Verzeichnisses
OOM während Builds	Zu klein dimensionierter Workspace-Plan	Workspace-Ressourcen über die Workspace-Einstellungen in der Workspace-Tabelle erhöhen; bereitgestellte Dienste bleiben davon unberührt
Dienst über den Browser nicht erreichbar	Es wird kein externer Traffic an den Dienst geleitet, oder die Port-/Pfadkonfiguration ist falsch	Prüfe, ob der Dienst das Landscape-Gateway ist oder ob der Workspace Router eine Pfadzuordnung zu ihm besitzt, und kontrolliere die Port-Einstellungen. Siehe Landscape Networking