Zum Hauptinhalt springen
Version: 1.89.x (Q2 26)

So erstellt man ein eigenes REST-Backend

info

Diese Funktion ist derzeit nur in Codesphere Private Cloud verfügbar.

Die Managed-Services-Architektur von Codesphere ist auf Erweiterbarkeit ausgelegt. Codesphere enthält grundlegende Managed-Service-Provider wie PostgreSQL und S3, doch es lassen sich auch eigene individuelle Provider integrieren, indem ein RESTful-Backend implementiert wird, das der Codesphere Managed Service Adapter API Specification entspricht.

Dadurch lässt sich jede beliebige Ressource bereitstellen – sei es eine Datenbank bei einem bestimmten Cloud-Anbieter, ein Legacy-System oder ein individuelles internes Tool – und direkt über die Codesphere UI und CLI verwalten.

Neben den in diesem Artikel beschriebenen RESTful-Provider-Backends lassen sich individuelle Provider auch auf Basis von Codesphere Landscapes implementieren.

Architekturübersicht​

Der Codesphere Marketplace fungiert als zentrale Steuerungsebene für verschiedene Managed-Service-Provider. Wenn ein Nutzer einen Service bereitstellt, verwaltet Codesphere die zugrunde liegende Infrastruktur nicht selbst direkt. Stattdessen sendet es eine Anfrage an das konfigurierte Managed Service Backend des Providers. Dieses Backend ist für die tatsächliche Bereitstellung und das Lifecycle-Management der Ressource verantwortlich.

Managed-Service-Architektur

Entsprechende barrierefreie Textbeschreibung

  1. Nutzeraktion: Ein Nutzer fordert über die UI oder die API einen neuen Service an (z. B. „Meine individuelle DB“).
  2. Marketplace Internal API: Codesphere speichert den gewünschten Zustand für diesen Service (Plan, Konfiguration, Secrets) in seiner Datenbank.
  3. Managed Service Backends: Codesphere gleicht das eigene Backend über einen Polling-Mechanismus mit dem gewünschten Zustand eines Services ab. Auf Anfrage liefert das Backend den aktuellen Status (z. B. Connection-Strings, Health-Status) zurück, der dem Nutzer von Codesphere angezeigt wird.
  4. Zugrunde liegende Infrastruktur: Das Backend empfängt die Anfrage und führt die notwendigen Aktionen aus (z. B. Aufruf einer AWS-API, Start eines Kubernetes Pods, Ausführung eines Skripts).

Der API-Vertrag​

Um mit Codesphere zu integrieren, muss das Backend die folgenden REST-Endpunkte implementieren. Alle Service-IDs sind von Codesphere generierte UUIDs.

1. Service erstellen (POST /)​

Codesphere ruft diesen Endpunkt auf, wenn ein neuer Service angefragt wird.

  • Methode: POST
  • Body: Ein vollständiges Objekt mit id, plan, config und secrets.
  • Antwort: 201 Created (leerer Body) oder Fehler.
// Beispiel für den Request-Body
{
  "id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "plan": {
    "parameters": { "storage": 1000 }
  },
  "config": {
    "version": "14.2",
    "myCustomParameter": "value"
  },
  "secrets": {
    "password": "super-secret-password"
  }
}

2. Service aktualisieren (PATCH /{id})​

Codesphere ruft diesen Endpunkt auf, wenn ein Nutzer die Konfiguration ändert, den Plan skaliert, Secrets rotiert oder eine Abweichung zwischen dem gemeldeten Status eines Services und dem gewünschten Zustand feststellt.

  • Methode: PATCH
  • Pfadparameter: id (UUID)
  • Body: Ein Teilobjekt, das nur die zu aktualisierenden Felder enthält.
  • Antwort: 204 No Content oder Fehler.
// Beispiel für den Request-Body
{
  "plan": {
    "parameters": { "storage": 2000 }
  }
}

3. Status abrufen (GET /?id=...)​

Codesphere fragt diesen Endpunkt regelmäßig ab, um den Status der Services zu synchronisieren. Dies dient sowohl als „Listen“- als auch als „Details abrufen“-Operation.

  • Methode: GET
  • Query-Parameter: id (wiederholbar, z. B. ?id=uuid-1&id=uuid-2). Werden keine IDs angegeben, sollen alle bekannten Service-IDs zurückgegeben werden.
  • Antwort: 200 OK mit einer Zuordnung von ID zu Status-Objekten.

Das Status-Objekt sollte details enthalten (schreibgeschützte Informationen wie Hostnamen, Connection-Strings), die dem Nutzer angezeigt werden.

// Beispiel für den Response-Body
{
  "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11": {
    "plan": { "parameters": { "storage": 1000 } },
    "config": { "version": "14.2" },
    "details": {
      "hostname": "10.0.0.5",
      "port": 5432,
      "ready": true
    }
  }
}

4. Service löschen (DELETE /{id})​

Codesphere ruft diesen Endpunkt auf, wenn ein Nutzer den Service löscht. Das Backend sollte die Ressourcen deprovisionieren und sicherstellen, dass keine Daten erhalten bleiben, sofern dies nicht beabsichtigt ist.

  • Methode: DELETE
  • Pfadparameter: id (UUID)
  • Antwort: 204 No Content oder Fehler.

5. Backup erstellen (PUT /backups/{id}) (optional)​

Codesphere ruft diesen Endpunkt auf, um ein On-Demand- oder geplantes Backup auszulösen, sofern der Provider Backups unterstützt. Details zur nutzerseitigen Konfiguration und Wiederherstellung von Backups finden sich im Leitfaden Managed Service Backups.

  • Methode: PUT
  • Pfadparameter: id (UUID, die eindeutige Kennung für dieses Backup)
  • Body: TakeBackupArgs mit msId, config (Konfiguration des Backup-Speichers) und secrets (Zugangsdaten des Backup-Speichers).
  • Antwort: 202 Accepted

