Runtimes

Runtimes sind die Ausführungsumgebungen, in denen deine Application Services innerhalb eines Codesphere Landscape laufen. Jeder Service in deinem Landscape verwendet einen dieser Runtime-Typen, die jeweils für unterschiedliche Workload-Muster und Deployment-Anforderungen optimiert sind.

Übersicht der Runtime-Typen​

Codesphere unterstützt mehrere Runtime-Typen, um unterschiedlichen Anwendungsarchitekturen und Deployment-Szenarien gerecht zu werden:

Codesphere Reactives​

Codesphere Reactives sind eine Runtime-Umgebung, mit der du deine Anwendungsumgebung mithilfe von Standard-Bash-Befehlen definieren kannst – genau so, wie du es auf einer lokalen Maschine oder VM tun würdest – während die Plattform die gesamte Infrastrukturverwaltung automatisch übernimmt. Du erhältst die Freiheit einer imperativen Linux-Konfiguration, ohne Container bauen, verwalten oder überhaupt darüber nachdenken zu müssen. Die Runtime kombiniert die Leistungsfähigkeit traditioneller Serverumgebungen mit automatischer Skalierung und minimalem Infrastruktur-Overhead im inaktiven Zustand.

→ Lies den vollständigen Codesphere Reactives Guide

Was Reactives anders macht​

Im Gegensatz zu traditionellen Serverless-Plattformen, die zustandslos sind und auf kurzlebige Funktionsausführungen beschränkt sind, oder herkömmlichen VMs, die kontinuierlich Ressourcen verbrauchen, kombinieren Codesphere Reactives die Vorteile beider Ansätze:

• Zustandsbehaftete Ausführung: Vollständiger Zugriff auf ein gemeinsam genutztes Netzwerk-Filesystem für persistente Daten
• Off-when-unused: Automatische Ressourcenfreigabe während Inaktivitätsphasen
• Automatische schnelle Neustarts: Optimierte Cold-Start-Zeiten
• Langlebige Prozesse: Unterstützung für traditionelle Webserver, Background-Worker und komplexe Anwendungen
• Umgebungskontrolle & Sicherheit: Rootless Containers mit anpassbaren Abhängigkeiten über Nix oder sprachspezifische Paketmanager (z. B. npm, pip)

Architektur & Funktionsweise​

Codesphere Reactives sind voll funktionsfähige Ubuntu-Container nach offenem Standard, die mit unserer patentierten Deployment-Orchestrierung für verbesserte Startup-Performance orchestriert werden:

• Gemeinsames Netzwerk-Filesystem: Jeder Reactive hat Zugriff auf ein leistungsstarkes Netzwerk-Filesystem, das persistenten Speicher über Neustarts und Replicas hinweg bereitstellt. Dateien in /home/user/app bleiben erhalten, während andere Speicherorte ephemeren Speicher verwenden.
• Serverless-Ressourcenverwaltung: Gepoolte Compute-Instanzen über mehrere Nodes ermöglichen sofortigen Start und automatische Ressourcenfreigabe während Inaktivitätsphasen. Ungenutzte Ressourcen stehen sofort anderen Workloads zur Verfügung, und eine Wakeup-Logik startet Services bei Bedarf neu.
• Kubernetes-basierte Orchestrierung: Aufgebaut auf Kubernetes mit Health-Monitoring, Load Balancing, Auto-Scaling und geordneten Shutdowns – alles von der Plattform verwaltet, ohne dass Kubernetes-Kenntnisse erforderlich sind.

Reactives vs. Managed Containers​

Sowohl Codesphere Reactives als auch Managed Containers nutzen dieselbe zugrunde liegende Orchestrierungsplattform, unterscheiden sich jedoch in der Verwaltung des Basis-Container-Images:

Codesphere Reactives nutzen ein gemeinsam genutztes, von Codesphere gepflegtes Basisimage, das:

• Gepoolt und vorgewärmt ist: Instanzen werden im Pool bereitgehalten für einen nahezu sofortigen Start (Millisekunden)
• Standardisiert ist: Von Codesphere für Sicherheit und Kompatibilität gepflegt und aktualisiert
• Agent-injiziert ist: Der Codesphere-Agent wird zur Laufzeit dynamisch injiziert – für Orchestrierung, Monitoring und Plattformintegration
• Zur Laufzeit anpassbar ist: Du definierst Abhängigkeiten über Nix oder Paketmanager in der prepare-Stage

Managed Containers erlauben dir, dein eigenes (Basis-)Image zu definieren, was bedeutet:

• Individuelles Basis-OS: Nutze jedes beliebige OCI-Image aus öffentlichen Registries
• Vorgebackene Abhängigkeiten: Bündle alle Abhängigkeiten direkt in deinem Image
• Gleiche Plattformfunktionen: Du erhältst weiterhin Orchestrierung, Monitoring, Networking und alle Codesphere-Funktionen
• Etwas langsamerer Start: Container-Images müssen gepullt und initialisiert werden (typischerweise Sekunden statt Millisekunden)
• Plattformintegration: Der Codesphere-Agent wird für Plattformfunktionen integriert

Beide Runtime-Typen profitieren von:​

• Zugriff auf das gemeinsame Netzwerk-Filesystem
• Off-when-unused-Fähigkeiten
• Automatischem Load Balancing und Scaling
• Integriertem Monitoring und Observability

Lifecycle-Management​

Off-When-Unused-Verhalten​

Eine der leistungsfähigsten Funktionen von Reactives ist ihre Fähigkeit, auf null herunterzuskalieren:

1. Aktiver Zustand: Bei der Bearbeitung von Requests oder der Ausführung von Code verbrauchen Reactives ihre zugewiesenen Compute-Ressourcen
2. Inaktivitätserkennung: Nach einer Phase der Inaktivität (keine eingehenden Web-Requests, Standard 1h) fährt der Orchestrator den Reactive Service herunter
3. Ressourcenfreigabe: Compute-Ressourcen werden an den Pool zurückgegeben, der Filesystem-Zustand bleibt jedoch intakt
4. Sofortiges Aufwachen: Beim nächsten eingehenden Request startet der Reactive neu (typischerweise nur Millisekunden bis zur Ausführung der Run-Stage) und setzt genau dort fort, wo er aufgehört hat

Dieses Verhalten ist ideal für:

• Entwicklungs- und Staging-Umgebungen
• Produktions-Services mit geringem Traffic
• Geplante Batch-Jobs
• Kostensensitive Workloads

Skalierungsstrategien​

Reactives unterstützen sowohl horizontales als auch vertikales Scaling:

Horizontales Scaling (Replicas)​

• Füge mehrere Instanzen (Replicas) desselben Services hinzu
• Automatisches Load Balancing über alle gesunden Replicas
• Konfiguration über das Feld replicas in ci.yml, über die UI oder über die API
• Ideal für die Bewältigung erhöhter Request-Volumen

Vertikales Scaling (Ressourcen)​

• Erhöhe CPU-Kerne oder Speicherzuweisung
• Wirkt innerhalb von Sekunden, ohne Neustart
• Konfiguration über das Feld plan, das die Ressourcenstufe angibt
• Ideal für rechen- oder speicherintensive Workloads

Beispielkonfiguration für Scaling:

run:
  api-server:
    plan: 42  # Ressourcenstufe (bestimmt CPU/Speicher)
    replicas: 3  # Anzahl der Instanzen
    steps:
      - name: Start Server
        command: node server.js

Konfiguration & Setup​

Umgebungsvorbereitung​

Der Abschnitt prepare definiert, wie deine Runtime-Umgebung eingerichtet wird:

prepare:
  steps:
    - name: Install System Dependencies
      command: |
        nix-env -iA nixpkgs.nodejs_20 nixpkgs.python311
        
    - name: Install Application Dependencies
      command: npm ci
      
    - name: Build Application
      command: npm run build

Um binäre Abhängigkeiten während der prepare-Stage zu installieren, unterstützt Codesphere den Nix Package Manager. Weitere Details findest du unter Installing Dependencies with Nix.

Grundlegende Reactive-Konfiguration​

Jeder Reactive Service wird im Abschnitt run deiner ci.yml definiert:

run:
  my-service:
    # Ressourcenzuweisung
    plan: 21  # Compute-Stufe – Details siehe Preisseite
    
    # Umgebungsvariablen
    env:
      NODE_ENV: production
      DATABASE_URL: ${{ vault.dbUrl }}  # Referenziert Secrets aus dem Vault
      
    # Networking
    network:
      ports:
        - port: 3000
          isPublic: false  # Nur intern und über den Router erreichbar (Ports müssen meist nicht direkt exponiert werden)
      paths:
        - port: 3000
          path: /api  # Requests an /api/* werden hierhin geroutet
          
    # Startbefehle
    steps:
      - name: Start Application
        command: npm start

Erweiterte Konfigurationsoptionen​

Individuelle Health Checks​

run:
  my-service:
    steps:
      - name: Start Application
        command: npm start
    healthEndpoint: http://localhost:8080/health        
    network:
      ports:
        - port: 8080
          isPublic: false

Volume Mounts​

Standardmäßig mounten alle Services das gesamte Verzeichnis /home/user/app. Du kannst einen Service so einschränken, dass nur ein Unterverzeichnis gemountet wird, indem du volumeMounts verwendest:

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

Best Practices & Muster​

