Creating Service Providers

title: "Service Providers erstellen" slug: /managed-services/creating-service-providers sidebar_position: 3​

Mit Codesphere kann ein Service als Managed Service Provider paketiert werden, damit andere Entwickler ihn im Service-Katalog finden und bereitstellen können. Provider gibt es in zwei Typen:

• Landscape-basierte Provider stellen eine Codesphere-Landscape (eine ci.yml) als Managed Service bereit, orchestriert innerhalb des Codesphere-Clusters — es ist kein Backend-Code erforderlich.
• REST-basierte Provider verbinden den Katalog mit selbst betriebener Infrastruktur über ein eigenes Backend, das die Provider-REST-API implementiert.

Eine ausführlichere Erklärung der beiden Typen und wann welcher verwendet werden sollte, findest du unter Service-Kategorien. Zur Implementierung des Backends für einen REST-basierten Provider siehe Eigenes REST-Backend erstellen.

Diese Seite erklärt, wie ein Provider definiert wird und wie er in Codesphere veröffentlicht, aktualisiert und gelöscht wird.

Einen Provider definieren​

Voraussetzungen​

Provider-Schema​

Die Provider-Definition legt alle Metadaten und Konfigurationsschemas für den Service Provider fest. Die beiden Provider-Typen teilen sich die meisten Felder; der Hauptunterschied liegt im backend-Block — Landscape-basierte Provider verweisen auf ein Git-Repository (backend.landscape), während REST-basierte Provider auf den Backend-Endpunkt (backend.api) verweisen und zusätzlich plans, capabilities und backups deklarieren können.

name: mattermost
schemaVersion: v1
author: Your Team
displayName: Mattermost
iconUrl: https://example.com/mattermost-icon.png
category: collaboration
description: |
    Open-source team messaging and collaboration platform.
    Supports channels, direct messaging, and file sharing.
teamSingleton: true
backend:
  landscape:
    gitUrl: https://github.com/your-org/mattermost-landscape
configSchema:
  type: object
  properties:
    SITE_NAME:
      type: string
      description: Display name for your Mattermost instance
      default: mattermost
      readOnly: false
    MAX_USERS:
      type: integer
      description: Maximum number of users allowed
      x-update-constraint: increase-only
  required: ['MAX_USERS']
secretsSchema:
  type: object
  properties:
    ADMIN_PASSWORD:
      type: string
      format: password
detailsSchema:
  type: object
  properties:
    hostname:
      type: string
    port:
      type: integer
versions:
  0.0.1:
    ciProfile: debug
    # gitRef can be a commit-hash, branch or tag
    gitRef: 1a410efbd13591db07496601ebc7a059dd55cfe9
    description: Initial release
  1.0.0-rc:
    appVersion: Mattermost v11.10.1
    ciProfile: prod
    gitRef: release-branches/1-0-0-rc
    description: |
      Release Candidate.
      Changelog:
        - Feature X
        - Feature Y
        - Fix Z
  1.0.0:
    appVersion: Mattermost v11.10.1
    ciProfile: prod
    gitRef: release-tags/1-0-0
    description: Long Term Support Release

name: postgres
schemaVersion: v1
author: Codesphere
displayName: PostgreSQL
iconUrl: /ide/assets/managed-services/postgresql.svg
category: Database
description: |
    Open-source database system tailored for efficient data management and scalability.
documentationUrl: https://docs.codesphere.com/managed-services/providers/postgresql
backend:
  api:
    endpoint: http://ms-backend-postgres.postgres-operator:3000/api/v1/postgres
    secret: <auth-token> # token your backend uses to authenticate incoming requests
capabilities:
  pause: true
  backups: true
  pointInTimeRecovery: true
  highAvailability: true
configSchema:
  type: object
  properties:
    version:
      type: string
      description: Version of the Postgres DB.
      enum: ['17.9', '17.6', '16.13', '16.10', '15.17', '15.14', '14.22', '14.19']
      default: '17.9'
      x-update-constraint: minor-upgrade-only
    userName:
      type: string
      default: app
      pattern: '^(?!postgres$)'
      description: Cannot be "postgres" (reserved for the superuser).
      x-update-constraint: immutable
    databaseName:
      type: string
      default: app
      x-update-constraint: immutable
  additionalProperties: false
secretsSchema:
  type: object
  properties:
    userPassword:
      type: string
      format: password
      x-update-constraint: immutable
    superuserPassword:
      type: string
      format: password
  required: ['userPassword', 'superuserPassword']
detailsSchema:
  type: object
  properties:
    port:
      type: integer
    hostname:
      type: string
      format: hostname
    dsn:
      type: string
      format: uri
    ready:
      type: boolean
  required: ['port', 'hostname', 'dsn', 'ready']
