Eine Landscape konfigurieren

Execution Steps​

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

So fügst du Execution Steps 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 diesen Vorgang, falls weitere Schritte benötigt werden

Base-Image-Konfiguration​

Reactives verwenden standardmäßig ein gemeinsames, von Codesphere gepflegtes Ubuntu-Base-Image (Codesphere Defaults). Dieses Image ist vorgewärmt und gepoolt für einen quasi-instantanen Start (Millisekunden). 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 Netzwerk-Dateisystem. Über die Einstellung Mounting Paths kannst du einen Service so einschränken, dass er nur ein bestimmtes Unterverzeichnis mountet.

Anwendungsfälle für Mount-Unterpfade:​

• Isolierung des Dateizugriffs zwischen Services, um versehentliches Überschreiben zu verhindern
• Verbesserte Sicherheit durch Einschränkung des Dateisystembereichs jedes Services
• Organisation von Multi-Service-Architekturen mit dedizierten Verzeichnissen

run:
  my-service:
    # Mountet nur /home/user/app/uploads
    volumeMounts:
      - name: _workspace
        mountPath: /home/user/app
        workspacePath: uploads
    steps:
      - name: Start Server
        command: npm start

• steps: Liste der Execution Steps, jeweils mit name und command. Befehle werden beim Start des Services sequenziell ausgeführt.
• volumeMounts (optional): Beschränkt den Service auf ein Unterverzeichnis von /home/user/app.

Beispielbefehle:

• npm start — Node.js-Anwendung
• uv run uvicorn main:app --port 3000 --host 0.0.0.0 — Python-Anwendung
• ./gradlew bootRun — Spring-Boot-Anwendung

Jeder Service hat einen Resource Plan, der die zugewiesenen vCPUs, den Arbeitsspeicher und den Speicherplatz bestimmt. Die verfügbaren Pläne und deren Preise werden von deinem Cluster-Administrator konfiguriert und können sich zwischen Installationen unterscheiden.

So konfigurierst du Ressourcen:

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

Skalierungsstrategien:​

run:
  api-server:
    plan: 21        # Ressourcen-Tier (bestimmt CPU/Arbeitsspeicher)
    replicas: 3     # Anzahl der Instanzen
    steps:
      - name: Start Server
        command: node server.js

• plan: Die ID des Ressourcen-Tiers, das die CPU- und Arbeitsspeicherzuweisung bestimmt.
• replicas (optional): Anzahl der Service-Instanzen für horizontale Skalierung. Standardwert ist 1.

Health Check​

Standardmäßig pingt der Landscape Router deine Reactive Services auf Port 3000 an, um ihre Gesundheit 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 außerdem innerhalb des Service-Containers ausgeführt, daher muss die Anwendung unter localhost erreichbar sein. Wenn sie an ein anderes Interface gebunden ist, gib stattdessen die entsprechende IP-Adresse oder den Hostnamen an.

Ports konfigurieren​

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

Reactives innerhalb einer Landscape kommunizieren über interne URLs: http://ws-server-[WorkspaceId]-[serviceName].workspaces:[port]. Die interne URL eines Services kannst du ü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 Port-Zeile eine Public Port URL freigeben. Dies gibt direkt eine öffentliche URL für den Port frei, die über das Kontextmenü kopiert werden kann. Dies ist weniger sicher als Path-Routing und wird in der Regel nur bei älteren Legacy-Frameworks benötigt.

Workspace Router​

Routen ordnen eingehende HTTP-Anfragen deinen Services anhand von URL-Pfadpräfixen zu. Der Router unterstützt außerdem eine Strip Path-Option, mit der das übereinstimmende Präfix entfernt wird, 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 Abschnitt Routing for Other Services unten zeigt die von anderen Services in derselben Landscape definierten Routen, was hilfreich ist, um Konflikte zu erkennen oder einen Überblick über die gesamte Routing-Tabelle zu erhalten.

run:
  backend:
    healthEndpoint: http://localhost:8080/health
    network:
      ports:
        - port: 8080
          isPublic: false
      paths:
        - port: 8080
          path: /api
    steps:
      - command: npm run start:backend

• healthEndpoint (optional): Benutzerdefinierte URL für den Health Check. Standardwert ist http://localhost:3000/. Die Anfrage wird innerhalb des Service-Containers ausgeführt, daher muss die Anwendung unter localhost erreichbar sein. Wenn sie an ein anderes Interface gebunden ist, gib stattdessen die entsprechende IP-Adresse oder den Hostnamen an.
• network.ports: Liste der Ports, die der Service freigibt. Setze isPublic: true, um eine direkte öffentliche URL freizugeben (nicht empfohlen).
• network.paths: Ordnet URL-Pfadpräfixe für den Workspace Router den entsprechenden Ports zu.

