Erstellen von Service Providern

Codesphere ermöglicht es, bestehende Codesphere Landscapes als Managed Service Provider zu veröffentlichen. Dadurch können andere Entwickler eure individuellen Lösungen entdecken und bereitstellen.

Landscape-basierte Service Provider​

Ein Landscape-basierter Service Provider ermöglicht es anderen, eure Codesphere Landscape als vorkonfigurierten Managed Service zu instanziieren, den sie über den Service-Katalog bereitstellen und verwalten können.

Voraussetzungen​

Bevor ein Landscape-basierter Service Provider erstellt werden kann, benötigt man:

1. Ein Git-Repository, das eine gültige Codesphere Landscape mit einer ci.yml-Datei enthält.
2. (Optional) Eine provider.yml-Datei im Wurzelverzeichnis des Repositorys, die die Provider-Konfiguration definiert. Dies ist nur erforderlich, wenn die Veröffentlichung über die Git-URL-Methode erfolgen soll; andernfalls kann die vollständige Spezifikation direkt in der API-Anfrage angegeben werden.
3. Git-Provider-Berechtigungen, die im Codesphere-Konto konfiguriert sind. Git-Verbindungen können in den Benutzereinstellungen verwaltet werden.

Provider-Definition​

Die Datei provider.yml definiert sämtliche Metadaten und Konfigurationsschemata für den Service Provider.

name: mattermost
version: 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.

backend:
  landscape:
    gitUrl: https://github.com/your-org/mattermost-landscape
    ciProfile: production

configSchema:
  type: object
  properties:
    SITE_NAME:
      type: string
      description: Display name for your Mattermost instance
    MAX_USERS:
      type: integer
      description: Maximum number of users allowed
      x-update-constraint: increase-only

secretsSchema:
  type: object
  properties:
    ADMIN_PASSWORD:
      type: string
      format: password

detailsSchema:
  type: object
  properties:
    hostname:
      type: string
    port:
      type: integer

Provider-Felder​

Nachfolgend ist dargestellt, wo die einzelnen Schema-Typen in der Codesphere-UI erscheinen:

Veröffentlichen eines Landscape-basierten Providers​

Provider werden über die Codesphere Public API veröffentlicht. Man kann entweder eine Git-URL angeben, die die Datei provider.yml enthält, oder die vollständige Provider-Spezifikation direkt im Payload übergeben.

curl -X POST "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",
    "scope": {
      "type": "global"
    }
  }'

curl -X POST "https://<your-codesphere-instance-url>/api/managed-services/providers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mattermost",
    "version": "v1",
    "author": "Your Team",
    "displayName": "Mattermost",
    "iconUrl": "https://example.com/mattermost-icon.png",
    "category": "collaboration",
    "description": "Open-source team messaging platform.",
    "backend": {
      "landscape": {
        "gitUrl": "https://github.com/your-org/mattermost-landscape",
        "ciProfile": "production"
      }
    },
    "configSchema": {
      "type": "object",
      "properties": {
        "SITE_NAME": {
          "type": "string",
          "description": "Display name for your Mattermost instance"
        },
        "MAX_USERS": {
          "type": "integer",
          "description": "Maximum number of users allowed"
        }
      }
    },
    "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]
    }
  }'

Provider-Geltungsbereiche​

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

Übergabe von Konfigurationen an Landscapes​

Konfigurationswerte im Provider-Schema werden als Umgebungsvariablen an die Landscape übergeben. Diese können in der ci.yml referenziert werden:

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

Geheime Werte werden in den Vault der Landscape eingespeist und können in der ci.yml über die Syntax ${{ vault.SECRET_NAME }} abgerufen werden.

Update-Beschrä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 dem Erstellen eines Service geändert werden können. Dies ist nützlich, um betriebliche Regeln durchzusetzen — zum Beispiel um zu verhindern, dass Speicherplatz verringert wird, oder um die Version einer Datenbank-Engine nach der Erstkonfiguration festzuschreiben.

Das Schlüsselwort x-update-constraint kann jeder Eigenschaft im configSchema hinzugefügt werden:

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: immutable,

Verfügbare Beschränkungen​

Unterstützte Formate​

Provider-Schemata verwenden die Validierung von JSON Schema. Die folgenden format-Werte werden in Schema-Eigenschaften unterstützt:

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

Dynamische Details mit x-endpoint​

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

Wenn x-endpoint für eine Eigenschaft gesetzt ist, ruft Codesphere den Wert vom angegebenen Endpoint ab. Die Endpoint-URL unterstützt Interpolation mithilfe anderer Details-Felder.

detailsSchema:
  type: object
  properties:
    hostname:
      type: string
    port:
      type: integer
    status:
      type: object
      properties:
        state:
          type: string
        uptime:
          type: number
      x-endpoint: "https://{{hostname}}:{{port}}/status"

In diesem Beispiel wird die Eigenschaft status dynamisch vom /status-Endpoint des Service unter Verwendung der Werte hostname und port abgerufen.

Individuelle REST-Backends​

Die Managed-Services-Architektur von Codesphere ist erweiterbar gestaltet. Falls Landscape-basierte Provider nicht euren spezifischen Anforderungen entsprechen, könnt ihr ein eigenes individuelles REST-Backend implementieren.