Skip to main content
Version: Weekly Build

Managed Services

Every service offered through the Managed Services section is configured as an individual Managed Service Provider in the codesphere.managedServices array in config.yaml. The configuration follows a specific schema.

Managed Service Providers can be external to Codesphere (an external API is called), but there are also built-in Managed Services, where the provider runs within Codesphere. With the current release there is one such provider, for PostgreSQL.

Codesphere comes with a set of preconfigured providers. To enable any of them, specify name and version:

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

If you use any of those providers, ensure the respective backend is also enabled in the managedServiceBackends section:

# /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

Override properties​

You can override properties of the preconfigured providers instead of redefining them from scratch. Specify only the fields you want to change under the provider's name and schemaVersion; everything else is inherited from the built-in defaults.

Most fields are replaced as a whole — overriding plans, for example, replaces the entire array. The one exception is resourceParameters, which is deep-merged following RFC 7386 (JSON Merge Patch): you supply only the nested fields you want to change, and a null value removes a parameter entirely.

Deep merge applies to this static configuration only

resourceParameters is deep-merged only here, in the Codesphere configuration. The public provider API (POST/PUT/PATCH) replaces resourceParameters as a whole, like every other field.

For the schema of resourceParameters and plans, see Plans and Resource Parameters.

Bump a single limit — deep merge touches just this one nested field; pricedAs, type, and the other parameters keep their default values:

# /etc/codesphere/config.yaml
codesphere:
  # ... other configuration
  managedServices:
    - name: postgres
      schemaVersion: v1
      resourceParameters:
        storage:
          schema:
            minimum: 1024
    # ... other providers

Remove a parameter — a null value deletes it from the merged result:

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

Replace the plans — the plans array is replaced as a whole, so list every plan you want to keep. Here we collapse the defaults down to a single big plan:

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

Here you can find the full configuration of the PostgreSQL Managed Service Provider:

Full example: the 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 }

Adding your own Providers​

You can also use the private cloud configuration file to statically provision providers that you implemented yourself.

Landscape-Based Providers​

Landscape-Based Providers can simply be added to the managedServices array.

Full example: Statically provisioned custom Landscape-Based 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-Based Providers​

Rest-Based Providers are added to the managedServices array in the same way as Landscape-Based Providers.

It is highly recommended that your REST-Backend authenticates requests. Codesphere sends a per-provider shared secret with every call to the provider's backend.api.endpoint, so your backend only has to compare the incoming header against the secret you configured.

The secret never belongs in config.yaml, which is stored in plain text. Instead, put it in the managedServiceSecrets entry of the SOPS-encrypted installer vault secrets. Its value is a JSON array, one entry per 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"
                }
            }
        ]

The password value is parsed as JSON, so it must not contain YAML or JavaScript comments. Providers that are configured but have no matching entry are called without an Authorization header.

Each entry is matched against codesphere.managedServices by name and schemaVersion, both of which must equal the values used there. Entries may still use the deprecated version key instead of schemaVersion; if both are given they must be equal.

api.secret is sent verbatim as the value of the Authorization header. Codesphere does not add a scheme. To have your backend receive Authorization: Bearer MY-API-KEY-123123, the secret must include the Bearer prefix, as in the example above. The value may only contain printable ASCII characters (code points 32 to 126), since it is used as an HTTP header value.

The secrets are read when the installer runs and are handed to the Marketplace as part of its deployment; they are never written to config.yaml, to a Helm values file on disk, or to the platform database. Rotating a secret therefore means editing the vault and re-running the installer.