Beispiel für eine Routing-Konfiguration:

Umgebungsvariablen ermöglichen es, Konfigurationswerte an deine Services zu übergeben, ohne sie fest im Code zu verankern. 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 (Variablennamen) 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 Umgebungsvariablen.

run:
  my-service:
    env:
      NODE_ENV: production
      SECRET_KEY: ${{ vault.secretFoo }}
      DB_PASSWORD: ${{ vault.dbPassword }}
      PG_USER: ${{ workspace.env['BACKEND_PG_USER'] }}

• env: Schlüssel-Wert-Paare, die zur Laufzeit als Umgebungsvariablen injiziert werden.

Template-Syntax für Werte:​

Secrets werden verschlüsselt gespeichert und erst zur Laufzeit injiziert. Details siehe Secret Management.

Base-Image-Konfiguration:​

• Gib die vollständige Image-Referenz ein (z. B. nginx:1.25-alpine, node:20-slim)
• Bei privaten Registries stelle sicher, dass die entsprechenden Zugangsdaten konfiguriert sind
• Setze Startup Args, um den Standardbefehl des Containers bei Bedarf zu überschreiben. Der Entrypoint bleibt der Standard des Images. Wenn du den Entrypoint überschreiben möchtest, müsstest 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 an welche Stelle.

Run As User/Group:​

• Setze User ID (runAsUser), um festzulegen, unter welchem Benutzerkonto der Service innerhalb des Containers ausgeführt wird.
• Setze Group ID (runAsGroup), um festzulegen, zu welcher Benutzergruppe der Service innerhalb des Containers gehört.
• Diese Einstellungen steuern den Dateizugriff und Berechtigungen auf Prozessebene und sollten den Eigentumserwartungen deiner Anwendung und der gemounteten Dateien entsprechen.

Der Zugriffslevel auf das Workspace-Dateisystem hängt davon ab, welche User ID oder Group ID hier eingestellt ist:

• Bei Verwendung der User ID 1501 erhält der Container-Prozess denselben Lese-/Schreibzugriff auf die Workspace-Dateien.
• Bei einer anderen User ID erhält der Container-Prozess Lesezugriff auf alle Dateien und Schreibzugriff auf das Root-Verzeichnis des gemounteten Volumes, jedoch nicht auf Unterverzeichnisse.
• Unabhängig von der konfigurierten Group ID fügt Codesphere direkt die GID 1010 für das Workspace-FS hinzu. Die definierte GID wirkt sich auf die Besitzergruppe der von deinen Services erstellten Dateien aus.
• Du kannst Schreibzugriff auf ein bestimmtes Unterverzeichnis für die Group ID einrichten, indem du im Prepare-Stage den Befehl chmod g+w some-dir ausführst.

Alle anderen Konfigurationsoptionen (Resources, Ports, Routes, Environment Variables) funktionieren genauso wie bei Codesphere Reactives — siehe die obigen Abschnitte.

run:
  alpine-image:
    image: alpine:latest
    steps:
      - name: Run Alpine
        command: echo "Hello from Alpine!"
    plan: 21
    network:
      ports:
        - port: 80
          isPublic: false
      paths:
        - port: 80
          path: /
  nginx-server:
    image: nginx-unprivileged:1.25-alpine
    command: ["-g", "daemon off;"]
    plan: 21
    healthEndpoint: http://localhost/
    network:
      ports:
        - port: 80
          isPublic: false
      paths:
        - port: 80
          path: /
    env:
      NGINX_HOST: example.com
    volumeMounts:
      - name: _workspace
        mountPath: /etc/nginx/nginx.conf
        workspacePath: custom-nginx.conf
    runAsUser: 1000
    runAsGroup: 1000

• image: Das zu verwendende Docker-Image (z. B. nginx-unprivileged:1.25-alpine, node:20-slim, myregistry.com/repo/myimage:tag).
• runAsUser / runAsGroup (optional): Legt die User- und Group-ID fest, unter der der Container ausgeführt wird.
• command (optional): Überschreibt den Standardbefehl des Containers. Gib ihn als Array von Argumenten an (z. B. ["-g", "daemon off;"]). Der Entrypoint bleibt der Standard des Images. Dieses Feld schließt sich mit steps gegenseitig aus und kann nicht im selben Service verwendet werden.
• volumeMounts (optional): Du kannst Dateien und Ordner aus dem Workspace an beliebige Pfade im Container mounten.
• Alle anderen Felder (plan, network, env, usw.) funktionieren genauso wie bei Reactives.

