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. Es gibt zwei Arten von Providern:

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

Eine genauere Erklärung der beiden Typen und wann welcher Typ sinnvoll ist, findet sich unter Service-Kategorien. Wie das Backend hinter einem REST-basierten Provider implementiert wird, ist unter Ein eigenes REST-Backend erstellen beschrieben.

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 in der UI zusammengestellt werden.

Einen Provider definieren​

Voraussetzungen​

Ein Landscape-basierter Provider stellt eine Landscape aus einem Git-Repository oder aus einem statischen Build-Artefakt bereit. Für ein Git-Repository wird Folgendes benötigt:

  1. Ein Git-Repository mit einer gültigen Codesphere-Landscape und einer ci.yml-Datei.
  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 filepath-Argument) oder direkt in der API-Anfrage angegeben.
  3. Git-Zugriff auf das Landscape-Repository. Codesphere ruft das Repository über die eigene Git-Verbindung ab, daher muss das verwendete Konto Zugriff darauf haben. 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. Bei langlebigen Providern 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 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

Provider-Felder​

Diese Felder sind bei beiden 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). Zusammen mit name identifiziert dieses Feld einen Provider eindeutig.
displayNameLesbarer Name, der im Marketplace angezeigt wird.
iconUrlURL zum Provider-Icon (absoluter oder relativer Pfad).
categoryGruppierungskategorie (z. B. databases, messaging, monitoring).
authorOrganisation oder Person, die für den Provider verantwortlich ist.
descriptionMarkdown-formatierte Beschreibung des Services.
documentationUrlOptionaler Link zur externen Dokumentation des Services, der in der UI angezeigt wird.
teamSingletonOptionaler Boolean. Bei true kann jede Resource Group nur einen nicht gelöschten Service für diesen Provider und diese Version haben. Ein Service mit Status deleted blockiert eine Neuerstellung nicht mehr; ein Service, der noch gelöscht wird, hingegen schon. Weglassen oder auf false setzen, um mehrere Services zuzulassen.
labelsOptionale Map aus frei wählbaren Schlüssel-Wert-Strings, die einem Provider für eigene Zwecke zugeordnet werden können (z. B. Eigentümerschaft, 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 für vom Benutzer konfigurierbare Optionen. Siehe configSchema.
secretsSchemaOpenAPI-Schema für geheime Werte (z. B. Passwörter). Siehe secretsSchema.
detailsSchemaOpenAPI-Schema für Laufzeitdetails, die nach der Bereitstellung angezeigt werden. Siehe detailsSchema.

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

FeldBeschreibung
backend.landscape.gitUrlGit-Repository-URL mit der Landscape-Konfiguration.
configSchemaOpenAPI-Schema für vom Benutzer konfigurierbare Optionen. Diese Werte werden der Landscape als Umgebungsvariablen übergeben.
secretsSchemaOpenAPI-Schema für geheime Werte (z. B. Passwörter). Diese Werte werden im Vault der Landscape abgelegt.
detailsSchemaOpenAPI-Schema für Laufzeitdetails, die nach der Bereitstellung angezeigt werden. Siehe Standard-Landscape-Details.
plansOptional. Weglassen oder auf [] setzen, um die Auswahl von Plänen in der UI zu deaktivieren. Landscape-Provider haben keine Pläne.
versionsVersionen des Services, die Benutzer bereitstellen können. Mindestens eine Version ist erforderlich. Siehe Provider-Versionen.
Capabilities bei Landscape-basierten Providern

Landscape-basierte Provider unterstützen bisher keine Capabilities. Sie können trotzdem mit false deklariert werden, um in der UI 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 verarbeitet.

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 verarbeitet. Wie in OpenAPI können Eigenschaften als required markiert oder mit sinnvollen default-Werten versehen werden.

Eigenschaftsschlüssel werden in der UI in lesbare Bezeichnungen umgewandelt

Codesphere zeigt Benutzern nicht die rohen Schlüssel an — sie werden in der UI in lesbare Bezeichnungen umgewandelt (zum Beispiel wird service_url_frontend_3000 als Service Url Frontend 3000 angezeigt).

configSchema​

Das configSchema definiert die Konfigurationseigenschaften, die der Benutzer beim Erstellen eines Services festlegt — zum Beispiel die bereitzustellende 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 der Erstellungs-/Aktualisierungsanfrage an das Backend gesendet. Nach der Erstellung des Services lässt sich die Konfiguration in den Service-Einstellungen einsehen. Eigenschaften, die nicht als readOnly markiert sind, können später geändert werden (siehe Update-Constraints).

Config Schema in den Service-Einstellungen

vorsicht

Das Aktualisieren von Konfigurationsparametern kann eine kurze Ausfallzeit des Services verursachen.

Update-Constraints 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 Services geändert werden können. Das ist nützlich, um Betriebsregeln durchzusetzen — zum Beispiel zu verhindern, dass der Speicher verkleinert wird, oder um die Version einer Datenbank-Engine 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
ConstraintVerhalten
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 dem Setzen nicht mehr geändert werden.
info

Update-Constraints werden nur beim Aktualisieren eines bestehenden Services durchgesetzt. Bei der Ersterstellung werden alle Werte akzeptiert, solange sie die reguläre Schemavalidierung bestehen.

secretsSchema​

In secretsSchema definierte Secrets erscheinen im Dialog zum Erstellen eines Services als Formularfelder 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: bei Landscape-basierten Providern in den Vault der Landscape, bei REST-basierten Providern als secrets an das Backend gesendet. Wird eine Eigenschaft mit format: password markiert, wird sie als maskiertes Eingabefeld mit einer Schaltfläche dargestellt, die einen zufälligen Wert gemäß dem Schema der Eigenschaft generiert (siehe Generierte Passwörter).

Secrets Schema im Dialog zum Erstellen eines Services

detailsSchema​

Im detailsSchema definierte Eigenschaften werden vom Service zur Laufzeit bereitgestellt — zum Beispiel der PostgreSQL-Hostname. Sie sind schreibgeschützt und lassen sich im Bereich "Details" der Service-Einstellungen einsehen.

Details Schema in den Service-Einstellungen

Standard-Landscape-Details​
Nur für Landscape-basierte Provider

Bei Landscape-basierten Providern werden die folgenden 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 Detailseite 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 sich Laufzeitdetails dynamisch vom Service abrufen lassen. Das 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 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 }} lassen sich andere Detailfelder referenzieren, deren Werte Codesphere vor dem Senden der Anfrage einsetzt. So lässt sich der Endpunkt aus Details zusammensetzen, die erst nach der Bereitstellung bekannt sind — wie 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 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 Standard-OpenAPI-format-Werte zur Validierung:

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

