Zum Hauptinhalt springen
Version: Weekly Build

Erstellen von Service Providern

Mit Codesphere kann man einen Dienst als Managed Service Provider bereitstellen, damit andere Entwickler ihn im Service-Katalog finden und deployen können. Es gibt zwei Arten von Providern:

  • Landscape-basierte Provider deployen eine Codesphere-Landscape (eine ci.yml) als Managed Service, orchestriert innerhalb des Codesphere-Clusters – ohne dass Backend-Code erforderlich ist.
  • REST-basierte Provider verbinden den Katalog mit einer selbst betriebenen Infrastruktur über ein eigenes Backend, das die Provider-REST-API implementiert.

Eine ausführlichere Erklärung der beiden Typen und wann welcher genutzt werden sollte, findet sich unter Service-Kategorien. Um das Backend hinter einem REST-basierten Provider zu implementieren, siehe Erstellen eines eigenen REST-Backends.

Diese Seite erklärt, wie man einen Provider definiert und wie man ihn in Codesphere veröffentlicht, aktualisiert und löscht. Die Definition kann von Hand geschrieben oder im Provider-Editor der Benutzeroberfläche zusammengestellt werden.

Einen Provider definieren​

Voraussetzungen​

Ein Landscape-basierter Provider deployt eine Landscape aus einem Git-Repository. Bevor man einen solchen erstellt, wird Folgendes benötigt:

  1. Ein Git-Repository, das eine gültige Codesphere-Landscape mit einer ci.yml-Datei enthält.
  2. Eine Provider-Definition, entweder als Provider-Datei im Repository (standardmäßig provider.yml oder provider.yaml im Root-Verzeichnis, oder ein benutzerdefinierter Pfad über das Argument filepath) oder direkt im API-Request angegeben.
  3. Git-Zugriff auf das Landscape-Repository. Codesphere lädt das Repository über die Git-Verbindung herunter, daher muss das verwendete Konto Zugriff darauf haben. Git-Verbindungen können in den Benutzereinstellungen verwaltet werden.

Ein Beispiel findet sich in unserem öffentlichen URL-Shortener-Repository.

Der Git-Zugriff ist an einen Benutzer gebunden

Für das Herunterladen des Landscape-Repositorys wird die Git-Verbindung des Benutzers verwendet, der den Provider erstellt (oder zuletzt aktualisiert) hat. Verliert dieser Benutzer den Zugriff auf das Repository, schlagen Deployments des Providers fehl. Um den Provider auf die Git-Verbindung eines anderen Benutzers zu übertragen, sendet dieser Benutzer einen PUT- oder PATCH-Request für den Provider – dessen Verbindung wird anschließend zum Herunterladen verwendet. Für langlebige Provider empfiehlt sich die Veröffentlichung mit einem technischen Benutzer.

Provider-Schema​

Die Provider-Definition legt alle Metadaten und Konfigurationsschemas für den Service Provider fest. Die beiden Providertypen 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 verweisen (backend.api) 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

Provider-Felder​

Diese Felder sind bei beiden Providertypen gleich:

FeldBeschreibung
nameEindeutiger Bezeichner für den Provider. Muss ^[-a-z0-9_]+$ entsprechen.
schemaVersionVersionsstring im Format v[0-9]+ (z. B. v0, v1). Zusammen mit name identifiziert dies einen Provider eindeutig.
displayNameFür Menschen lesbarer Name, der im Marketplace angezeigt wird.
iconUrlURL zum Provider-Icon (absoluter oder relativer Pfad).
categoryGruppierungskategorie (z. B. databases, messaging, monitoring).
authorOrganisation oder Einzelperson, die für den Provider verantwortlich ist.
descriptionMarkdown-formatierte Beschreibung des Dienstes.
documentationUrlOptionaler Link zu externer Dokumentation für den Dienst, wird in der Benutzeroberfläche angezeigt.
teamSingletonOptionaler Boolean. Wenn true, kann jedes Team nur einen nicht gelöschten Service für diesen Provider und diese Version haben. Ein Service, der den Status deleted erreicht, blockiert eine Neuerstellung nicht mehr; ein Service, der noch gelöscht wird, hingegen schon. Weglassen oder auf false setzen, um mehrere Services zuzulassen.
configSchemaOpenAPI-Schema, das benutzerkonfigurierbare Optionen definiert. Siehe configSchema.
secretsSchemaOpenAPI-Schema, das geheime Werte (z. B. Passwörter) definiert. Siehe secretsSchema.
detailsSchemaOpenAPI-Schema, das nach der Bereitstellung offengelegte Runtime-Details definiert. Siehe detailsSchema.

