Landscapes & Workspaces

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

Was ist ein Landscape​

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

Was ist ein Workspace​

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

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

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

• Code & Collaborate: Eine vollausgestattete Cloud-IDE mit Anbindung an lokale IDEs, Git-Integration und Echtzeit-Teamzusammenarbeit
• CI & Deploy: Konfiguration von CI-Pipelines und CI-Profilen, Verwaltung von Umgebungsvariablen und Steuerung von Deployments
• Monitor: Überwachung von Application Health und Logs, Tracing von Requests sowie Monitoring der Performance von Workspace und Anwendung

Um zu starten, siehe die Anleitung Quickstart: Deploy your first Application.

Der Landscape-Lebenszyklus​

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

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

2. Codesphere instanziiert das Landscape
   Wenn ein Landscape synchronisiert wird, stellt Codesphere alle Ressourcen bereit und startet die Services. Die Plattform verfolgt dabei alle Änderungen an der ci.yml. Um ein laufendes 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 volle Kontrolle über das Landscape. Code oder Konfigurationen können in der Cloud-IDE geschrieben und getestet werden, Builds lassen sich im CI & Deploy-Panel auslösen und Secrets verwalten, und die Monitor-Werkzeuge ermöglichen es, Logs einzusehen, Requests zu tracen und Probleme in Echtzeit zu debuggen.

4. Nutzer greifen auf die Anwendung zu
   Nach dem Deployment werden die Services über den Landscape-Router bereitgestellt. Nutzer erreichen die Anwendung über eine eigene Domain oder die Dev-Domain, während interne Services sicher innerhalb des privaten Netzwerks isoliert bleiben.

Architekturübersicht​

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

Was läuft wo:​

• Workspace: Übernimmt Builds, Installation von Abhängigkeiten, Interaktionen mit dem Dateibaum, Language Server und Terminal-Sitzungen.
• Jeder Service im Landscape: Läuft auf eigenen dedizierten Ressourcen und bedient die Live-Anwendung unabhängig.

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

Landscape-Bausteine​

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

Die ci.yml-Datei​

Die ci.yml bietet ein standardisiertes Format zur Definition des Landscapes. Sie kann über die Benutzeroberfläche konfiguriert oder manuell im Repository bearbeitet werden. 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 die 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 Anwendungsquellcode herunter und installiert die nötigen Runtime-Abhängigkeiten mithilfe von Nix, um die Reproduzierbarkeit der Umgebung zu gewährleisten.
• Run: Konfiguriert die Deployment-Ressourcen, Umgebungsvariablen und das Networking und führt anschließend den Befehl zum Starten des Services 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 eines Landscapes:

• Codesphere Reactives: Eine containerisierte Umgebung auf Basis eines gemeinsamen Codesphere-Basisimages mit zustandsbehafteten Serverless-Funktionen und Startzeiten im Millisekundenbereich.
• Managed Containers: Bringe eigene Docker-Images mit, während Codesphere die Orchestrierung übernimmt (Skalierung, IDE-Zugriff, Networking und Monitoring).
• Cloud Native Deployments: Ein virtueller Managed-Kubernetes-Cluster, der zum Deployment cloud-nativer Anwendungen mit vollem kubectl-Zugriff genutzt werden kann.
• Virtual Machines (bald verfügbar): Eine auf Kubevirt basierende virtuelle Maschine, die mit jedem beliebigen benutzerdefinierten Image konfiguriert werden kann.
• Managed Services: Vorkonfigurierte Services aus dem Marketplace (Datenbanken, Message Queues, Caches), die deployed und mit dem Landscape verbunden werden können.

Eine detaillierte Aufschlüsselung der einzelnen Runtime-Typen findest du im Artikel Runtimes.

Privates Networking​

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

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

Der Landscape-Router​

Der Landscape-Router definiert die HTTP-Einstiegspunkte zu öffentlich verfügbaren reaktiven Services (siehe Architekturübersicht). Wenn Traffic eingeht, prüft der Router den Anfragepfad und leitet die Anfrage basierend auf den konfigurierten Pfadpräfixen an den entsprechenden Service weiter.

Die Services können über zwei Arten von URLs erreicht werden:

• Eigene 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 ein Landscape beispielsweise drei Services (foo, bar und tea), leitet der Router eingehende Anfragen wie folgt weiter:

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

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

Der Router übernimmt automatisch das Load Balancing über die Service-Replicas hinweg und stellt sicher, dass Anfragen gleichmäßig auf alle laufenden Instanzen eines Services verteilt werden. Er arbeitet auf Landscape-Ebene, das heißt, jedes Landscape verfügt über eine eigene, isolierte Routing-Konfiguration, wodurch mehrere Landscapes mit identischen Pfadstrukturen konfliktfrei nebeneinander bestehen können.

Netzwerk-Dateisystem​

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

Beim Einrichten der Anwendung sollte darauf geachtet werden, dass Services während der Laufzeit nicht gleichzeitig in dieselben Dateien schreiben, um Datenkorruption zu vermeiden. Best Practice ist es, jeden Service in einem eigenen Verzeichnis auszuführen und dieses Verzeichnis als Mount-Punkt zu konfigurieren.

Fehlerbehebung & häufige Probleme​