Skip to main content
This guide helps you migrate from: to the combined Enterprise chart:

​
What Changed

  • chainloop-ee combines both distributions in one chart.
  • Some configuration is no longer required as it’s handled by the chart itself
  • Most Platform keys under frontend, backend, global, and nats remain in the same sections.
  • Most OSS keys under controlplane and cas remain in the same sections.
  • Database configuration is centralized in top-level chainloopDatabase and platformDatabase.
  • Development dependencies (vault, dex, postgresql) are now wired for the combined install path.

​
Top-Level Ingress Defaults

chainloop-ee introduces a top-level ingress block that works as a global fallback for component ingress settings.
  • Supported keys: ingress.enabled, ingress.hostname, ingress.ingressClassName, ingress.annotations, ingress.tls.
  • Precedence: component-specific values (frontend.ingress.*, backend.ingress.*, controlplane.ingress.*, cas.ingress.*, and *.ingressAPI.*) override top-level values when both are set.
  • Rendering behavior: ingress resources render when either the component ingress is enabled or top-level ingress.enabled is true.
  • Hostname derivation from top-level ingress.hostname:
    • frontend: app.<hostname>
    • backend: app-api.<hostname>
    • controlplane: cp.<hostname>
    • controlplane API: cp-api.<hostname>
    • cas: cas.<hostname>
    • cas API: cas-api.<hostname>
  • ingress.annotations and ingress.tls are reused as shared defaults (for example, cert-manager annotations and HTTPS defaults).

​
Migration Checklist

Make sure to get familiar with Removed Keys section before you start copying your values.
  1. Start from Enterprise edition chart values.yaml. Refer to README.md for more details about configuration options.
  2. Copy your Platform customizations (frontend, backend, nats) into the same sections.
  3. Copy your OSS customizations (controlplane, cas, secretsBackend, casJWT*) into the same sections.
  4. Apply the key remaps from the tables below.
  5. Run helm template / helm upgrade --dry-run and validate rendered secrets, DB endpoints, and ingress hosts.

​
Platform -> chainloop-ee Mapping

​
Mostly Unchanged Paths

These sections are largely drop-in:
  • global.*
  • frontend.*
  • backend.*
  • nats.*

​
Required Remaps

Old path (platform)New path (chainloop-ee)Notes
backend.auth.chainloopAuthPassphrasechainloopAuthPassphraseMoved to top-level. Required in non-development installs.
backend.externalChainloopDatabase.*chainloopDatabase.*Chainloop (control plane) DB connection is now top-level.
backend.externalDatabase.*platformDatabase.*Platform DB connection is now top-level.
frontend.service.portfrontend.service.ports.httpService schema follows chart conventions with ports.
backend.service.portbackend.service.ports.httpSame schema update as frontend.
backend.mcpService.portbackend.mcpService.ports.httpSame schema update for MCP service.
frontend.service.targetPortn/aNot exposed in values in the combined chart.
backend.service.targetPortn/aNot exposed in values in the combined chart.
backend.mcpService.targetPortn/aNot exposed in values in the combined chart.

​
Notable Default/Model Changes

  • frontend.service / backend.service / backend.mcpService now include additional service fields (clusterIP, nodePorts, externalTrafficPolicy, etc.).
  • frontend and backend include explicit pod/container security context defaults in chainloop-ee.
  • ingress.* at top-level acts as a shared default for all component ingresses.

​
OSS -> chainloop-ee Mapping

​
Mostly Unchanged Paths

These are generally reusable as-is:
  • controlplane.*
  • cas.*
  • secretsBackend.*
  • casJWTPrivateKey
  • casJWTPublicKey

​
Required Remaps

Old path (OSS)New path (chainloop-ee)Notes
controlplane.auth.passphrasechainloopAuthPassphraseMoved to top-level. Required in non-development installs.
controlplane.externalDatabase.*chainloopDatabase.*DB endpoint/user/database moved to top-level shared model.
controlplane.customCAs + cas.customCAscustomCAsUnified top-level CA injection list.

​
Removed Keys