Die übrigen Felder hängen vom Providertyp ab:

FeldBeschreibung
backend.landscape.gitUrlGit-Repository-URL, die die Landscape-Konfiguration enthält.
configSchemaOpenAPI-Schema, das benutzerkonfigurierbare Optionen definiert. Diese Werte werden der Landscape als Umgebungsvariablen übergeben.
secretsSchemaOpenAPI-Schema, das geheime Werte (z. B. Passwörter) definiert. Diese Werte werden im Secrets-Vault der Landscape hinterlegt.
detailsSchemaOpenAPI-Schema, das nach der Bereitstellung offengelegte Runtime-Details definiert. Siehe Standard-Landscape-Details.
plansOptional. Weglassen oder auf [] setzen, um die Plan-Auswahl in der Benutzeroberfläche zu deaktivieren. Landscape-Provider haben keine Plans.
versionsVersionen des Dienstes, die Benutzer deployen können. Mindestens eine Version ist erforderlich. Siehe Provider-Versionen.

Capabilities bei Landscape-basierten Providern

Landscape-basierte Provider unterstützen noch keine Capabilities. Man kann sie dennoch mit false deklarieren, um in der Benutzeroberfläche ein explizites Kreuz ("nicht unterstützt") anzuzeigen; das Weglassen einer Capability blendet sie vollständig aus.

Konfigurationsschemas​

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

Die drei Schemas teilen sich ein Format – ein gültiges OpenAPI-Schemaobjekt

configSchema, secretsSchema und detailsSchema erfüllen unterschiedliche Zwecke, müssen aber jeweils ein gültiges OpenAPI-Schemaobjekt sein – so werden sie von Codesphere geparst. Wie bei OpenAPI können Eigenschaften als required markiert oder mit sinnvollen default-Werten versehen werden.

Property-Schlüssel werden in der Benutzeroberfläche in lesbare Bezeichnungen umgewandelt

Codesphere zeigt Benutzern nicht die rohen Schlüssel an – sie werden in der Benutzeroberfläche in lesbare Bezeichnungen umgewandelt (z. B. wird service_url_frontend_3000 als Service Url Frontend 3000 angezeigt).

configSchema​

Das configSchema definiert die Konfigurationseigenschaften, die der Benutzer bei der Erstellung eines Services festlegt – zum Beispiel die zu deployende PostgreSQL-Version. Bei Landscape-basierten Providern werden diese Werte der Landscape als Umgebungsvariablen übergeben (siehe Konfiguration an Landscapes übergeben); bei REST-basierten Providern werden sie im Body des Erstellungs-/Aktualisierungs-Requests an das 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 Aktualisierungsbeschränkungen).

Config Schema in den Service-Einstellungen

vorsicht

Das Aktualisieren von Konfigurationsparametern kann zu einer kurzen Ausfallzeit des Services führen.

Aktualisierungsbeschrä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 Services geändert werden können. Das ist nützlich, um operative Regeln durchzusetzen – zum Beispiel um zu verhindern, dass Storage verringert wird, oder um eine Datenbank-Engine-Version nach der Ersteinrichtung zu sperren.

Das Schlüsselwort x-update-constraint kann jeder Eigenschaft 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: minor-upgrade-only
BeschränkungVerhalten
increase-onlyDer neue Wert muss größer oder gleich dem aktuellen Wert sein. Gilt nur für numerische Felder.
minor-upgrade-onlyDer neue Wert darf sich nur innerhalb derselben Hauptversion vorwärtsbewegen (z. B. 17.6 → 17.9, aber nicht 16.x → 17.x). Gedacht für Versionsfelder.
immutableDie Eigenschaft kann nach dem Setzen nicht mehr geändert werden.

info

Aktualisierungsbeschränkungen werden nur beim Aktualisieren eines bestehenden Services durchgesetzt. Bei der Ersterstellung werden alle Werte akzeptiert, solange sie die standardmäßige Schema-Validierung bestehen.

secretsSchema​

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

Secrets Schema im Dialog zum Erstellen eines Services

detailsSchema​

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

Details Schema in den Service-Einstellungen

Standard-Landscape-Details​

Nur Landscape-basierte Provider

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