1. Cluster bereitstellen: Füge im Bereich Managed Services der UI oder API einen virtuellen Kubernetes Cluster hinzu. Beachte, dass jedes Team gleichzeitig nur einen virtuellen Cluster haben kann.
2. Auf den Cluster zugreifen: Sobald der Cluster bereitgestellt ist, rufe die kubeconfig über die API ab, um dich mit kubectl zu verbinden.
3. Workloads deployen: Verwende kubectl-Befehle in den Prepare- oder Run-Steps oder interagiere direkt über das Terminal.

K8s-Manifeste über kubectl deployen:

prepare:
  steps:
    - name: Deploy Application
      command: |
        kubectl apply -f k8s/deployment.yaml
        kubectl apply -f k8s/service.yaml

Ein Helm Chart deployen:

prepare:
  steps:
    - name: Deploy with Helm
      command: |
        helm repo add corp42 https://charts.corp42.net
        helm repo update
        helm install my-release corp42/my-awesome-app -n app --create-namespace -f values-codesphere.yaml

1. Typ auswählen: Wähle Databases & More aus dem Dropdown/Modal aus.
2. Provider auswählen: Wähle den gewünschten 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 auf projektweite Secrets verweisen oder neue erzeugen.
5. Speichern: Der Service ist nun deinem Landscape-Profil hinzugefügt. Er wird beim nächsten Deployment dieser Landscape bereitgestellt.

Du kannst Managed Services in deiner ci.yml-Datei definieren. Dies ist nützlich für „Infrastructure as Code“-Praktiken. Die UI generiert dieses YAML ebenfalls automatisch für dich, du kannst es aber auch manuell schreiben, wenn du das bevorzugst.

1. Profil bearbeiten: Klicke oben rechts auf Edit as File und bearbeite die Profildefinition, um einen neuen Service im Abschnitt run hinzuzufügen. Dieses Beispiel definiert eine PostgreSQL-Datenbank.

   schemaVersion: v0.2
   # ... bestehende prepare- und run-Stages ...
   
   run:
     my-postgres-db:
       provider:
         name: postgres
         version: v1
       plan:
         id: 0
         parameters:
           storage: 10000
           cpu: 5
           memory: 500
       config:
         version: "17.6"
         userName: "${{ workspace.env.pgUser }}"
         databaseName: "${{ workspace.env.pgDb }}"
       secrets:
         userPassword: "${{ vault.pgPassword }}"
         superuserPassword: "${{ vault.pgSuperuserPassword }}"
   

   • Key (z. B. my-postgres-db): Der Name und eindeutige Bezeichner für diesen Service in der Landscape.

     warnung

     Das Umbenennen eines Services erfordert, dass das System ihn neu erstellt, was zu Datenverlust führen kann. Gehe hierbei mit Vorsicht vor.

   • provider: Der Typ des Services (entspricht dem Provider-Namen im Katalog).
   • secrets: Kann mit der Syntax ${{ vault.NAME }} auf Secrets im Codesphere Vault verweisen.

   

   info

   Die Managed-Service-Definition muss eine gültige Provider-Konfiguration für den bereitzustellenden Service verwenden (z. B. Plan-IDs, Versionen und Konfigurationsparameter). Die zulässigen Werte findest du über den Aufruf des Endpunkts get provider in der Codesphere Public API, oder du erstellst zunächst das initiale Grundgerüst über die UI, bevor du die YAML-Datei manuell bearbeitest.

2. Speichern: Speichere das Profil (Strg + S bzw. Cmd + S)

3. Landscape synchronisieren: Wechsle zum Tab Execution Manager und klicke oben mittig im Bereich Landscape Deployment auf Sync Landscape. Bestätige die Ressourcennutzung. Dadurch werden die Änderungen am Profil angewendet und die Bereitstellung der Managed Services ausgelöst.

   

4. Secrets: Gib die erforderlichen Secrets ein, die du zuvor bei der Definition des Managed Service verwendet hast. In diesem Beispiel pgPassword und pgSuperuserPassword. Diese werden sicher im Codesphere Vault gespeichert und bei der Bereitstellung in den Service injiziert.

   

Der Service wird nun erstellt und steht deiner Anwendung zur Verbindung zur Verfügung, sobald du diese Landscape deployst.