Zum Hauptinhalt springen
Version: Weekly Build

Service Provider erstellen

Mit Codesphere lässt sich ein Service als Managed Service Provider verpacken, sodass andere Entwickler ihn im Service-Katalog finden und bereitstellen können. Provider gibt es in zwei Arten:

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

Eine ausführlichere Erklärung der beiden Typen und wann welcher eingesetzt werden sollte, findet sich unter Service-Kategorien. Zur Implementierung des Backends hinter einem REST-basierten Provider siehe Ein 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. Die Definition kann von Hand geschrieben oder im Provider-Editor der Benutzeroberfläche zusammengestellt werden.

Einen Provider definieren​

Voraussetzungen​

Ein landscape-basierter Provider stellt eine Landscape aus einem Git-Repository bereit. Bevor einer erstellt wird, sind folgende Dinge nötig:

  1. Ein Git-Repository mit einer gültigen Codesphere-Landscape inklusive ci.yml-Datei.
  2. Eine Provider-Definition, entweder als Provider-Datei im Repository (standardmäßig provider.yml oder provider.yaml im Stammverzeichnis, oder ein eigener Pfad über das Argument filepath) oder direkt in der API-Anfrage angegeben.
  3. Git-Zugriff auf das Landscape-Repository. Codesphere zieht das Repository über die eigene Git-Verbindung, daher muss das Konto, mit dem der Provider erstellt wird, Zugriffsrechte darauf besitzen. Git-Verbindungen lassen sich in den Benutzereinstellungen verwalten.

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

Git-Zugriff ist an einen Benutzer gebunden

Für das Abrufen 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 eine PUT- oder PATCH-Anfrage für den Provider – anschließend wird dessen Verbindung zum Abrufen verwendet. Für langlebige Provider empfiehlt es sich, mit einem technischen Benutzer zu veröffentlichen.

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 eigenen 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 für beide Provider-Typen gleich:

FeldBeschreibung
nameEindeutiger Bezeichner für den Provider. Muss ^[-a-z0-9_]+$ entsprechen.
schemaVersionVersionsstring im Format v[0-9]+ (z. B. v0, v1). Identifiziert zusammen mit name einen Provider eindeutig.
displayNameFür Menschen lesbarer Name, der im Marketplace angezeigt wird.
iconUrlURL zum Provider-Symbol (absoluter oder relativer Pfad).
categoryGruppierungskategorie (z. B. databases, messaging, monitoring).
authorOrganisation oder Einzelperson, die für den Provider verantwortlich ist.
descriptionMarkdown-formatierte Beschreibung des Service.
documentationUrlOptionaler Link zur externen Dokumentation des Service, wird in der Benutzeroberfläche angezeigt.
teamSingletonOptionaler boolescher Wert. Bei true kann jedes Team nur einen nicht gelöschten Service für diesen Provider und diese Version besitzen. Ein Service, der den Status deleted erreicht hat, blockiert eine Neuerstellung nicht mehr; ein Service, der sich noch im Löschvorgang befindet, schon. Weglassen oder auf false setzen erlaubt mehrere Services.
labelsOptionale Map aus beliebigen Schlüssel-Wert-Paaren, die zur eigenen Verwendung an einen Provider angehängt werden können (z. B. Zuständigkeit, Umgebung, Kostenstelle). Codesphere interpretiert diese Werte nicht. Bis zu 50 Einträge; Schlüssel bis zu 514 Zeichen, Werte bis zu 5000 Zeichen.
configSchemaOpenAPI-Schema, das vom Benutzer konfigurierbare Optionen definiert. Siehe configSchema.
secretsSchemaOpenAPI-Schema, das geheime Werte (z. B. Passwörter) definiert. Siehe secretsSchema.
detailsSchemaOpenAPI-Schema, das nach der Bereitstellung verfügbare Laufzeitdetails definiert. Siehe detailsSchema.

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

FeldBeschreibung
backend.landscape.gitUrlGit-Repository-URL mit der Landscape-Konfiguration.
configSchemaOpenAPI-Schema, das vom Benutzer konfigurierbare 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 abgelegt.
detailsSchemaOpenAPI-Schema, das nach der Bereitstellung verfügbare Laufzeitdetails definiert. Siehe Standard-Landscape-Details.
plansOptional. Weglassen oder auf [] setzen, um die Planauswahl in der Benutzeroberfläche zu deaktivieren. Landscape-Provider haben keine Pläne.
versionsVersionen des Service, die Benutzer bereitstellen können. Mindestens eine Version ist erforderlich. Siehe Provider-Versionen.
Capabilities bei landscape-basierten Providern

