Erstellen von Service Providern

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

Landscape-basierte Service Provider​

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

Voraussetzungen​

Bevor du einen Landscape-basierten Service Provider erstellst, benötigst du:

1. Ein Git-Repository, das eine gültige Codesphere-Landscape mit einer ci.yml-Datei enthält.
2. Eine Provider-Definition, entweder als provider.yml-Datei im Root-Verzeichnis des Repositorys oder direkt in der API-Anfrage angegeben.
3. Git-Zugriff auf das Landscape-Repository. Codesphere zieht das Repository über deine Git-Verbindung, daher muss das Konto, mit dem du den Provider erstellst, über die entsprechende Zugriffsberechtigung verfügen. Deine Git-Verbindungen kannst du in deinen Benutzereinstellungen verwalten.

Provider-Definition​

Die Datei provider.yml definiert alle Metadaten und Konfigurationsschemas für deinen Service Provider.

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.

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

plans:
  # The plan has no influence on the resource usage, so you should only define one.
  # You can also set plans to an empty array to disable the plan selection UI.
  - id: 0
    name: Default Plan
    description: Resource usage depends on the ci-profile of the landscape.
    parameters: {}

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: Nextcloud v33
    ciProfile: prod
    gitRef: release-branches/1-0-0-rc
    description: |
      Release Candidate.
      Changelog:
        - Feature X
        - Feature Y
        - Fix Z
  1.0.0:
    appVersion: Nextcloud v33
    ciProfile: prod
    gitRef: release-tags/1-0-0
    description: Long Term Support Release
scope:
  type: team
  teamIds: [4008]

Provider-Felder​

configSchema, secretsSchema und detailsSchema erfüllen unterschiedliche Zwecke, verwenden aber dasselbe Format: Jedes muss ein gültiges OpenAPI-Schema-Objekt sein, da Codesphere sie auf dieser Basis parst. Wie in OpenAPI können Eigenschaften als required markiert oder mit sinnvollen default-Werten versehen werden.

Nachfolgend siehst du, wo die jeweiligen Schema-Typen in der Codesphere-UI erscheinen:

Provider-Versionen​

Jeder Provider muss mindestens einen Eintrag in versions definieren. Jede Version legt den exakten Zustand der zu deployenden Landscape fest:

• gitRef: Ein Commit-Hash, Branch oder Tag des Landscape-Repositorys.
• ciProfile: Das CI-Profil aus der ci.yml-Datei der Landscape, das für das Deployment verwendet wird.
• appVersion (optional): Eine menschenlesbare Bezeichnung für die deployte Anwendungsversion.
• description (optional): Markdown-formatierte Release-Notes, die dem Benutzer angezeigt werden.

Beim Erstellen eines Services wählt der Benutzer aus, welche Version deployt werden soll.

Veröffentlichen und Aktualisieren eines Landscape-basierten Providers​

Der empfohlene Weg, einen Provider zu veröffentlichen und zu aktualisieren, ist der idempotente Upsert-Endpunkt der Codesphere Public API. 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, du kannst dieselbe Anfrage verwenden, um einen Provider zu erstellen und um spätere Änderungen auszurollen — du musst nicht nachverfolgen, 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.yml-Datei enthält, oder die vollständige Provider-Spezifikation direkt im Payload bereitstellen.

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

curl -X PUT "https://<your-codesphere-instance-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.",
    "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]
    },
    "versions": {
      "0.0.1": {
          "ciProfile": "debug",
          "gitRef": "1a410efbd13591db07496601ebc7a059dd55cfe9",
          "description": "Initial release"
      },
          "1.0.0-rc": {
          "appVersion": "Nextcloud v33",
          "ciProfile": "prod",
          "gitRef": "release-branches/1-0-0-rc",
          "description": "Release Candidate.\nChangelog:\n  - Feature X\n  - Feature Y\n  - Fix Z\n"
      },
          "1.0.0": {
          "appVersion": "Nextcloud v33",
          "ciProfile": "prod",
          "gitRef": "release-tags/1-0-0",
          "description": "Long Term Support Release"
      }
    }
  }'

Provider-Scopes​

Beim Erstellen eines Providers kannst du dessen Sichtbarkeitsbereich festlegen:

Übergabe von Konfiguration an Landscapes​

Wird ein Service aus einem Landscape-basierten Provider erstellt, werden die Eingaben des Benutzers an die Landscape weitergegeben: Eigenschaften aus dem configSchema werden als Umgebungsvariablen gesetzt, und Secrets aus dem secretsSchema werden in den Vault der Landscape eingefügt. Beide können in der ci.yml-Datei 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.

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

Das configSchema unterstützt eine benutzerdefinierte Erweiterung x-update-constraint, mit der du einschränken kannst, wie einzelne Eigenschaften nach der Erstellung eines Services geändert werden können. Das 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 Ersteinrichtung festzuschreiben.

Füge das Schlüsselwort x-update-constraint zu einer beliebigen Eigenschaft in deinem configSchema 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: immutable,

Verfügbare Einschränkungen​

Unterstützte Formate​

Provider-Schemas verwenden die JSON Schema-Validierung. 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 du Runtime-Details dynamisch von deinem Service abrufen kannst. Das ist nützlich, um Live-Statusinformationen, Metriken oder andere Daten abzurufen, die sich nach der Provisionierung ändern.

Ist x-endpoint für eine Eigenschaft gesetzt, ruft Codesphere den Wert vom angegebenen Endpunkt ab. Die Endpunkt-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 über den /status-Endpunkt des Services abgerufen, unter Verwendung der Werte hostname und port.

Benutzerdefinierte REST-Backends​

Die Managed-Services-Architektur von Codesphere ist erweiterbar konzipiert. Falls Landscape-basierte Provider deinen spezifischen Anforderungen nicht entsprechen, kannst du dein eigenes benutzerdefiniertes REST-Backend implementieren.