plans:
  - id: 0
    name: Small
    description: 0.5 vCPU / 500 MB Memory
    parameters:
      storage:
        pricedAs: storage-mib
        schema:
          type: integer
          default: 10240
          minimum: 512
          x-update-constraint: increase-only
      cpu:
        pricedAs: cpu-tenths
        schema: { type: number, default: 5, readOnly: true }
      memory:
        pricedAs: ram-mib
        schema: { type: integer, default: 512, readOnly: true }
# Optional: schemas for the backup store, required only if capabilities.backups is true.
backups:
  configSchema:
    type: object
    properties:
      endpointUrl:
        type: string
        format: uri
        description: S3-compatible endpoint URL for the backup storage.
      destinationPath:
        type: string
        format: uri
        description: S3 bucket URI where backups are stored (must use the s3:// scheme).
      accessKeyId:
        type: string
        description: S3 access key. The associated user must have write access to the destination bucket.
    required: ['endpointUrl', 'destinationPath', 'accessKeyId']
  secretsSchema:
    type: object
    properties:
      secretKey:
        type: string
        format: password
        description: S3 secret key for authentication.
    required: ['secretKey']

Provider-Felder​

Diese Felder sind bei beiden Provider-Typen identisch:

Die übrigen Felder hängen vom Provider-Typ ab:

Konfigurationsschemas​

Ein Provider definiert bis zu drei Schemas: configSchema, secretsSchema und detailsSchema. Sie erfüllen unterschiedliche Zwecke, werden aber auf die gleiche Weise geparst.

1.4.1. ConfigSchema​

Das configSchema definiert die Konfigurationseigenschaften, die der Nutzer bei der Erstellung eines Service festlegt — zum Beispiel die zu deployende PostgreSQL-Version. Bei Landscape-basierten Providern werden diese Werte als Umgebungsvariablen an die Landscape übergeben (siehe Konfiguration an Landscapes übergeben); bei REST-basierten Providern werden sie im Body der Erstellungs-/Aktualisierungsanfrage an dein Backend gesendet. Sobald der Service erstellt ist, kann die Konfiguration in den Service-Einstellungen eingesehen werden. Eigenschaften, die nicht als readOnly markiert sind, können später aktualisiert werden (siehe Update-Einschränkungen).

Update-Einschränkungen mit x-update-constraint​

Das configSchema unterstützt eine benutzerdefinierte Erweiterung x-update-constraint, mit der eingeschränkt werden kann, wie einzelne Eigenschaften nach der Erstellung eines Service geändert werden dürfen. Das ist nützlich, um operative Regeln durchzusetzen — zum Beispiel um zu verhindern, dass der Speicherplatz verringert wird, oder um die Version einer Datenbank-Engine nach der initialen Einrichtung zu fixieren.

Füge das Schlüsselwort x-update-constraint zu einer beliebigen Eigenschaft hinzu:

configSchema:
  type: object
  properties:
    storage:
      type: integer
      description: Storage allocation in GB
      x-update-constraint: increase-only
    version:
      type: string
      description: Version of the Postgres DB.
      enum: ['17.6', '16.10', '15.14', '14.19', '13.22']
      x-update-constraint: minor-upgrade-only

1.4.2. SecretsSchema​

Im secretsSchema definierte Secrets erscheinen als Formularfelder im Dialog zum Erstellen eines Service und müssen vom Nutzer ausgefüllt werden — zum Beispiel das PostgreSQL-Superuser-Passwort. Die Werte werden bei der Erstellung in den Service injiziert: bei Landscape-basierten Providern in den Secrets-Vault der Landscape, bei REST-basierten Providern als secrets an dein Backend gesendet. Wird eine Eigenschaft mit format: password markiert, wird sie als maskiertes Eingabefeld dargestellt.

1.4.3. DetailsSchema​

Im detailsSchema definierte Eigenschaften werden vom Service zur Laufzeit bereitgestellt — zum Beispiel der PostgreSQL-Hostname. Sie sind schreibgeschützt und können im Bereich Details der Service-Einstellungen eingesehen werden.

Standardmäßige Landscape-Details​

Bei Landscape-basierten Providern werden folgende Details immer automatisch berechnet und zurückgegeben:

Zum Beispiel erzeugt eine Landscape mit einem frontend-Service auf Port 3000 den Eintrag service_url_frontend_3000. Um diese Werte auf der Details-Seite des Service anzuzeigen, deklariere sie in deinem detailsSchema:

detailsSchema:
  type: object
  properties:
    hostname:
      type: string
      format: uri
    service_url_frontend_3000:
      type: string
      format: uri

1.4.4. Dynamische Details mit x-endpoint​

Das detailsSchema unterstützt eine benutzerdefinierte OpenAPI-Erweiterung x-endpoint, mit der Laufzeitdetails dynamisch aus deinem Service abgerufen werden können. Das ist nützlich, um Live-Statusinformationen, Metriken oder andere Daten abzurufen, die sich nach der Bereitstellung ändern.

Wird x-endpoint bei einer Eigenschaft gesetzt, ruft Codesphere den Wert zur Laufzeit vom angegebenen Endpunkt ab und validiert ihn anhand des Schemas der Eigenschaft.

Die Endpunkt-URL ist eine Vorlage: Andere Detailfelder können mit der Syntax ${{ .field_name }} referenziert werden, und Codesphere ersetzt deren Werte vor dem Absenden der Anfrage. So lässt sich der Endpunkt aus Details zusammensetzen, die erst nach der Bereitstellung bekannt sind — etwa die standardmäßigen service_url_*-Felder.

detailsSchema:
  type: object
  properties:
    service_url_frontend_3000:
      type: string
      format: uri
      readOnly: true
    status:
      type: object
      properties:
        state:
          type: string
      # ${{ .service_url_frontend_3000 }} is replaced with that detail's value at runtime
      x-endpoint: '${{ .service_url_frontend_3000 }}/health'

In diesem Beispiel wird die Eigenschaft status vom /health-Endpunkt des Frontend-Service abgerufen. Die Vorlage löst ${{ .service_url_frontend_3000 }} zur URL des laufenden Service auf, sodass die endgültige Anfrage an <service-url>/health geht und die JSON-Antwort status.state befüllt.

1.4.5. Unterstützte Formate​

Provider-Schemas unterstützen die gängigen OpenAPI-format-Werte zur Validierung:

int32, int64, float, double, byte, binary, date, date-time, password, uri, hostname

Über die Validierung hinaus beeinflussen manche Formate, wie ein Wert im Codesphere-UI dargestellt wird:

detailsSchema:
  type: object
  properties:
    hostname:
      type: string
      format: uri        # rendered as a link in the details section
      readOnly: true

secretsSchema:
  type: object
  properties:
    admin_password:
      type: string
      format: password   # rendered as a masked input in the create dialog

1.4.6. Konfiguration und Secrets an Landscapes übergeben​

Wenn ein Service aus einem Landscape-basierten Provider erstellt wird, werden die Eingaben des Nutzers an die Landscape weitergereicht: Eigenschaften aus dem configSchema werden als Umgebungsvariablen gesetzt, und Secrets aus dem secretsSchema werden in den Vault der Landscape injiziert. Beide können in der ci.yml der Landscape referenziert werden:

schemaVersion: v0.2
run:
  my-service:
    steps:
      - command: ./start.sh
    env:
      APP_VERSION: ${{ workspace.env['APP_VERSION'] }}
      ADMIN_PASSWORD: ${{ vault.ADMIN_PASSWORD }}

In diesem Beispiel ist APP_VERSION eine Eigenschaft des configSchema des Providers und ADMIN_PASSWORD eine Eigenschaft des secretsSchema des Providers.

Capabilities​

capabilities ist eine optionale Map, die deklariert, welche Lifecycle-Funktionen das Backend eines Providers unterstützt. Jeder Eintrag ist ein boolescher Wert und wird im Service-UI angezeigt: true zeigt ein Häkchen, false zeigt ein explizites Kreuz ("nicht unterstützt"), und eine ausgelassene Capability wird komplett ausgeblendet.

Provider-Versionen​

Jeder Landscape-basierte Provider muss mindestens einen Eintrag unter versions definieren. Jede Version legt den genauen Zustand der Landscape fest, der bereitgestellt wird:

• gitRef: Ein Commit-Hash, Branch oder Tag des Landscape-Repositorys.
• ciProfile: Das CI-Profil aus der ci.yml der Landscape, das für die Bereitstellung verwendet wird.
• appVersion (optional): Eine für Menschen lesbare Bezeichnung der bereitgestellten Anwendungsversion.
• description (optional): Markdown-formatierte Release-Notizen, die dem Nutzer angezeigt werden.

Beim Erstellen eines Service wählen Nutzer aus, welche Version bereitgestellt werden soll. Nutzer können die Version ihrer bereitgestellten Services ändern und dadurch ein Upgrade oder Downgrade auslösen. Weitere Informationen findest du unter Upgrade auf eine neue Version.

Provider veröffentlichen und verwalten​

Sobald ein Provider definiert ist, wird er über die Codesphere Public API in Codesphere veröffentlicht. Die im Folgenden beschriebenen Mechanismen für Veröffentlichung, Aktualisierung, Löschung, Scope und Singleton sind für Landscape-basierte und REST-basierte Provider identisch.

Provider-Scopes​

Beim Erstellen eines Providers kann dessen Sichtbarkeitsbereich (Scope) festgelegt werden:

Den Provider für alle in der Instanz verfügbar machen:

"scope": {
  "type": "global"
}

Den Provider auf bestimmte Teams beschränken:

"scope": {
  "type": "team",
  "teamIds": [1, 24, 56]
}

Einen Provider veröffentlichen und aktualisieren​

Die empfohlene Methode zum Veröffentlichen und Aktualisieren eines Providers ist der idempotente Upsert-Endpunkt. Sende eine PUT-Anfrage an /managed-services/providers:

• Existiert noch kein Provider mit demselben name und derselben schemaVersion, wird er erstellt.
• Existiert bereits einer, werden alle veränderbaren Felder direkt aktualisiert.

Das bedeutet, dieselbe Anfrage kann sowohl zum Erstellen eines Providers als auch für spätere Änderungen verwendet werden — es muss nicht nachverfolgt werden, ob der Provider bereits existiert. Das ist zum Beispiel in CI/CD-Pipelines nützlich.

Du kannst entweder eine Git-URL angeben, die die Provider-Datei enthält, oder die vollständige Provider-Spezifikation im Payload übergeben.

curl -X PUT "https://<your-codesphere-url>/api/managed-services/providers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gitUrl": "https://github.com/your-org/mattermost-landscape",
    "gitRef": "my-branch",
    "filepath": "config/prov-definition.yml",
    "scope": {
      "type": "global"
    }
  }'