SchlüsselWert
hostnameDie URL der Landscape.
service_url_<serverName>_<port>Die URL eines Services, ein Eintrag pro in der Landscape definiertem Service.

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 Services anzuzeigen, müssen sie im detailsSchema deklariert werden:

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

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. 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 gegen das Schema der Eigenschaft.

Die Endpunkt-URL ist eine Vorlage: Andere Detail-Felder können mit der Syntax ${{ .field_name }} referenziert werden, und Codesphere ersetzt deren Werte, bevor der Request ausgeführt wird. So kann der Endpunkt aus Details aufgebaut werden, 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-Services abgerufen. Die Vorlage löst ${{ .service_url_frontend_3000 }} zur URL des laufenden Services auf, sodass der endgültige Request an <service-url>/health geht und die JSON-Antwort status.state befüllt.

info

Für x-endpoint werden nur GET-Requests unterstützt. Der Endpunkt muss JSON zurückgeben, das der Schemadefinition der Eigenschaft entspricht.

Unterstützte Formate​

Provider-Schemas unterstützen die standardmäßigen OpenAPI-format-Werte zur Validierung:

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

Über die Validierung hinaus verändern manche Formate, wie ein Wert in der Codesphere-Benutzeroberfläche dargestellt wird:

FormatAuswirkung in der Benutzeroberfläche
uri, hostnameIm Details-Bereich der Service-Einstellungen wird der Wert als anklickbarer Link statt als reiner Text dargestellt. Zu verwenden für detailsSchema-Eigenschaften wie hostname oder service_url_*.
passwordIm Dialog zum Erstellen eines Services wird das entsprechende secretsSchema-Feld als maskiertes Passwort-Eingabefeld statt als reines Textfeld dargestellt.
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

Konfiguration und Secrets an Landscapes übergeben​

Nur Landscape-basierte Provider

Wenn ein Service aus einem Landscape-basierten Provider erstellt wird, wird die Eingabe des Benutzers an die Landscape weitergegeben: Eigenschaften aus configSchema werden als Umgebungsvariablen gesetzt, und Secrets aus secretsSchema werden in den Vault der Landscape eingefügt. 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 angibt, welche Lifecycle-Funktionen das Backend eines Providers unterstützt. Jeder Eintrag ist ein Boolean und wird in der Service-Benutzeroberfläche angezeigt: true stellt ein Häkchen dar, false ein explizites Kreuz ("nicht unterstützt"), und eine weggelassene Capability wird vollständig ausgeblendet.

CapabilityBeschreibung
pauseDer Service kann pausiert und später fortgesetzt werden, wodurch Rechenleistung freigegeben wird, während die Daten erhalten bleiben.
backupsDer Service unterstützt Backups in einen externen Speicher. Erfordert den Schemablock backups. Siehe Managed Service Backups.
pointInTimeRecoveryDer Service kann auf einen beliebigen Zeitpunkt wiederhergestellt werden, nicht nur auf diskrete Backup-Snapshots.
highAvailabilityDer Service kann in einer hochverfügbaren Konfiguration betrieben werden (z. B. redundante Replikate mit Failover).

hinweis

Capabilities beschreiben, was das Backend eines Providers implementiert. Landscape-basierte Provider können noch keine dieser Capabilities unterstützen.

Plans und Resource Parameters​

Nur REST-basierte Provider

Landscape-basierte Provider haben noch keine konfigurierbaren Plans.

Ein REST-basierter Provider beschreibt seine abrechenbaren Ressourcen in zwei zusammenwirkenden Teilen:

  • resourceParameters legt fest, welche Ressourcen existieren und wie sie validiert werden – einmal auf Provider-Ebene definiert.
  • plans sind benannte Vorgaben, die konkrete Werte für diese Ressourcen festlegen – eine schnelle, unkomplizierte Wahl für den Benutzer (Small, Medium, …).

Das Backend sieht diese ausführliche Definition nie. Wenn ein Service erstellt oder aktualisiert wird, löst Codesphere den ausgewählten Plan auf und sendet dem Backend nur die flachen Werte (siehe Erstellen eines eigenen REST-Backends):

{ "plan": { "parameters": { "storage": 10240, "cpu": 5, "memory": 512 } } }

Resource Parameters​

Jeder Eintrag unter resourceParameters hat zwei Felder:

FeldBeschreibung
pricedAsKennzeichnet den Parameter für Nutzungserfassung und Abrechnung. Einer von cpu-tenths, ram-mib, storage-mib, network-bandwidth-mbps, replicas oder free. Standardmäßig free. Für eine wirklich kostenneutrale Option empfiehlt sich stattdessen eine configSchema-Eigenschaft.
schemaEin OpenAPI-Schemaobjekt, das den Wert validiert – immer numerisch (type: integer oder type: number). Unterstützt minimum, maximum, description und x-update-constraint, genau wie configSchema.