Landscape-basierte Provider unterstützen bislang keine Capabilities. Sie können trotzdem mit false deklariert werden, um in der Benutzeroberfläche ein explizites Kreuz ("nicht unterstützt") anzuzeigen; wird eine Capability weggelassen, wird sie vollständig ausgeblendet.

Konfigurationsschemas​

Ein Provider definiert bis zu drei Schemas: configSchema, secretsSchema und detailsSchema. Sie dienen unterschiedlichen Zwecken, werden aber gleich geparst.

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

configSchema, secretsSchema und detailsSchema dienen unterschiedlichen Zwecken, müssen aber jeweils ein gültiges OpenAPI-Schemaobjekt sein — so werden sie von Codesphere geparst. Wie in OpenAPI können Eigenschaften als required markiert oder mit sinnvollen default-Werten versehen werden.

Eigenschaftsschlüssel werden in der Benutzeroberfläche in lesbare Bezeichnungen umgewandelt

Codesphere zeigt den Benutzern nicht die rohen Schlüssel an, sondern wandelt sie in der Benutzeroberfläche in lesbare Bezeichnungen um (z. B. wird service_url_frontend_3000 als Service Url Frontend 3000 angezeigt).

configSchema​

Das configSchema definiert die Konfigurationseigenschaften, die der Benutzer beim Erstellen eines Service festlegt — zum Beispiel die zu installierende 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 Anfragekörper der Erstellungs-/Aktualisierungsanfrage an das eigene Backend gesendet. Nach der Erstellung des Service lässt sich die Konfiguration in den Service-Einstellungen einsehen. 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 einem kurzen Ausfall des Service führen.

Aktualisierungsbeschränkungen mit x-update-constraint​

Das configSchema unterstützt eine benutzerdefinierte Erweiterung x-update-constraint, mit der sich einschränken lässt, wie einzelne Eigenschaften nach der Erstellung eines Service geändert werden können. Das ist nützlich, um operative Regeln durchzusetzen — zum Beispiel um zu verhindern, dass Speicherplatz verringert wird, oder um die Version einer Datenbank-Engine nach der Ersteinrichtung festzuschreiben.

Das Schlüsselwort x-update-constraint kann zu 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 nach vorne bewegen (z. B. 17.6 → 17.9, aber nicht 16.x → 17.x). Für Versionsfelder gedacht.
immutableDie Eigenschaft kann nach ihrer Festlegung nicht mehr geändert werden.
info

Aktualisierungsbeschränkungen werden nur bei der Aktualisierung eines bestehenden Service durchgesetzt. Bei der Erstellung werden alle Werte akzeptiert, solange sie die reguläre Schemavalidierung bestehen.

secretsSchema​

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

Secrets Schema im Dialog zum Erstellen eines Service

detailsSchema​

In detailsSchema definierte Eigenschaften werden vom Service zur Laufzeit bereitgestellt — zum Beispiel der PostgreSQL-Hostname. Sie sind schreibgeschützt und können im Detailsbereich 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 Service, ein Eintrag pro in der Landscape definiertem Service.

Eine Landscape mit einem frontend-Service auf Port 3000 erzeugt zum Beispiel service_url_frontend_3000. Um diese Werte auf der Detailseite des Service 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 sich Laufzeitdetails dynamisch vom eigenen Service abrufen lassen. Das ist nützlich, um Live-Statusinformationen, Metriken oder andere Daten abzurufen, die sich nach der Bereitstellung ändern.

Wird x-endpoint für eine 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: Mit der Syntax ${{ .field_name }} lässt sich auf andere Detailfelder verweisen, und Codesphere ersetzt deren Werte vor dem Senden 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 über den /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.

info

Für x-endpoint werden nur GET-Anfragen 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 Service erstellen wird das entsprechende secretsSchema-Feld als maskiertes Passwortfeld statt als Klartextfeld 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, werden die Eingaben des Benutzers an die Landscape weitergegeben: Eigenschaften aus configSchema werden als Umgebungsvariablen gesetzt, und Secrets aus secretsSchema werden in das Vault der Landscape injiziert. Beides kann 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.

Capabilities​

capabilities ist eine optionale Map, die festlegt, welche Lifecycle-Funktionen das Backend eines Providers unterstützt. Jeder Eintrag ist ein boolescher Wert und wird in der Service-Benutzeroberfläche angezeigt: true zeigt ein Häkchen, 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, wobei Rechenleistung freigegeben wird, während die Daten erhalten bleiben.
backupsDer Service unterstützt Backups auf einen externen Speicher. Erfordert den backups-Schemablock. 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 Replicas mit Failover).
hinweis

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

Pläne und Ressourcenparameter​

Nur REST-basierte Provider