curl -X PUT "https://<your-codesphere-url>/api/managed-services/providers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mattermost",
    "schemaVersion": "v1",
    "author": "Your Team",
    "displayName": "Mattermost",
    "iconUrl": "https://example.com/mattermost-icon.png",
    "category": "collaboration",
    "description": "Open-source team messaging platform.",
    "teamSingleton": true,
    "backend": {
      "landscape": {
        "gitUrl": "https://github.com/your-org/mattermost-landscape"
      }
    },
    "configSchema": {
      "type": "object",
      "properties": {
        "SITE_NAME": { "type": "string", "description": "Display name" },
        "MAX_USERS": { "type": "integer", "description": "Maximum number of users" }
      }
    },
    "secretsSchema": {
      "type": "object",
      "properties": {
        "ADMIN_PASSWORD": { "type": "string", "format": "password" }
      }
    },
    "detailsSchema": {
      "type": "object",
      "properties": {
        "hostname": { "type": "string" },
        "port": { "type": "integer" }
      }
    },
    "plans": [],
    "scope": {
      "type": "team",
      "teamIds": [42, 43]
    },
    "versions": {
      "1.0.0": {
        "appVersion": "Mattermost v11.10.1",
        "ciProfile": "prod",
        "gitRef": "release-tags/1-0-0",
        "description": "Long Term Support Release"
      }
    }
  }'

