Zum Hauptinhalt springen
Version: Weekly Build

Managed Services

Jeder Dienst, der über den Bereich Managed Services angeboten wird, wird als einzelner Managed Service Provider im Array codesphere.managedServices in config.yaml konfiguriert. Die Konfiguration folgt einem bestimmten Schema.

Managed Service Provider können extern zu Codesphere sein (dabei wird eine externe API aufgerufen), es gibt aber auch integrierte Managed Services, bei denen der Provider innerhalb von Codesphere läuft. Mit dem aktuellen Release gibt es einen solchen Provider für PostgreSQL.

Codesphere wird mit einer Reihe vorkonfigurierter Provider ausgeliefert. Um einen davon zu aktivieren, gib Name und Version an:

# /etc/codesphere/config.yaml
codesphere:
  # ... andere Konfiguration
  managedServices:
    - name: postgres
      schemaVersion: v1
    - name: babelfish
      schemaVersion: v1
    - name: s3
      schemaVersion: v1
    - name: virtualK8sV1
      schemaVersion: v1

Wenn du einen dieser Provider verwendest, stelle sicher, dass das jeweilige Backend ebenfalls im Abschnitt managedServiceBackends aktiviert ist:

# /etc/codesphere/config.yaml
managedServicesBackends:
  postgres: # Dieses eine Backend bedient sowohl postgres als auch babelfish
    enabled: true
  barmanCloudPlugin: # Muss aktiviert sein, damit Datenbank-Backups funktionieren
    enabled: true
  s3:
    enabled: true
  k8sBackend:
    enabled: true

Eigenschaften überschreiben​

Du kannst Eigenschaften der vorkonfigurierten Provider überschreiben, anstatt sie von Grund auf neu zu definieren. Gib unter name und schemaVersion des Providers nur die Felder an, die du ändern möchtest; alles andere wird von den integrierten Standardwerten übernommen.

Die meisten Felder werden als Ganzes ersetzt — das Überschreiben von plans ersetzt beispielsweise das gesamte Array. Die eine Ausnahme ist resourceParameters, welches tief zusammengeführt (deep-merged) wird gemäß RFC 7386 (JSON Merge Patch): Du gibst nur die verschachtelten Felder an, die du ändern möchtest, und ein null-Wert entfernt einen Parameter vollständig.

Deep Merge gilt nur für diese statische Konfiguration

resourceParameters wird nur hier tief zusammengeführt, in der Codesphere-Konfiguration. Die öffentliche Provider-API (POST/PUT/PATCH) ersetzt resourceParameters als Ganzes, wie jedes andere Feld auch.

Das Schema von resourceParameters und plans findest du unter Plans and Resource Parameters.

Ein einzelnes Limit anpassen — Deep Merge betrifft nur dieses eine verschachtelte Feld; pricedAs, type und die anderen Parameter behalten ihre Standardwerte:

# /etc/codesphere/config.yaml
codesphere:
  # ... andere Konfiguration
  managedServices:
    - name: postgres
      schemaVersion: v1
      resourceParameters:
        storage:
          schema:
            minimum: 1024
    # ... andere Provider

Einen Parameter entfernen — ein null-Wert löscht ihn aus dem zusammengeführten Ergebnis:

    - name: postgres
      schemaVersion: v1
      resourceParameters:
        cpu: null

Pläne ersetzen — das Array plans wird als Ganzes ersetzt, also liste jeden Plan auf, den du behalten möchtest. Hier reduzieren wir die Standardwerte auf einen einzigen großen Plan:

    - name: postgres
      schemaVersion: v1
      plans:
        - id: 0
          name: Big
          description: Only one big plan
          parameters: { storage: 1000000, cpu: 50, memory: 8000 }

Hier findest du die vollständige Konfiguration des PostgreSQL Managed Service Providers:

Vollständiges Beispiel: der PostgreSQL Managed Service Provider
# /etc/codesphere/config.yaml
codesphere:
  managedServices:
    - name: postgres
      schemaVersion: v1
      backend:
        api:
          endpoint: "http://ms-backend-postgres.postgres-operator:3000/api/v1/postgres"
      author: Codesphere
      category: Database
      displayName: PostgreSQL
      # Auf true setzen, um pro Team nur einen nicht gelöschten Service für diese Provider-Version zuzulassen.
      # teamSingleton: true
      iconUrl: /ide/assets/managed-services/postgresql.svg
      configSchema:
        type: object
        properties:
          version:
            type: string
            description: Version of the Postgres DB. Includes pre-installed extensions compatible with this   version. Extension versions are managed and cannot be customized.
            enum:
              - '17.6'
              - '16.10'
            default: '17.6'
            readOnly: false
          userName:
            type: string
            default: app
            pattern: '^(?!postgres$)'
          databaseName:
            type: string
            default: app
        required: []
        additionalProperties: false
      detailsSchema:
        type: object
        properties:
          port:
            type: integer
          hostname:
            type: string
          dsn:
            type: string
          ready:
            type: boolean
        required:
          - port
          - hostname
          - dsn
          - ready
        additionalProperties: false
      secretsSchema:
        type: object
        properties:
          userPassword:
            type: string
            format: password
          superuserPassword:
            type: string
            format: password
        required:
          - userPassword
          - superuserPassword
        additionalProperties: false
      description: >-
        Open-source database system tailored for efficient data management and
        scalability. Deployed on Codesphere using the CNPG K8s Operator.
      # Einmal definiert; wird von jedem Plan unten gemeinsam genutzt.
      resourceParameters:
        storage:
          pricedAs: storage-mib
          schema:
            description: Storage (MiB)
            type: integer
            minimum: 512
            readOnly: false
            x-update-constraint: increase-only
        cpu:
          pricedAs: cpu-tenths
          schema:
            description: CPU Tenths
            type: number
            readOnly: true
        memory:
          pricedAs: ram-mib
          schema:
            description: Memory (MiB)
            type: integer
            readOnly: true
      plans:
        - id: 0
          name: Small
          description: 0.5 vCPU / 500 MB Memory
          parameters: { storage: 10240, cpu: 5, memory: 512 }
        - id: 1
          name: Medium
          description: 1 vCPU / 1 GB Memory
          parameters: { storage: 25600, cpu: 10, memory: 1024 }
        - id: 2
          name: Medium High-Mem
          description: 1 vCPU / 2 GB Memory
          parameters: { storage: 25600, cpu: 10, memory: 2048 }
        - id: 3
          name: Large
          description: 2 vCPU / 4 GB Memory
          parameters: { storage: 51200, cpu: 20, memory: 4096 }
        - id: 4
          name: Extra Large
          description: 4 vCPU / 8 GB Memory
          parameters: { storage: 153600, cpu: 40, memory: 8192 }

Eigene Provider hinzufügen​

Du kannst die Private-Cloud-Konfigurationsdatei auch verwenden, um selbst implementierte Provider statisch bereitzustellen.

Landscape-basierte Provider​

Landscape-basierte Provider können einfach zum Array managedServices hinzugefügt werden.

Vollständiges Beispiel: Statisch bereitgestellter, benutzerdefinierter Landscape-basierter Provider
# /etc/codesphere/config.yaml
codesphere:
  managedServices:
    - 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:
        1.0.0:
          appVersion: Mattermost v33
          ciProfile: prod
          gitRef: release-tags/1-0-0
          description: Long Term Support Release
    # andere Provider ...

REST-basierte Provider​

REST-basierte Provider werden auf die gleiche Weise wie Landscape-basierte Provider zum Array managedServices hinzugefügt.

Es wird dringend empfohlen, dass dein REST-Backend Anfragen authentifiziert. Codesphere sendet bei jedem Aufruf des backend.api.endpoint des Providers ein pro Provider geteiltes Secret, sodass dein Backend den eingehenden Header nur mit dem von dir konfigurierten Secret vergleichen muss.

Das Secret gehört niemals in config.yaml, da diese Datei im Klartext gespeichert wird. Lege es stattdessen im Eintrag managedServiceSecrets der SOPS-verschlüsselten Installer Vault Secrets ab. Der Wert ist ein JSON-Array mit jeweils einem Eintrag pro Provider:

# /home/<myuser>/secrets/prod.vault.yaml
secrets:
  # ... andere Secrets
  - name: managedServiceSecrets
    fields:
      password: |-
        [
            {
                "name": "my-provider",
                "schemaVersion": "v1",
                "api": {
                    "secret": "Bearer MY-API-KEY-123123"
                }
            }
        ]

Der Wert von password wird als JSON geparst, darf also keine YAML- oder JavaScript-Kommentare enthalten. Provider, die konfiguriert sind, aber keinen passenden Eintrag haben, werden ohne Authorization-Header aufgerufen.

Jeder Eintrag wird anhand von name und schemaVersion mit codesphere.managedServices abgeglichen; beide Werte müssen den dort verwendeten Werten entsprechen. Einträge können weiterhin den veralteten Schlüssel version anstelle von schemaVersion verwenden; sind beide angegeben, müssen sie identisch sein.

api.secret wird unverändert als Wert des Authorization-Headers gesendet. Codesphere fügt kein Schema hinzu. Damit dein Backend Authorization: Bearer MY-API-KEY-123123 empfängt, muss das Secret das Präfix Bearer enthalten, wie im obigen Beispiel. Der Wert darf nur druckbare ASCII-Zeichen (Codepunkte 32 bis 126) enthalten, da er als HTTP-Header-Wert verwendet wird.

Die Secrets werden beim Ausführen des Installers gelesen und dem Marketplace als Teil seines Deployments übergeben; sie werden niemals in config.yaml, in eine Helm-Values-Datei auf der Festplatte oder in die Plattform-Datenbank geschrieben. Das Rotieren eines Secrets bedeutet daher, den Vault zu bearbeiten und den Installer erneut auszuführen.