Über die Validierung hinaus ändern einige Formate, wie ein Wert in der Codesphere-UI dargestellt wird:

FormatAuswirkung in der UI
uri, hostnameIm Bereich Details 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 reines Textfeld dargestellt. Eine Schaltfläche neben dem Feld generiert einen zufälligen Wert.
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

Generierte Passwörter​

Eigenschaften mit format: password im secretsSchema erhalten eine Schaltfläche, die das Eingabefeld mit einem zufälligen Wert füllt. Die Schaltfläche erscheint nur, wenn die Eigenschaft ein Schema ohne minLength oder maxLength angibt. Die OpenAPI-Spezifikation ist uneindeutig darüber, wie Längenbeschränkungen mit einem pattern zusammenwirken, daher werden solche Felder dem Benutzer überlassen. Ein pattern muss mit ^...$ verankert sein.

secretsSchema:
  type: object
  properties:
    admin_password:
      type: string
      format: password
      pattern: '^[A-Za-z0-9]{24}$'

Der Wert entspricht dem pattern. Ohne pattern werden 20 Zeichen aus [a-zA-Z0-9!@#$%^&*] verwendet. Die Werte werden im Browser des Benutzers mit einem kryptografisch sicheren Zufallszahlengenerator erzeugt und können vor dem Absenden noch bearbeitet werden.

vorsicht

Lookaheads wie (?!postgres$) werden bei der Generierung ignoriert. Die erlaubten Zeichen sollten mit Zeichenklassen und Quantoren beschrieben werden, damit das Pattern einen gültigen Wert erzeugen kann.

Konfiguration und Secrets an Landscapes übergeben​

Nur für Landscape-basierte Provider

Wenn ein Service aus einem Landscape-basierten Provider erstellt wird, wird die Eingabe des Benutzers an die Landscape weitergereicht: 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 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 festlegt, welche Lifecycle-Funktionen das Backend eines Providers unterstützt. Jeder Eintrag ist ein Boolean und wird in der Service-UI 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 Rechenressourcen freigegeben werden, während die Daten erhalten bleiben.
backupsDer Service unterstützt Backups in einem externen Speicher. Erfordert den backups-Schemablock. Siehe Managed Service Backups.
pointInTimeRecoveryDer Service kann auf einen beliebigen Zeitpunkt zurückgesetzt 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 bisher keine dieser Capabilities unterstützen.

Pläne und Ressourcenparameter​

Nur für REST-basierte Provider

Landscape-basierte Provider haben noch keine konfigurierbaren 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 Voreinstellungen, die konkrete Werte für diese Ressourcen festlegen — eine schnelle, unkomplizierte Auswahl für den Benutzer (Small, Medium, …).

Das Backend sieht diese ausführliche Definition nie. Beim Erstellen oder Aktualisieren eines Services löst Codesphere den ausgewählten Plan auf und sendet dem Backend nur die flachen Werte (siehe Ein eigenes REST-Backend erstellen):

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

Ressourcenparameter​

Jeder Eintrag unter resourceParameters hat zwei Felder:

FeldBeschreibung
pricedAsKennzeichnet den Parameter für Nutzungsverfolgung 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.

Markiere einen Parameter mit readOnly: true, um ihn festzusetzen: Benutzer können ihn nicht direkt ändern, sodass ein Plan die einzige Möglichkeit ist, einen anderen Wert festzulegen. Lässt man ihn konfigurierbar (Standard), können Benutzer den Wert des Plans innerhalb der minimum-/maximum-Grenzen des Schemas feinjustieren.

Da das Schema hier und nicht in jedem einzelnen Plan liegt, wird eine Grenze oder Einschränkung einmal geschrieben und gilt für jeden Plan — keine Wiederholung, nichts, was 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 Services.
nameKurze, in der UI angezeigte Bezeichnung (z. B. Small).
descriptionLesbare 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 — festgesetzt, 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. Lässt man plans weg (oder setzt es auf ein leeres Array), entfällt die Planauswahl vollständig — Codesphere sendet dem Backend dann keinen plan, und das Backend entscheidet, was bereitgestellt wird.

Provider-Versionen​

Nur für Landscape-basierte Provider

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

  • 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 lesbare Bezeichnung für die bereitgestellte Anwendungsversion.
  • description (optional): Markdown-formatierte Release-Notizen für den Benutzer.

Ein Provider, der aus einem statischen Build-Artefakt bereitgestellt wird, setzt backend.landscape.staticBuildArtifact anstelle von gitUrl, und jede Version legt einen artifactTag anstelle von gitRef und ciProfile fest. Siehe Statische Builds konsumieren.

Beim Erstellen eines Services wählen Benutzer die zu verwendende Version aus. Benutzer können die Version ihrer bereitgestellten Services ändern, was ein Upgrade oder Downgrade auslöst. Weitere Informationen unter Upgrade auf eine neue Version.

Veraltete Felder

backend.landscape.ciProfile und backend.landscape.gitRef wurden früher verwendet, um diese Werte einmalig 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 UI erstellen​

Statt die Provider-Datei von Hand zu schreiben, lässt sich eine Definition in der Codesphere-UI 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 sich als YAML oder JSON kopieren oder herunterladen lässt — zum Beispiel, um sie als provider.yml im eigenen Repository zu committen. Alles, was die Felder benötigen und erzeugen, entspricht genau dem, was weiter oben auf dieser Seite dokumentiert ist.

TabOptionWas passiert
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 vorhandene 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 des Formulars bereits ausgefüllt ist.

Definition erstellen​

Im Tab Create Provider Definition lässt sich ein neuer Provider erstellen — entweder abgeleitet von einer bereits vorhandenen Landscape oder aus einem leeren Formular.

Start from Landscape leitet einen ersten Entwurf der Definition aus einem vorhandenen Landscape-Repository ab, sodass das, was die ci.yml bereits deklariert, nicht manuell übertragen werden muss.

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). Standardmäßig ci.yml.

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

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