6. Backup löschen (DELETE /backups/{id}) (optional)​

Codesphere ruft diesen Endpunkt auf, wenn die Aufbewahrungsfrist erreicht ist, um alte Backups zu bereinigen.

  • Methode: DELETE
  • Pfadparameter: id (UUID des Backups)
  • Body: TakeBackupArgs mit msId, config und secrets.
  • Antwort: 202 Accepted

7. Backup-Status abrufen (POST /backups/{id}/status) (optional)​

Codesphere fragt diesen Endpunkt regelmäßig ab, um zu bestätigen, ob ein Backup erfolgreich abgeschlossen wurde.

  • Methode: POST
  • Pfadparameter: id (UUID des Backups)
  • Antwort: 200 OK mit einem JSON-Body { "exists": boolean, "error"?: string }. Ist exists gleich true, ist das Backup abgeschlossen. Bei false läuft es noch. Der error-String kann zur Meldung eines Fehlers verwendet werden.

Beispiel: Postgres-Backend​

Nachfolgend eine partielle OpenAPI-Spezifikation für unser internes PostgreSQL-Backend. Sie zeigt, wie die Schemas config, plan und details definiert werden.

openapi: "3.1.0"
info:
  title: Postgres Managed Service Provider
  version: "1.0"

paths:
  /postgres:
    post:
      summary: Create a new postgres service
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Postgres"
      responses:
        201:
          description: Postgres service created

    get:
      summary: Get status of postgres services.
      parameters:
        - name: id
          in: query
          schema:
            type: array
            items:
              type: string
              format: uuid
      responses:
        200:
          content:
            application/json:
              schema:
                oneOf:
                  - type: array # List all IDs if no query param
                    items:
                      type: string
                      format: uuid
                  - type: array # List status if query param provided
                    items:
                      $ref: "#/components/schemas/PostgresStatus"

  /postgres/{id}:
    delete:
      summary: Delete a postgres service
      responses:
        204:
          description: Postgres service deleted
    patch:
      summary: Update a postgres service
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Postgres"
      responses:
        204:
          description: Postgres service updated

  /postgres/backups/{id}:
    put:
      summary: Take a backup of a postgres service
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TakeBackupArgs"
      responses:
        202:
          description: Backup request accepted
    delete:
      summary: Delete a backup of a postgres service
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TakeBackupArgs"
      responses:
        202:
          description: Backup deletion accepted

  /postgres/backups/{id}/status:
    post:
      summary: Get the status of a postgres backup
      responses:
        200:
          description: Backup status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BackupStatus"

components:
  schemas:
    BackupStatus:
      type: object
      required:
        - exists
      properties:
        exists:
          type: boolean
        error:
          type: string

    TakeBackupArgs:
      type: object
      properties:
        msId:
          type: string
          format: uuid
        config:
          type: object
        secrets:
          type: object

    PostgresConfig:
      type: object
      properties:
        version:
          type: string
          enum: ["15.14", "14.19"]
        databaseName:
          type: string

    PostgresPlan:
      type: object
      properties:
        parameters:
          $ref: "#/components/schemas/PostgresPlanParameters"

    PostgresPlanParameters:
      type: object
      properties:
        storage:
          type: integer
          description: Storage size in MB (not MiB)
        cpu:
          type: integer
          description: CPU in tenths
        memory:
          type: integer
          description: Memory in MB (not MiB)

    PostgresDetails:
      type: object
      properties:
        hostname:
          type: string
        dsn:
          type: string
        ready:
          type: boolean

    PostgresStatus:
      type: object
      properties:
        config:
          $ref: "#/components/schemas/PostgresConfig"
        details:
          $ref: "#/components/schemas/PostgresDetails"

    PostgresSecrets:
      type: object
      properties:
        superuserPassword:
          type: string
        userPassword:
          type: string

    Postgres:
      type: object
      properties:
        id:
          type: string
          format: uuid
        config:
          $ref: "#/components/schemas/PostgresConfig"
        plan:
          $ref: "#/components/schemas/PostgresPlan"
        secrets:
          $ref: "#/components/schemas/PostgresSecrets"

Sicherheitsaspekte​

Da das Backend sensible Daten (Secrets) empfängt und kritische Änderungen an der Infrastruktur vornimmt, hat Sicherheit höchste Priorität.

  1. Netzwerkisolation: Idealerweise sollte das Backend nur aus der gewünschten Codesphere-Umgebung heraus erreichbar sein, z. B. durch Beschränkung des Zugriffs auf die Codesphere Egress-IPs.
  2. Authentifizierung: Implementiere einen Mechanismus mit Shared Secret oder Token-Authentifizierung. Codesphere kann so konfiguriert werden, dass dieses Token bei jeder Anfrage im Authorization-Header gesendet wird.
  3. Eingabevalidierung: Validiere alle eingehenden config- und plan-Parameter strikt gegen das jeweilige Schema, um Injection-Angriffe oder ungültige Zustände zu verhindern.

Registrierung des Backends​

Sobald das Backend entwickelt und bereitgestellt ist, muss es in der Codesphere Private Cloud-Umgebung registriert werden, um es für Nutzer verfügbar zu machen.

Dazu muss die config.yaml der Installation aktualisiert werden, um die neue Service-Provider-Definition und Backend-Konfiguration einzuschließen. Konkret müssen das Array codesphere.managedServices sowie der Abschnitt managedServiceBackends angepasst werden.

Detaillierte Anweisungen zur Registrierung des Backends finden sich im Abschnitt Managed Service Configuration im Private Cloud Installation Guide.