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. 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:
  # ... other configuration
  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 entsprechende Backend auch im Abschnitt managedServiceBackends aktiviert ist:

# /etc/codesphere/config.yaml
managedServicesBackends:
  postgres: # This single backend serves both postgres and babelfish
    enabled: true
  barmanCloudPlugin: # Needs to be enabled for database backups to work
    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 zum Beispiel ersetzt das gesamte Array. Die einzige Ausnahme ist resourceParameters, das nach RFC 7386 (JSON Merge Patch) tief zusammengeführt (deep-merged) wird: 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, 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 und 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:
  # ... other configuration
  managedServices:
    - name: postgres
      schemaVersion: v1
      resourceParameters:
        storage:
          schema:
            minimum: 1024
    # ... other providers

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, also liste jeden Plan auf, den du behalten möchtest. Hier fassen wir die Standardwerte zu einem einzigen großen Plan zusammen:

    - 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
      # Set to true to allow only one non-deleted service per team for this provider version.
      # 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.
      # Defined once; shared by every plan below.
      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
    # other providers ...

REST-basierte Provider

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

Es wird dringend empfohlen, dass dein REST-Backend Anfragen authentifiziert. Codesphere sendet bei jedem Aufruf des backend.api.endpoint des Providers ein providerspezifisches gemeinsames Geheimnis (Shared Secret) mit, sodass dein Backend nur den eingehenden Header mit dem von dir 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:
  # ... other 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, wobei beide Werte den dort verwendeten Werten entsprechen müssen. Einträge können weiterhin den veralteten Schlüssel version anstelle von schemaVersion verwenden; sind beide angegeben, 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 als Teil seiner Deployment übergeben; sie werden niemals in config.yaml, in eine Helm-Values-Datei auf der Festplatte oder in die Plattformdatenbank geschrieben. Ein Geheimnis zu rotieren bedeutet daher, den Vault zu bearbeiten und den Installer erneut auszuführen.