Ein Parameter kann mit readOnly: true festgelegt werden: Benutzer können ihn dann nicht direkt ändern, sodass ein Plan der einzige Weg ist, einen anderen Wert festzulegen. Bleibt er konfigurierbar (der Standard), können Benutzer den Wert des Plans innerhalb der minimum/maximum-Grenzen des Schemas feinjustieren.

Da das Schema hier und nicht in jedem Plan liegt, wird eine Grenze oder Beschränkung nur einmal geschrieben und gilt für jeden Plan – keine Wiederholung, nichts, was synchron gehalten werden muss.

Plans​

Jeder Plan liefert einen konkreten Wert für jeden Schlüssel in resourceParameters:

FeldBeschreibung
idGanzzahl, eindeutig innerhalb des Providers. Identifiziert den Plan bei der Erstellung eines Services.
nameKurze Bezeichnung, die in der Benutzeroberfläche angezeigt wird (z. B. Small).
descriptionFür Menschen lesbare Zusammenfassung der Stufe (z. B. 0.5 vCPU / 500 MB Memory).
parametersEine flache Map von resourceParameter-Namen zu Werten. Jeder Wert ist der Standardwert des Plans für diesen Parameter – festgelegt, wenn der Parameter readOnly ist, andernfalls der Ausgangswert, den der Benutzer anpassen kann.

Alle Plans teilen sich dasselbe Schema, daher sollte jeder Plan einen Wert für jeden in resourceParameters deklarierten Parameter bereitstellen.

Plans sind optional. plans weglassen (oder auf ein leeres Array setzen), um die Plan-Auswahl vollständig zu überspringen – Codesphere sendet dann keinen plan an das Backend, und das Backend entscheidet, was deployt wird.

Provider-Versionen​

Nur Landscape-basierte Provider

Jeder Landscape-basierte Provider muss mindestens einen Eintrag in versions definieren. Jede Version legt den genauen Stand der Landscape fest, der deployt wird:

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

Beim Erstellen eines Services wählen Benutzer aus, welche Version deployt werden soll. Benutzer können die Version ihrer deployten Services ändern, wodurch ein Upgrade oder Downgrade ausgelöst wird. Weitere Informationen dazu finden sich unter Upgrade auf eine neue Version.

Veraltete Felder

backend.landscape.ciProfile und backend.landscape.gitRef dienten früher dazu, diese Werte einmal für den gesamten Provider festzulegen. Sie sind veraltet – ciProfile und gitRef werden jetzt pro Version definiert – bleiben aber aus Gründen der Abwärtskompatibilität verfügbar.

Einen Provider in der Benutzeroberfläche erstellen​

Statt die Provider-Datei von Hand zu schreiben, kann man eine Definition in der Codesphere-Benutzeroberfläche erstellen und direkt im Katalog veröffentlichen. Es handelt sich um einen formularbasierten Editor für dasselbe oben beschriebene Provider-Schema, mit einer Live-Vorschau der resultierenden Definition, die als YAML oder JSON kopiert oder heruntergeladen werden kann – zum Beispiel, um sie als provider.yml im eigenen Repository zu committen. Alles, was die Felder erfordern und erzeugen, entspricht genau dem, was zuvor auf dieser Seite dokumentiert wurde.

TabOptionWas diese Option macht
Create Provider DefinitionStart from LandscapeLiest eine ci.yml aus einem Git-Repository und füllt das Formular damit vor.
Create Provider DefinitionStart from ScratchÖffnet ein leeres Formular.
Import Provider DefinitionFrom Git RepoRuft eine bestehende Provider-Datei aus einem Git-Repository ab und lädt sie in das Formular.
Import Provider DefinitionPaste SchemaLädt eine eingefügte Provider-Definition als YAML oder JSON.

Unabhängig von der gewählten Option führt Start zum selben Editor – der Einstiegspunkt entscheidet nur, wie viel vom Formular bereits ausgefüllt ist.

Definition erstellen​

Über den Tab Create Provider Definition kann eine neue Provider-Definition erstellt werden – entweder abgeleitet von einer bereits vorhandenen Landscape oder aus einem leeren Formular.