Alles, was auf diese Weise abgeleitet wird, 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 Start from Scratch oder einen Import verwenden.

Eine vorhandene Definition importieren​

Der Tab Import Provider Definition eignet sich, 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 Vorschaufenster 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. Standardmäßig provider.yml im Root-Verzeichnis des Repositorys.

Das Formular ausfüllen​

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

Provider Configuration-Formular mit Live-Vorschau der Provider-Definition

Mit Copy Snippet As und Download As lässt sich die angezeigte Definition als YAML oder JSON exportieren. Der Export ist verfügbar, sobald die Definition gültig ist — bei einem Landscape-basierten Provider bedeutet das mindestens eine Version sowie gültige Konfigurations-, Details- und Secrets-Abschnitte. Erst das Committen der exportierten Datei als provider.yml im eigenen Repository ermöglicht später die Git-basierten Veröffentlichungs-Workflows.

Aus dem Editor veröffentlichen​

Publish to Catalog öffnet den Veröffentlichungsdialog:

Publish Provider-Dialog über dem Formular und der Live-Definitionsvorschau

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 SecretNur bei REST-basierten Providern sichtbar. Optionales Bearer-Token, das Codesphere im Auth-Header jeder Anfrage an den eigenen Endpunkt sendet. Es wird nicht im Formular oder in der Vorschau angezeigt, sodass es nie in einer exportierten Provider-Datei landet.

