Runtimes

Runtimes sind die Ausführungsumgebungen, in denen deine Anwendungsdienste innerhalb einer Codesphere Landscape laufen. Jeder Dienst in deiner Landscape verwendet einen dieser Runtime-Typen, die jeweils für unterschiedliche Workload-Muster und Deployment-Anforderungen optimiert sind.

Überblick über die Runtime-Typen​

Codesphere unterstützt mehrere Runtime-Typen, um unterschiedliche Anwendungsarchitekturen und Deployment-Szenarien abzudecken:

Codesphere Reactives​

Codesphere Reactives sind eine Runtime-Umgebung, mit der du deine Anwendungsumgebung über Standard-Bash-Befehle definierst – 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 auch nur bedenken zu müssen. Die Runtime vereint die Stärken klassischer Serverumgebungen mit automatischer Skalierung und minimalem Infrastrukturaufwand bei Nichtnutzung.

→ Vollständige Anleitung zu Codesphere Reactives lesen

Was Reactives anders macht​

Anders als klassische serverlose Plattformen, die zustandslos sind und auf kurzlebige Funktionsausführungen beschränkt sind, oder klassische VMs, die durchgehend Ressourcen verbrauchen, vereinen Codesphere Reactives Vorteile aus beiden Welten:

• Zustandsbehaftete Ausführung: Voller Zugriff auf ein gemeinsam genutztes Netzwerk-Dateisystem für persistente Daten
• Ausgeschaltet bei Nichtnutzung: Automatische Freigabe von Ressourcen während Leerlaufzeiten
• Automatische schnelle Neustarts: Optimierte Cold-Start-Zeiten
• Langlaufende Prozesse: Unterstützung für klassische Webserver, Background-Worker und komplexe Anwendungen
• Umgebungskontrolle & Sicherheit: Rootless-Container mit anpassbaren Abhängigkeiten über Nix oder sprachspezifische Paketmanager (z. B. npm, pip)

Architektur & Funktionsweise​

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

• Gemeinsam genutztes Netzwerk-Dateisystem: Jedes Reactive hat Zugriff auf ein leistungsstarkes Netzwerk-Dateisystem, das persistenten Speicher über Neustarts und Replicas hinweg bereitstellt. Dateien in /home/user/app bleiben erhalten, während andere Speicherorte flüchtigen Speicher verwenden.
• Serverloses Ressourcenmanagement: Gebündelte Compute-Instanzen über mehrere Nodes ermöglichen sofortigen Start und automatische Ressourcenfreigabe während Leerlaufzeiten. Ungenutzte Ressourcen stehen anderen Workloads sofort zur Verfügung, und die Wakeup-Logik startet Dienste bedarfsgerecht neu.
• Kubernetes-basierte Orchestrierung: Aufbauend auf Kubernetes mit Health-Monitoring, Load Balancing, Auto-Scaling und geordnetem Herunterfahren – 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 darin, wie das Basis-Container-Image verwaltet wird:

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

• gebündelt und vorgewärmt ist: Instanzen werden im Pool bereitgehalten, um einen nahezu sofortigen Start (Millisekunden) zu ermöglichen
• standardisiert ist: Wird von Codesphere für Sicherheit und Kompatibilität gepflegt und aktualisiert
• agent-injiziert ist: Der Codesphere-Agent wird zur Laufzeit dynamisch für Orchestrierung, Monitoring und Plattformintegration injiziert
• zur Laufzeit anpassbar ist: Du definierst Abhängigkeiten über Nix oder Paketmanager in der prepare-Stage

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

• Individuelles Basis-OS: Verwendung beliebiger OCI-Images aus öffentlichen Registries
• Vorinstallierte Abhängigkeiten: Bündelung aller 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 gezogen und initialisiert werden (typischerweise Sekunden statt Millisekunden)
• Plattformintegration: Der Codesphere-Agent wird für Plattformfunktionen integriert

Beide Runtime-Typen profitieren von:​

• Zugriff auf das gemeinsam genutzte Netzwerk-Dateisystem
• Funktionen zum Ausschalten bei Nichtnutzung
• Automatischem Load Balancing und Skalierung
• Integriertem Monitoring und Observability

Lifecycle-Management​

Verhalten bei Nichtnutzung​

Eine der leistungsfähigsten Funktionen von Reactives ist die Fähigkeit, auf null zu skalieren:

