So erstellst du dein eigenes REST-Backend

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

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

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

Architekturübersicht​

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

1. Nutzeraktion: Ein Nutzer fordert über die UI oder die API einen neuen Service an (z. B. „My Custom DB“).
2. Marketplace Internal API: Codesphere speichert den gewünschten Zustand für diesen Service (Plan, Config, Secrets) in seiner Datenbank.
3. Managed Service Backends: Codesphere gleicht dein Backend über einen Polling-Mechanismus mit dem gewünschten Zustand eines Services ab. Auf Anfrage liefert dein Backend den aktuellen Status (z. B. Connection Strings, Health-Status) zurück, der dem Nutzer in Codesphere angezeigt wird.
4. Zugrunde liegende Infrastruktur: Dein 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 dein Backend die folgenden REST-Endpunkte implementieren. Alle Service-IDs sind UUIDs, die von Codesphere generiert werden.

1. Service erstellen (POST /)​

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

• Methode: POST
• Body: Ein vollständiges Objekt mit id, plan, config und secrets.
• Response: 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 erkannt wird.

• Methode: PATCH
• Path-Parameter: id (UUID)
• Body: Ein partielles Objekt, das nur die zu aktualisierenden Felder enthält.
• Response: 204 No Content oder Fehler.

// Beispiel für den Request Body
{
  "plan": {
    "parameters": { "storage": 2000 }
  }
}

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

Codesphere pollt diesen Endpunkt regelmäßig, um den Status der Services zu synchronisieren. Er dient sowohl als „List“- als auch als „Get Details“-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.
• Response: 200 OK mit einer Map von ID zu Status-Objekten.

Das Status-Objekt sollte details (nur lesbare Informationen wie Hostnamen, Connection Strings) enthalten, 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. Dein Backend sollte die Ressourcen deprovisionieren und sicherstellen, dass keine Daten bestehen bleiben, sofern nicht anders vorgesehen.

• Methode: DELETE
• Path-Parameter: id (UUID)
• Response: 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, falls dein Provider Backups unterstützt. Nutzerseitige Details zur Konfiguration und Wiederherstellung von Backups findest du im Leitfaden Managed Service Backups.

• Methode: PUT
• Path-Parameter: id (UUID, der eindeutige Identifikator für dieses Backup)
• Body: TakeBackupArgs mit msId, config (Konfiguration des Backup-Speichers) und secrets (Zugangsdaten für den Backup-Speicher).
• Response: 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
• Path-Parameter: id (UUID des Backups)
• Body: TakeBackupArgs mit msId, config und secrets.
• Response: 202 Accepted

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

Codesphere pollt diesen Endpunkt regelmäßig, um zu prüfen, ob ein Backup erfolgreich abgeschlossen wurde.

• Methode: POST
• Path-Parameter: id (UUID des Backups)
• Response: 200 OK mit einem JSON-Body { "exists": boolean, "error"?: string }. Ist exists auf true gesetzt, ist das Backup abgeschlossen. Bei false ist es noch in Bearbeitung. Der error-String kann verwendet werden, um einen Fehler zu melden.

Beispiel: Postgres-Backend​

Unten findest du eine partielle OpenAPI-Spezifikation für unser internes PostgreSQL-Backend. Sie zeigt, wie wir die Schemas config, plan und details definieren.

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 dein Backend sensible Daten (Secrets) empfängt und kritische Änderungen an der Infrastruktur vornimmt, hat Sicherheit hier höchste Priorität.

1. Netzwerkisolation: Idealerweise sollte dein Backend nur aus der gewünschten Codesphere-Umgebung erreichbar sein, z. B. indem der Zugriff auf die Codesphere-Egress-IPs beschränkt wird.
2. Authentifizierung: Implementiere einen Mechanismus mit gemeinsamem Secret oder Token-Authentifizierung. Codesphere lässt sich so konfigurieren, dass dieses Token bei jeder Anfrage im Authorization-Header gesendet wird.
3. Eingabevalidierung: Validiere alle eingehenden config- und plan-Parameter strikt gegen dein Schema, um Injection-Angriffe oder ungültige Zustände zu verhindern.

Backend registrieren​

Sobald dein Backend entwickelt und bereitgestellt ist, musst du es in deiner Codesphere Private Cloud-Umgebung registrieren, damit es für Nutzer verfügbar ist.

Dazu aktualisierst du die config.yaml deiner Installation, um die Definition deines neuen Service-Providers sowie die Backend-Konfiguration einzutragen. Konkret musst du das Array codesphere.managedServices und den Abschnitt managedServiceBackends anpassen.

Detaillierte Anleitungen zur Registrierung deines Backends findest du im Abschnitt Managed Service Configuration im Private Cloud Installation Guide.