Das Veröffentlichen führt denselben idempotenten Upsert wie PUT /managed-services/providers aus: Existiert noch kein Provider mit demselben name und derselben schemaVersion, wird er 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 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 für Veröffentlichung, Aktualisierung, Löschung, Scope und Singleton gelten gleichermaßen für Landscape-basierte und REST-basierte Provider.

info

Das Veröffentlichen von Providern erfordert Cluster-Admin-Berechtigungen. Resource-Group-Admins können beantragen, dass Provider auf bestimmte Resource Groups beschränkt werden.

Provider-Scopes​

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

Scope-TypBeschreibung
globalVerfügbar für alle Resource Groups der Codesphere-Instanz. Erfordert Cluster-Admin-Berechtigungen.
teamNur für angegebene Resource Groups 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 Resource Groups 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. 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 lässt sich sowohl zum Erstellen eines Providers als auch zum Ausrollen späterer Änderungen verwenden — es muss nicht verfolgt 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

Eigene Endpunkte für Erstellen (POST) und Aktualisieren (PATCH) existieren weiterhin für Teilaktualisierungen und explizitere Workflows, aber in den meisten Fällen ist der Upsert-Endpunkt die einfachste Wahl. Siehe Einen Provider direkt aktualisieren.

Versionen sind nur anhängbar

Bei Landscape-basierten Providern lassen sich neue Einträge zu versions hinzufügen, aber bestehende Versionseinträge können über 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 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 —, kann das optionale Argument filepath angegeben werden. Es wird relativ zum Root-Verzeichnis 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 seine Karte im Services Catalog bearbeiten oder per PATCH- oder PUT-Anfrage an /managed-services/providers/{name}/{schemaVersion} aktualisieren.

Breaking Changes am Schema vermeiden

Änderungen am Provider-Schema müssen abwärtskompatibel sein. Eine 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 einzelne Felder zu ändern, ohne die gesamte Definition erneut zu senden, 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 — sodass sich der endpoint aktualisieren lässt, während das gespeicherte secret unverändert bleibt, oder ein neues secret angegeben werden kann, 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 zurückgegeben. Das gilt für die PATCH-, PUT- und POST-Antworten bei REST-basierten Providern.

Einen Provider löschen​

warnung

Das Löschen eines Providers wirkt global. Der Provider wird aus dem Katalog für jede Resource Group entfernt, für die er verfügbar war. Aktive Services dieses Providers werden nicht mehr abgeglichen und können sich verschlechtern.

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