Landscapes & Workspaces

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

Was ist eine Landscape​

Eine Landscape ist eine Deployment-Konfiguration der Anwendung und ihrer Architektur, die vollständig durch eine einzelne ci.yml-Datei im Repository definiert wird. Dieser Infrastructure-as-Code (IaC)-Bauplan legt die Deployments, Abhängigkeiten zu Managed Services sowie deren Verbindung über ein sicheres privates Netzwerk fest. Da alles versionskontrolliert ist, kann dasselbe Rezept auf jede beliebige Codesphere-Instanz deployt werden.

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 die Landscape angebunden.

Wenn ein Workspace nicht aktiv genutzt wird, fährt er automatisch herunter, um Ressourcen zu sparen. Bei Rückkehr wird er wieder aktiviert und die Sitzung wiederhergestellt. Dieses On-Demand-Modell sorgt dafür, dass Workspaces nur dann Compute-Ressourcen verbrauchen, wenn sie aktiv genutzt werden.

Jeder Workspace verfügt über ein integriertes Set an Werkzeugen (das Workspace Toolkit), mit denen die Landscape gebaut, deployt und überwacht werden kann. Alle Werkzeuge sind über die Seitenleiste in einer einheitlichen Ansicht zugänglich:

• Code & Collaborate: Eine voll ausgestattete Cloud-IDE mit lokaler IDE-Anbindung, Git-Integration und Echtzeit-Teamzusammenarbeit
• CI & Deploy: Konfiguration von CI-Pipelines und CI-Profilen, Verwaltung von Umgebungsvariablen und Steuerung von Deployments
• Monitor: Verfolgung von Application Health und Logs, Tracing von Requests sowie Überwachung der Workspace- und Anwendungsperformance

Um zu starten, siehe den Leitfaden Quickstart: Erste Anwendung deployen.

Der Landscape-Lifecycle​

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

1. Landscape definieren
   Über die Workspace-Werkzeuge oder durch Anpassung der IaC-Datei ci.yml wird die Landscape aus den Bausteinen von Codesphere zusammengestellt: Compute-Runtimes, Managed Services, Routing-Regeln und Speicheroptionen. Dieser deklarative Ansatz sorgt dafür, dass das Deployment versionskontrolliert und reproduzierbar bleibt.

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

3. Verwaltung über den Workspace
   Das Workspace Toolkit gibt dir volle Kontrolle über die Landscape. Schreibe und teste Code oder Konfiguration in der Cloud-IDE, löse Builds aus und verwalte Secrets im CI & Deploy-Bereich, und nutze die Monitor-Werkzeuge, um Logs zu prüfen, Requests zu tracen und Probleme in Echtzeit zu debuggen.

4. Nutzerzugriff auf die Anwendung
   Nach dem Deployment werden die Dienste über den Landscape-Router bereitgestellt. Nutzer erreichen die 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 entsprechende Landscape-Instanz sind an dasselbe Netzwerk-Dateisystem angebunden, laufen jedoch auf separaten Compute-Ressourcen. Diese Isolation stellt sicher, dass Workspace-Aktivitäten (wie Builds, Abhängigkeitsinstallationen oder IDE-Operationen) niemals die Performance oder Verfügbarkeit der laufenden Anwendung beeinträchtigen.

Was läuft wo:​

• Workspace: Übernimmt Builds, Abhängigkeitsinstallationen, Dateibaum-Interaktionen, Language Server und Terminal-Sitzungen.
• Jeder Dienst in der Landscape: Läuft auf eigenen dedizierten Ressourcen und stellt die laufende Anwendung unabhängig bereit.

Das bedeutet, dass selbst wenn das Workspace-Deployment auf Fehler stößt (z. B. weil es für die Art der Workload unterdimensioniert ist), die deployten Landscape-Dienste davon unberührt bleiben. Ebenso kann der Workspace neu gestartet werden (z. B. um die neueste Version von Codesphere zu erhalten), ohne die Landscape-Workloads zu beeinträchtigen.

Bausteine einer Landscape​

Dieser Abschnitt behandelt die zentralen Komponenten, aus denen eine Landscape besteht. Eine Schritt-für-Schritt-Anleitung zur Konfiguration dieser Elemente findest du im Artikel Landscape-Konfiguration.

Die ci.yml-Datei​

Die ci.yml bietet ein standardisiertes Format zur Definition der Landscape. Sie kann über die Benutzeroberfläche konfiguriert oder direkt manuell im Repository bearbeitet werden. Eine Schritt-für-Schritt-Anleitung findest du unter Landscape-Konfiguration. Die Datei besteht aus zwei Hauptabschnitten:

