Zum Hauptinhalt springen
Version: Weekly Build

Managed Services

Jeder Dienst, der über den Bereich Managed Services angeboten wird, wird als individueller 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. Im 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:
  # ... weitere 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 auch 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 geändert werden sollen; alle anderen Werte werden 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, das nach RFC 7386 (JSON Merge Patch) tief zusammengeführt (deep-merged) wird: Du gibst nur die verschachtelten Felder an, die geändert werden sollen, und ein null-Wert entfernt einen Parameter vollständig.

Deep Merge gilt nur für diese statische Konfiguration

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

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

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

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

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

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

Die Pläne ersetzen — das Array plans wird als Ganzes ersetzt, daher musst du jeden Plan auflisten, 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 Resource Group nur einen nicht gelöschten Dienst 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
    # weitere Provider ...

REST-basierte Provider​

REST-basierte Provider werden auf dieselbe Weise wie landscape-basierte Provider zum Array managedServices hinzugefügt.

Es wird dringend empfohlen, dass dein REST-Backend Anfragen authentifiziert. Codesphere sendet mit jedem Aufruf an den backend.api.endpoint des Providers ein providerspezifisches gemeinsames Geheimnis (shared secret), sodass dein Backend nur den eingehenden Header mit dem konfigurierten Geheimnis vergleichen muss.

Das Geheimnis gehört niemals in config.yaml, da diese 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 einem Eintrag pro Provider:

# /home/<myuser>/secrets/prod.vault.yaml
secrets:
  # ... weitere 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 und darf daher 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; wenn beide angegeben sind, müssen sie übereinstimmen.

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 Geheimnis 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 im Rahmen seines Deployments übergeben; sie werden niemals in config.yaml, in eine Helm-Values-Datei auf der Festplatte oder in die Plattformdatenbank geschrieben. Das Rotieren eines Geheimnisses bedeutet daher, den Vault zu bearbeiten und den Installer erneut auszuführen.