Landscape-basierte Provider verfügen noch nicht über konfigurierbare Pläne.

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 eigene Backend bekommt diese umfangreiche Definition nie zu sehen. Wenn ein Service erstellt oder aktualisiert wird, löst Codesphere den ausgewählten Plan auf und sendet dem eigenen Backend nur die flachen Werte (siehe Ein eigenes REST-Backend erstellen):

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

Ressourcenparameter​

Jeder Eintrag unter resourceParameters besteht aus zwei Feldern:

FeldBeschreibung
pricedAsKennzeichnet den Parameter für die Nutzungserfassung und Abrechnung. Einer von cpu-tenths, ram-mib, storage-mib, network-bandwidth-mbps, replicas oder free. Standardwert ist free. Für eine wirklich kostenneutrale Option ist eine configSchema-Eigenschaft vorzuziehen.
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 mit readOnly: true wird fixiert: Benutzer können ihn nicht direkt ändern, sodass ein Plan die einzige Möglichkeit ist, einen anderen Wert festzulegen. Konfigurierbar belassen (Standard) erlaubt Benutzern, den Wert des Plans innerhalb der minimum/maximum-Grenzen des Schemas fein abzustimmen.

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

Pläne​

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 Service.
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 aus resourceParameter-Name → Wert. Jeder Wert ist der Standardwert des Plans für diesen Parameter — fixiert, wenn der Parameter readOnly ist, andernfalls der Ausgangspunkt, den der Benutzer anpassen kann.

Alle Pläne teilen sich dasselbe Schema, daher sollte jeder Plan einen Wert für jeden in resourceParameters deklarierten Parameter angeben.

Pläne sind optional. plans weglassen (oder als leeres Array angeben), um die Planauswahl vollständig zu überspringen — Codesphere sendet dann keinen plan an das eigene Backend, und das Backend entscheidet selbst, was bereitgestellt wird.

Provider-Versionen​

Nur landscape-basierte Provider

Jeder landscape-basierte Provider muss mindestens einen Eintrag in versions definieren. Jede Version fixiert den genauen Zustand der bereitzustellenden Landscape:

  • 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 für die bereitgestellte Anwendungsversion.
  • description (optional): Markdown-formatierte Release-Notes, die dem Benutzer angezeigt werden.

Beim Erstellen eines Service wählen Benutzer aus, welche Version bereitgestellt werden soll. Benutzer können die Version ihrer bereitgestellten Services ändern, was ein Upgrade oder Downgrade auslöst. Weitere Informationen 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 weiterhin verfügbar.

Einen Provider in der Benutzeroberfläche erstellen​

Statt die Provider-Datei von Hand zu schreiben, lässt sich eine Definition in der Codesphere-Benutzeroberfläche erstellen und direkt im Katalog veröffentlichen. Es handelt sich um einen formularbasierten Editor für das gleiche oben beschriebene Provider-Schema, mit einer Live-Vorschau der entstehenden 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 weiter oben auf dieser Seite dokumentiert ist.

TabOptionWas sie bewirkt
Create Provider DefinitionStart from LandscapeLiest eine ci.yml aus einem Git-Repository ein und füllt das Formular daraus 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 bestimmt nur, wie viel des Formulars bereits vorausgefüllt ist.

Definition erstellen​

Mit dem Tab Create Provider Definition lässt sich ein neuer Provider erstellen — entweder abgeleitet aus 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.