{
  "name": "postgres",
  "schemaVersion": "v1",
  "displayName": "PostgreSQL",
  "backend": {
    "api": {
      "endpoint": "http://ms-backend-postgres.postgres-operator:3000/api/v1/postgres",
      "secret": "shared-token"
    }
  },
  "capabilities": { "pause": true, "backups": true, "pointInTimeRecovery": true, "highAvailability": true },
  // configSchema, secretsSchema, detailsSchema, plans, backups ...
  "scope": { "type": "global" }
}

Einen Provider direkt aktualisieren​

Um bestimmte Felder zu ändern, ohne die gesamte Definition erneut zu übermitteln, verwende den PATCH-Endpunkt. Nur die von dir angegebenen Felder werden geändert; alle anderen gespeicherten Felder bleiben erhalten.

curl -X PATCH "https://<your-codesphere-url>/api/managed-services/providers/{name}/{schemaVersion}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "My Updated Service",
    "backend": {
      "api": {
        "endpoint": "https://new-endpoint.example.com",
        "secret": "new-secret"
      }
    }
  }'

Beim Aktualisieren von backend.api bleiben weggelassene Felder erhalten — so kann der endpoint aktualisiert werden, während das gespeicherte secret unverändert bleibt, oder es kann ein neues secret angegeben werden, um es zu rotieren.

Einen Provider löschen​

Um einen Provider zu entfernen, sende eine DELETE-Anfrage an /managed-services/providers/{name}/{schemaVersion}:

curl -X DELETE "https://<your-codesphere-url>/api/managed-services/providers/{name}/{schemaVersion}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Die Pfadparameter name und schemaVersion identifizieren den zu löschenden Provider.