Multi-Service-Architektur​

Services innerhalb des Landscapes können die nicht öffentlichen Ports nutzen, um HTTP-Aufrufe von einem Service zu einem anderen zu machen. Der bevorzugte Weg, externen Traffic zu deinen Landscape-Services zu routen, ist die Zuordnung eines privaten Ports zu einem öffentlichen Pfad. Das Veröffentlichen eines Ports exponiert eine zusätzliche Subdomain für diesen Port (im Format <ws-id>-<port>-<service-name>.<dc-base-domain>), oft ist dies jedoch nicht notwendig und weniger sicher als der Weg über den Router.

run:
  frontend:
    plan: 21
    network:
      paths:
        - port: 3000
          path: /
    steps:
      - command: npm run start:frontend
      
  backend:
    plan: 21
    network:
      ports:
        - port: 8080
          isPublic: false  # Interner Port, aber zu öffentlichem Pfad weitergeleitet
      paths:
        - port: 8080
          path: /api
    steps:
      - command: npm run start:backend
      
  worker:
    plan: 21
    network:
      ports:
        - port: 3000
          isPublic: false  # Nur intern, keine öffentlichen Routen definiert
    steps:
      - command: npm run start:worker

Häufige Fallstricke​

Sicherheit​

Rootless Containers​

Reactives laufen als Non-Root-Nutzer, was eine zusätzliche Sicherheitsebene bietet. Das bedeutet:

• Kein direkter Zugriff auf privilegierte Ports (< 1024)
• Keine Installation von System-Paketen möglich, die Root-Rechte erfordern
• Eingeschränkte Filesystem-Berechtigungen außerhalb von /home/user/app

Secret-Management​

Nutze immer den Vault, um sensible Informationen zu speichern:

run:
  api:
    env:
      # Template-Syntax verwenden, um Secrets zu referenzieren
      SECRET_KEY: ${{ vault.secretFoo }}
      DB_PASSWORD: ${{ vault.secretBar }}

Detaillierte Informationen zur Verwaltung von Secrets findest du unter Secret Management.

Managed Containers​

Managed Containers erlauben es dir, eigene Docker-Images in Codesphere einzubringen und dabei die Orchestrierungs-, Networking- und Monitoring-Fähigkeiten der Plattform zu nutzen. Daher gelten auch alle zuvor für Reactives genannten Punkte und Best Practices für die Managed Container Runtime.

→ Lies den vollständigen Managed Containers Guide

Wann Managed Containers verwendet werden sollten​

Verwende Managed Containers, wenn:

• du bereits Dockerfiles oder vorgebaute Images hast
• du ein bestimmtes Basisimage oder eine bestimmte OS-Distribution benötigst (Alpine, Ubuntu, Debian usw.)
• deine Abhängigkeiten komplex sind und am besten über ein Dockerfile verwaltet werden
• du Images aus Registries wie Docker Hub, ECR oder privaten Registries nutzen möchtest
• du System-Pakete bündeln musst, die über Nix nicht verfügbar sind

Konfiguration​

run:
  nginx-server:
    baseImage: nginx-unprivileged:1.29-alpine
    plan: 21
    steps:
      - command: nginx -g "daemon off;"
    healthEndpoint: http://localhost/
    network:
      ports:
        - port: 3000
          isPublic: false
        - port: 8080
          isPublic: false
      paths:
        - port: 8080
          path: /
    runAsUser: 1000
    runAsGroup: 1000

Managed Kubernetes (Virtual Clusters)​

Virtual Clusters nutzen einen virtuellen, verwalteten Kubernetes-Cluster. Nutzer erhalten vollständigen kubectl-Zugriff für fortgeschrittene Orchestrierungsszenarien.

→ Lies den vollständigen Virtual Clusters Guide

Wann Virtual Clusters verwendet werden sollten​

Verwende Virtual Clusters, wenn:

• du vollständigen Zugriff auf die Kubernetes-API benötigst
• du komplexe Helm-Charts deployst
• du individuelle Kubernetes-Ressourcen (CRDs) benötigst
• du bereits bestehende Kubernetes-Manifeste hast

Konfiguration​

Du kannst den virtuellen Kubernetes-Cluster im Bereich Managed Services der UI oder API bereitstellen. Sobald der Cluster bereitgestellt ist, kannst du dich über die in der API verfügbare Kubeconfig verbinden und deine Workloads mit kubectl-Befehlen in den prepare- oder run-Steps oder über das Terminal deployen.

Die tiefe Lifecycle-Integration in die Codesphere ci.yml ist derzeit in Arbeit. Nutzer können bereits jetzt Workloads deployen, indem sie kubectl-Befehle zu den prepare- oder run-Steps hinzufügen und den passenden Context verwenden.