Use this section as a quick reference for keys that existed in Platform or OSS values but are not present in chainloop-ee as the same path.
Removed keyReplacement / action
controlplane.externalDatabase.*Use chainloopDatabase.* (top-level).
controlplane.customCAsUse top-level customCAs.
controlplane.uiDashboardURLNo replacement in values (chart-managed).
controlplane.ingress.selfSignedNo direct replacement in chainloop-ee values.
controlplane.ingressAPI.selfSignedNo direct replacement in chainloop-ee values.
controlplane.auth.passphraseUse chainloopAuthPassphrase (top-level).
cas.customCAsUse top-level customCAs.
frontend.service.portUse frontend.service.ports.http.
frontend.service.targetPortNo replacement in values (chart-managed).
backend.auth.chainloopAuthPassphraseUse chainloopAuthPassphrase (top-level).
backend.externalDatabase.*Use platformDatabase.* (top-level).
backend.externalChainloopDatabase.*Use chainloopDatabase.* (top-level).
backend.service.portUse backend.service.ports.http.
backend.mcpService.portUse backend.mcpService.ports.http.
backend.service.targetPortNo replacement in values (chart-managed).
backend.mcpService.targetPortNo replacement in values (chart-managed).
backend.cas_apiNo direct replacement in chainloop-ee values. Backend CAS API wiring is chart-managed.
backend.cas_api.addrNo direct replacement in chainloop-ee values. Backend CAS API wiring is chart-managed.
backend.cas_api.insecureNo direct replacement in chainloop-ee values. Backend CAS API wiring is chart-managed.
backend.controlplane_apiNo direct replacement in chainloop-ee values. Backend control plane API wiring is chart-managed.
backend.controlplane_api.addrNo direct replacement in chainloop-ee values. Backend control plane API wiring is chart-managed.
backend.controlplane_api.insecureNo direct replacement in chainloop-ee values. Backend control plane API wiring is chart-managed.
backend.customCAsUse top-level customCAs.
backend.ingress.selfSignedNo direct replacement in chainloop-ee values.
backend.mcpNo replacement in values (chart-managed).
backend.mcp.oauthNo replacement in values (chart-managed).
backend.mcp.oauth.enabledNo replacement in values (chart-managed).
backend.mcp.oauth.authProviderNo replacement in values (chart-managed).
backend.mcp.oauth.authProvider.clientIdNo replacement in values (chart-managed).
backend.mcp.oauth.authProvider.clientSecretNo replacement in values (chart-managed).
backend.mcp.oauth.authProvider.issuerUrlNo replacement in values (chart-managed).
backend.mcpIngress.selfSignedNo replacement in values
global.compatibility.openshift.adaptSecurityContextNo direct replacement in chainloop-ee values.
cas.ingress.selfSignedNo direct replacement in chainloop-ee values.
cas.ingressAPI.selfSignedNo direct replacement in chainloop-ee values.

​
Vault in chainloop-ee

chainloop-ee vendors the Vault subchart (chainloop-ee/charts/vault/values.yaml) and only overrides a small subset at top-level vault.*:
  • vault.server.command
  • vault.server.args
  • vault.server.config
  • vault.server.extraVolumes
  • vault.server.extraVolumeMounts
  • vault.extraDeploy
If you previously customized standard Vault chart keys, keep using the same key paths under vault.* in chainloop-ee.

​
Minimal Migrated Values Example

chainloopAuthPassphrase: "replace-me"

chainloopDatabase:
  host: "chainloop-db"
  port: 5432
  user: "chainloop"
  database: "chainloop"
  password: "replace-me"

platformDatabase:
  host: "platform-db"
  port: 5432
  user: "backenduser"
  database: "backend"
  password: "replace-me"

secretsBackend:
  backend: "vault"
  secretPrefix: "chainloop"
  vault:
    address: https://vault.example.com
    token: "s.1234567890"
casJWTPrivateKey: |-
  -----BEGIN RSA PRIVATE KEY-----
  MIIEpAIBAAKCAQEA
  -----END RSA PRIVATE KEY-----
casJWTPublicKey: |-
  -----BEGIN PUBLIC KEY-----
  MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA
  -----END PUBLIC KEY-----
controlplane:
  auth:
    oidc:
      url: "replace-me"
      clientID: "replace-me"
      clientSecret: "replace-me"
  keylessSigning:
    enabled: true
    backends:
      - type: fileCA
        fileCA:
          cert: |-
            -----BEGIN CERTIFICATE-----
            MIIEpAIBAAKCAQEA
            -----END CERTIFICATE-----
          key: |-
            -----BEGIN ENCRYPTED RSA PRIVATE KEY-----
            MIIEowIBAAKCAQEA
            -----END ENCRYPTED RSA PRIVATE KEY-----
          keyPass: "replace-me"
        issuer: true
ingress:
  enabled: true
  hostname: "chainloop.example.com"
  ingressClassName: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
  tls: true

​
Validation Steps

  • Render manifests:
    • helm template chainloop-ee ./deployment/chainloop-ee -f <your-values>.yaml
  • Dry-run upgrade:
    • helm upgrade --install chainloop-ee ./deployment/chainloop-ee -f <your-values>.yaml --dry-run
  • Verify:
    • ingress hosts/TLS per component
    • secretsBackend configuration
    • machineIdentityIssuers and chainloopAuthPassphrase configuration
    • All custom configuration about autoOnboarding, restrictOrgCreation, keylessSigning, etc.
    • casJWTPrivateKey and casJWTPublicKey configuration

​
References