• prepare: Definiert die Runtime-Umgebung, alle Abhängigkeiten sowie den Build-Vorgang der Anwendung
• run: Definiert die Deployment-Artefakte und deren Konfiguration

Nachfolgend ein Beispiel einer ci.yml-Datei, die eine Nextcloud-Anwendung definiert.

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

schemaVersion: v0.2

# 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:
        - port: 3000
          isPublic: false # Secure internal port
      paths:
        - port: 3000
          path: /
    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

Runtimes​

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

• Codesphere Reactives: Eine containerisierte Umgebung, die ein gemeinsames Codesphere-Basisimage mit zustandsbehafteten serverlosen Funktionen und Startzeiten im Millisekundenbereich nutzt.
• Managed Containers: Eigene Docker-Images einbringen, während Codesphere die Orchestrierung übernimmt (Skalierung, IDE-Zugriff, Networking und Monitoring).
• Cloud Native Deployments: Ein virtueller Managed-Kubernetes-Cluster, der zum Deployen von Cloud-Native-Anwendungen mit vollständigem kubectl-Zugriff genutzt werden kann.
• Virtual Machines (in Kürze verfügbar): 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 deployt und mit der Landscape verbunden werden können.

Eine detaillierte Aufschlüsselung jedes Runtime-Typs findest du im Artikel Runtimes.

Privates Networking​

Standardmäßig werden Landscapes innerhalb eines sicheren privaten Netzwerks deployt. Dienste bleiben isoliert und sind nur dann aus dem öffentlichen Internet zugänglich, wenn dies explizit in der ci.yml-Datei oder über die Benutzeroberfläche konfiguriert wurde. So könnte zum Beispiel nur ein API-Gateway öffentlich bereitgestellt werden, während Backend-Microservices vor externem Traffic geschützt bleiben.

Diese internen URLs sind nur innerhalb des privaten Netzwerks der Landscape auflösbar und können nicht aus dem öffentlichen Internet oder dem Browser eines Nutzers erreicht werden. Öffentliche Dienste können weiterhin intern über ihre interne URL erreicht werden, private Dienste sind hingegen nur über dieses interne Netzwerk zugänglich.

Der Landscape-Router​

Der Landscape-Router definiert die HTTP-Einstiegspunkte zu den öffentlich verfügbaren Reactive-Diensten (siehe Architekturüberblick). Trifft Traffic ein, prüft der Router den Request-Pfad und leitet ihn anhand der konfigurierten Pfad-Präfixe an den entsprechenden Dienst weiter.

Auf die Dienste kann über zwei Arten von URLs zugegriffen werden:

• Custom Domain: customdomain.com/* - die eigene Domain, konfiguriert in den Domain-Einstellungen
• Dev-Domain: https://[workspace-id]-3000.[datacenter-id].[your instance url]/* - wird dem Workspace standardmäßig zugewiesen

Definiert eine Landscape beispielsweise drei Dienste (foo, bar und tea), leitet der Router eingehende Requests wie folgt weiter:

• /foo/* → wird an den Dienst foo weitergeleitet
• /bar/* → wird an den Dienst bar weitergeleitet
• /tea/* → wird an den Dienst tea weitergeleitet

Dieses pfadbasierte Routing wird für jeden Dienst im Abschnitt network.paths der ci.yml-Datei konfiguriert.

Der Router übernimmt automatisch das Load Balancing über Dienst-Replicas hinweg und stellt sicher, dass Requests gleichmäßig über alle laufenden Instanzen eines Dienstes verteilt werden. Er arbeitet auf Landscape-Ebene, was bedeutet, dass jede Landscape ihre eigene isolierte Routing-Konfiguration besitzt, sodass mehrere Landscapes mit identischen Pfadstrukturen konfliktfrei koexistieren können.

Netzwerk-Dateisystem​

Jedes Codesphere Reactive (einschließlich des Workspace-Deployments selbst) ist an ein Netzwerk-Dateisystem angebunden. Der insgesamt verfügbare Speicherplatz wird auf Workspace-Ebene definiert und über alle Reactive-Dienste der Landscape hinweg gemeinsam genutzt. Er lässt sich in den Workspace-Einstellungen über die Workspace-Tabelle anpassen.

Beim Einrichten der Anwendung sollte sichergestellt werden, dass Dienste zur Laufzeit nicht gleichzeitig in dieselben Dateien schreiben, um Datenkorruption zu vermeiden. Als Best Practice sollte jeder Dienst in seinem eigenen Verzeichnis laufen, das als Mount-Point konfiguriert wird.

Troubleshooting & häufige Probleme​