Start from Landscape leitet einen ersten Entwurf der Definition aus einem bestehenden Landscape-Repository ab, sodass nicht abgeschrieben werden muss, was die ci.yml bereits deklariert.

Tab Create Provider Definition mit ausgewählter Option Start from Landscape

FeldBeschreibung
Repository URLDas Landscape-Repository. Es muss über einen der in den persönlichen Git-Berechtigungseinstellungen verbundenen Git-Provider erreichbar sein.
GitRefOptionaler Commit, Branch oder Tag. Standardmäßig der HEAD des Repositorys.
CI ProfileOptionaler Profilname (z. B. prod, aufgelöst zu ci.prod.yml) oder ein expliziter Dateipfad (z. B. ci.dev.yml). Standardmäßig ci.yml.

Codesphere ruft das ausgewählte CI-Profil ab, parst es und füllt anschließend vor:

  • name — als Slug aus dem Repository-Namen abgeleitet (kleingeschrieben, alles außerhalb von a–z, 0–9, - und _ wird durch - ersetzt).
  • configSchema — ein Eintrag pro im Profil gefundener Referenz ${{ workspace.env.KEY }}.
  • secretsSchema — ein Eintrag pro im Profil gefundener Referenz ${{ vault.KEY }}.
  • backend.landscape.gitUrl, sowie ein erster versions-Eintrag 0.0.1, festgelegt auf die eingegebenen gitRef und ciProfile.

Alles auf diese Weise Abgeleitete ist ein Ausgangspunkt – Einträge im Formular können vor der Veröffentlichung bearbeitet, hinzugefügt oder entfernt werden. Da die Ableitung an eine Landscape gebunden ist, bleibt der Backend-Typ Landscape; für einen REST-basierten Provider empfiehlt sich Start from Scratch oder ein Import.

Eine bestehende Definition importieren​

Der Tab Import Provider Definition ist zu verwenden, wenn bereits eine Provider-Definition existiert – um eine in Git gepflegte Definition zu verfeinern, den Provider einer anderen Person anzupassen, oder eine zuvor aus dem Vorschaubereich exportierte Definition erneut zu bearbeiten.

Die Provider-Datei wird direkt aus einem Repository importiert:

Tab Import Provider Definition mit ausgewählter Option From Git Repo

FeldBeschreibung
Repository URLRepository, das die Provider-Datei enthält.
GitRefOptionaler Commit, Branch oder Tag. Standardmäßig der HEAD des Repositorys.
Provider DefinitionOptionaler Pfad zur Provider-Datei. Standardmäßig provider.yml im Root-Verzeichnis des Repositorys.

Das Formular ausfüllen​

Das Formular ist in Abschnitte gegliedert, die dem Provider-Schema entsprechen — Core, Metadata, Configuration Options, Instance Details, Secrets Schema, Plans & Resource Parameters und, bei Landscape-basierten Providern, Versions. Die daneben angezeigte Provider Definition Preview aktualisiert sich während der Eingabe, sodass jederzeit die Definition sichtbar ist, die veröffentlicht werden soll.

Formular Provider Configuration mit Live-Vorschau der Provider-Definition

Copy Snippet As und Download As exportieren die angezeigte Definition als YAML oder JSON. Der Export ist aktiviert, sobald die Definition gültig ist — bei einem Landscape-basierten Provider bedeutet das mindestens eine Version sowie gültige Abschnitte für Config, Details und Secrets. Erst wenn die exportierte Datei als provider.yml im eigenen Repository committet wird, funktionieren die Git-basierten Veröffentlichungsabläufe später einwandfrei.

Veröffentlichen aus dem Editor​

Publish to Catalog öffnet den Veröffentlichungsdialog:

Dialog Publish Provider über dem Formular und der Live-Vorschau der Definition

FeldBeschreibung
Publishing ScopeResource Group veröffentlicht in den ausgewählten Resource Groups; Global veröffentlicht für die gesamte Organisation und erfordert Cluster-Admin-Berechtigungen. Siehe Provider-Scopes.
Resource GroupWird beim Scope Resource Group angezeigt. Listet nur die Resource Groups auf, in denen man Admin ist.
API SecretWird nur bei REST-basierten Providern angezeigt. Optionales Bearer-Token, das Codesphere im Auth-Header jedes Requests an den eigenen Endpunkt sendet. Es bleibt außerhalb des Formulars und der Vorschau, sodass es niemals in einer exportierten Provider-Datei landet.