Create Provider Definition-Tab 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). Standardwert ist ci.yml.

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

  • name — aus dem Repository-Namen in Kleinbuchstaben generiert (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, plus ein erster versions-Eintrag 0.0.1, fixiert auf das eingegebene gitRef und ciProfile.

Alles, was auf diese Weise abgeleitet wird, ist ein Ausgangspunkt — Einträge können im Formular 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 Start from Scratch oder einen Import verwenden.

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 von jemand anderem anzupassen oder eine zuvor aus dem Vorschaubereich exportierte Definition erneut zu bearbeiten.

Die Provider-Datei direkt aus einem Repository importieren:

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

FeldBeschreibung
Repository URLRepository mit der Provider-Datei.
GitRefOptionaler Commit, Branch oder Tag. Standardmäßig der Head des Repositorys.
Provider DefinitionOptionaler Pfad zur Provider-Datei. Standardwert ist provider.yml im Stammverzeichnis 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, für landscape-basierte Provider, Versions. Die daneben befindliche Provider Definition Preview aktualisiert sich während der Eingabe, sodass stets die Definition sichtbar ist, die gleich veröffentlicht wird.

Provider Configuration-Formular mit der Live Provider Definition Preview

Copy Snippet As und Download As exportieren die in der Vorschau angezeigte Definition als YAML oder JSON. Der Export wird aktiviert, sobald die Definition gültig ist — bei einem landscape-basierten Provider bedeutet das mindestens eine Version sowie gültige Config-, Details- und Secrets-Abschnitte. Das Committen der exportierten Datei als provider.yml im eigenen Repository ist die Voraussetzung dafür, dass die Git-basierten Veröffentlichungs-Workflows später funktionieren.

Aus dem Editor veröffentlichen​

Publish to Catalog öffnet den Veröffentlichungsdialog:

Publish Provider-Dialog ü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-Administratorrechte. Siehe Provider-Geltungsbereiche.
Resource GroupWird beim Geltungsbereich Resource Group angezeigt. Listet nur die Resource Groups auf, in denen ein Admin-Status vorliegt.
API SecretWird nur bei REST-basierten Providern angezeigt. Optionales Bearer-Token, das Codesphere im Auth-Header jeder Anfrage an den eigenen Endpunkt sendet. Es wird außerhalb des Formulars und der Vorschau gehalten, sodass es nie in einer exportierten Provider-Datei landet.

Die Veröffentlichung führt dasselbe idempotente Upsert durch wie PUT /managed-services/providers: Existiert noch kein Provider mit demselben name und derselben schemaVersion, wird einer erstellt; existiert bereits einer, werden dessen veränderbare Felder direkt aktualisiert. Das erneute Veröffentlichen einer bearbeiteten Definition aktualisiert daher 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 Geltungsbereiche verfügbar ist.

Provider veröffentlichen und verwalten​

Sobald ein Provider definiert ist, lässt er sich über die Codesphere Public API in Codesphere veröffentlichen — oder, falls er im Provider-Editor erstellt wurde, direkt von dort aus. Die unten beschriebenen Mechanismen für Veröffentlichung, Aktualisierung, Löschung, Geltungsbereich und Singleton gelten gleichermaßen für landscape-basierte und REST-basierte Provider.

info

Das Veröffentlichen von Providern erfordert Cluster-Administratorrechte. Team-Administratoren können beantragen, dass Provider auf bestimmte Teams beschränkt werden.

Provider-Geltungsbereiche​

Beim Erstellen eines Providers lässt sich dessen Sichtbarkeitsbereich festlegen:

Geltungsbereich-TypBeschreibung
globalVerfügbar für alle Teams der Codesphere-Instanz. Erfordert Cluster-Administratorrechte.
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 eine PUT-Anfrage 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, dieselbe Anfrage kann sowohl zum Erstellen eines Providers als auch zum Ausrollen späterer Änderungen verwendet werden — es muss nicht nachgehalten werden, ob der Provider bereits existiert. Das ist zum Beispiel in CI/CD-Pipelines nützlich.

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

tipp

Dedizierte Create-Endpunkte (POST) und Update-Endpunkte (PATCH) existieren weiterhin für Teilaktualisierungen und explizitere Workflows, aber für die meisten Fälle ist der Upsert-Endpunkt die einfachste Wahl. Siehe Einen Provider direkt aktualisieren.

Versionen können nur hinzugefügt werden

Bei landscape-basierten Providern lassen sich neue Einträge zu versions hinzufügen, aber bestehende Versionseinträge können über ein Upsert nicht geändert oder entfernt werden. Alle anderen Provider-Felder werden direkt aktualisiert.

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

hinweis

Wird gitRef weggelassen, wird der Standard-Branch des Repositorys zum Abrufen der Provider-Datei verwendet.

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

scope und filepath sind nicht Teil der Provider-Datei — sie werden hier, in der Veröffentlichungsanfrage, 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​

Ein veröffentlichter Provider lässt sich über dessen Karte im Services Catalog bearbeiten oder durch Senden einer PATCH- oder PUT-Anfrage an /managed-services/providers/{name}/{schemaVersion}.

Breaking Changes im Schema vermeiden

Änderungen am Provider-Schema müssen abwärtskompatibel sein. Ein Breaking Change, wie das Entfernen eines Felds oder das verpflichtend machen eines neuen Felds, kann bestehende Services beeinträchtigen. Als Herausgeber liegt es in der eigenen Verantwortung, Schemaänderungen kompatibel zu halten.

Um bestimmte Felder zu ändern, ohne die gesamte Definition erneut einzureichen, den PATCH-Endpunkt verwenden. Nur die 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 lässt sich der endpoint aktualisieren, während das gespeicherte secret unverändert bleibt, oder ein neues secret angeben, 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. Das gilt für die PATCH-, PUT- und POST-Antworten bei REST-basierten Providern.

Einen Provider löschen​

warnung

Das Löschen eines Providers ist global. Der Provider wird für jede Resource Group, in der er verfügbar war, aus dem Katalog entfernt. Aktive Services dieses Providers hören auf, abgeglichen zu werden, und können beeinträchtigt werden.

Ein Provider lässt sich über dessen Karte im Services Catalog löschen, oder durch Senden einer 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.