1. Aktiver Zustand: Bei der Bearbeitung von Anfragen oder Ausführung von Code verbrauchen Reactives ihre zugewiesenen Compute-Ressourcen
2. Erkennung von Inaktivität: Nach einer Phase der Inaktivität (keine eingehenden Web-Anfragen, standardmäßig 1 Stunde) fährt der Orchestrator den Reactive-Dienst herunter
3. Ressourcenfreigabe: Compute-Ressourcen werden an den Pool zurückgegeben, der Zustand des Dateisystems bleibt jedoch erhalten
4. Sofortiges Aufwecken: Bei der nächsten eingehenden Anfrage startet das Reactive neu (typischerweise nur Millisekunden bis zur Ausführung der Run-Stage) und setzt genau dort fort, wo es aufgehört hat

Dieses Verhalten ist ideal für:

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

Skalierungsstrategien​

Reactives unterstützen sowohl horizontale als auch vertikale Skalierung:

Horizontale Skalierung (Replicas)​

• Mehrere Instanzen (Replicas) desselben Dienstes hinzufügen
• 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 eines erhöhten Anfragevolumens

Vertikale Skalierung (Ressourcen)​

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

Beispiel-Skalierungskonfiguration:

run:
  api-server:
    plan: 42  # Resource tier (determines CPU/memory)
    replicas: 3  # Number of instances
    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 Installieren von Abhängigkeiten mit Nix.

Grundlegende Reactive-Konfiguration​

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

run:
  my-service:
    # Resource allocation
    plan: 21  # Compute tier - see pricing page for details
    
    # Environment variables
    env:
      NODE_ENV: production
      DATABASE_URL: ${{ vault.dbUrl }}  # Reference secrets from vault
      
    # Networking
    network:
      ports:
        - port: 3000
          isPublic: false  # Only accessible internally and via router (usually there is no need to expose ports directly)
      paths:
        - port: 3000
          path: /api  # Requests to /api/* route here
          
    # Startup commands
    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 Dienste das gesamte Verzeichnis /home/user/app. Du kannst einen Dienst so einschränken, dass er nur ein Unterverzeichnis mit volumeMounts mountet:

run:
  my-service:
    # Only mounts /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​

Dienste innerhalb der Landscape können die nicht öffentlichen Ports nutzen, um HTTP-Aufrufe von einem Dienst zu einem anderen zu tätigen. Der bevorzugte Weg, ausgehenden Traffic zu deinen Landscape-Diensten zu routen, ist die Zuordnung eines privaten Ports zu einem öffentlichen Pfad. Wenn ein Port öffentlich gemacht wird, wird eine zusätzliche Subdomain für diesen Port freigegeben (im Format <ws-id>-<port>-<service-name>.<dc-base-domain>), was jedoch oft nicht nötig und weniger sicher ist 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  # Internal port but forwarded to public path
      paths:
        - port: 8080
          path: /api
    steps:
      - command: npm run start:backend
      
  worker:
    plan: 21
    network:
      ports:
        - port: 3000
          isPublic: false  # Internal only, no public routes defined
    steps:
      - command: npm run start:worker

Häufige Fehlerquellen​

Sicherheit​

Rootless-Container​

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

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

Secret-Management​

Verwende immer den Vault, um vertrauliche Informationen zu speichern:

run:
  api:
    env:
      # Use template syntax to reference secrets
      SECRET_KEY: ${{ vault.secretFoo }}
      DB_PASSWORD: ${{ vault.secretBar }}

Für detaillierte Informationen zur Verwaltung von Secrets siehe Secret-Management.

Managed Containers​

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

→ Vollständige Anleitung zu Managed Containers lesen

Wann Managed Containers verwendet werden sollten​

Verwende Managed Containers, wenn:

• du bereits Dockerfiles oder vorgefertigte 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 verwenden möchtest
• du Systempakete 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 Managed Kubernetes Cluster. Nutzer erhalten vollständigen kubectl-Zugriff für fortgeschrittene Orchestrierungsszenarien.

→ Vollständige Anleitung zu Virtual Clusters lesen

Wann Virtual Clusters verwendet werden sollten​

Verwende Virtual Clusters, wenn:

• du vollen Zugriff auf die Kubernetes-API benötigst
• du komplexe Helm-Charts bereitstellst
• du individuelle Kubernetes-Ressourcen (CRDs) benötigst
• du bereits bestehende Kubernetes-Manifeste hast

Konfiguration​

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

Die tiefe Lifecycle-Integration in die Codesphere-ci.yml befindet sich aktuell in Entwicklung. Nutzer können jedoch bereits Workloads bereitstellen, indem sie kubectl-Befehle zu den prepare- oder run-Steps hinzufügen und den passenden Kontext verwenden.