Die Veröffentlichung führt denselben idempotenten Upsert wie PUT /managed-services/providers durch: Existiert noch kein Provider mit demselben name und derselben schemaVersion, wird er erstellt; existiert bereits einer, werden seine veränderbaren Felder direkt aktualisiert. Das erneute Veröffentlichen einer bearbeiteten Definition aktualisiert somit den bestehenden Provider, statt einen zweiten zu erstellen — und das Veröffentlichen unter einem bereits vergebenen name überschreibt diesen Provider, daher sollte ein eindeutiger Name gewählt werden, sofern keine Aktualisierung beabsichtigt ist.

Nach erfolgreicher Veröffentlichung erfolgt eine Weiterleitung zum Services Catalog, wo der Provider nun für die ausgewählten Scopes verfügbar ist.

Provider veröffentlichen und verwalten​

Sobald ein Provider definiert ist, wird er über die Codesphere Public API in Codesphere veröffentlicht — oder, falls er im Provider-Editor erstellt wurde, direkt von dort aus. Die im Folgenden beschriebenen Mechanismen zum Veröffentlichen, Aktualisieren, Löschen, Scoping und für Singletons gelten gleichermaßen für Landscape-basierte und REST-basierte Provider.

info

Das Veröffentlichen von Providern erfordert Cluster-Admin-Berechtigungen. Team-Admins können beantragen, dass Provider für bestimmte Teams eingeschränkt werden.

Provider-Scopes​

Beim Erstellen eines Providers kann dessen Sichtbarkeits-Scope festgelegt werden:

Scope-TypBeschreibung
globalFür alle Teams der Codesphere-Instanz verfügbar. Erfordert Cluster-Admin-Berechtigungen.
teamNur für angegebene Teams verfügbar. Ein Array von teamIds angeben.

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​

Der empfohlene Weg, einen Provider zu veröffentlichen und zu aktualisieren, ist der idempotente Upsert-Endpunkt. Dazu einen PUT-Request an /managed-services/providers senden:

  • 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, derselbe Request 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.

Entweder eine Git-URL, die die Provider-Datei enthält, oder die vollständige Provider-Spezifikation im Payload kann angegeben werden.

tipp

Eigene Endpunkte zum Erstellen (POST) und Aktualisieren (PATCH) existieren weiterhin für partielle Aktualisierungen und explizitere Abläufe, aber für die meisten Fälle ist der Upsert-Endpunkt die einfachste Wahl. Siehe Einen Provider direkt aktualisieren.

Versionen können nur angehängt werden

Bei Landscape-basierten Providern können neue Einträge zu versions hinzugefügt werden, aber bestehende Versionseinträge können durch einen Upsert nicht geändert oder entfernt werden. Alle anderen Provider-Felder werden direkt aktualisiert.

Der einfachste Ansatz ist die Angabe der Git-Repository-URL. Codesphere ruft die Provider-Datei automatisch aus dem Repository ab und validiert sie. Standardmäßig wird nach provider.yml im Root-Verzeichnis des Repositorys gesucht; wird diese Datei nicht gefunden, wird auf provider.yaml zurückgegriffen.

hinweis

Wird gitRef weggelassen, wird der Standard-Branch des Repositorys verwendet, um die Provider-Datei abzurufen.

Um einen anderen Dateinamen oder Speicherort zu verwenden — zum Beispiel um mehrere Provider-Dateien in einem Repository zu pflegen — kann das optionale Argument filepath übergeben werden. Es wird relativ zum Root-Verzeichnis des Repositorys aufgelöst und ist standardmäßig provider.yml, wenn es weggelassen wird.

scope und filepath sind nicht Teil der Provider-Datei — sie werden hier, im Veröffentlichungs-Request, zusammen mit der Git-URL angegeben:

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"
    }
  }'

Einen Provider direkt aktualisieren​

Um bestimmte Felder zu ändern, ohne die gesamte Definition erneut einzureichen, wird der PATCH-Endpunkt verwendet. Nur die enthaltenen 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 — der endpoint kann somit aktualisiert werden, während das gespeicherte secret unverändert bleibt, oder ein neues secret kann angegeben werden, um es zu rotieren.

Secrets werden nie zurückgegeben (REST-basierte Provider)

Das Feld secret in backend.api wird sicher gespeichert, aber nie in der API-Antwort enthalten. Dies gilt für die PATCH-, PUT- und POST-Antworten bei REST-basierten Providern.

Einen Provider löschen​

Um einen Provider zu entfernen, wird ein DELETE-Request an /managed-services/providers/{name}/{schemaVersion} gesendet:

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.