Configuration Model

This page explains how deployment configuration is structured in the coreai-platform Terraform layer.

The current reference implementation is under deployments/terraform/bsq-ai and separates platform inputs into a few clear groups: common platform defaults, Git and delivery settings, component scope, secrets, and environment-specific extensions.

Configuration Layers

1. Common platform defaults

common_config defines the shared foundation used across Runtime, CoreAI, and ProAI.

Typical inputs include:

• base domain
• ingress class
• storage classes
• image pull secret
• registry locations
• realm name
• whether CoreAI and ProAI components are enabled

These are the first settings to validate in any deployment because they affect routing, storage, image pulls, and platform-wide naming.

2. Git and delivery source

git_config tells Argo CD where to read manifests from:

• Git repository URL
• branch
• path inside the repository

If these values are wrong, the platform can bootstrap Argo CD successfully but fail to synchronize the actual application layer.

3. Component scope and defaults

Component enablement and many default versions are controlled through:

• components_config
• modular CoreAI component overrides
• modular ProAI component overrides

This is where deployment scope is shaped. It controls which services are enabled, which namespaces are used, and how the default platform footprint is assembled.

4. Secrets and service credentials

Secrets are provided through the .auto.tfvars layer and cover areas such as:

• Argo CD access
• registry authentication
• Keycloak client secrets for SSO-enrolled components
• database credentials
• MinIO service accounts
• Grafana and MLflow credentials
• model source credentials such as Hugging Face

Some values are mandatory for bootstrap, while others can be generated automatically when left empty.

Keycloak client secrets deserve specific attention. Each SSO-enabled component has a keycloak_client_secret variable. When left empty (the default), a random secret is generated automatically. When provided, the explicit value is used. Either way, the secret becomes part of the OIDC client registration that the platform pushes to Keycloak during deployment.

5. Provider-specific or circumstantial settings

Some inputs only matter in specific environments.

Current examples include:

• Azure DNS configuration for external-dns
• Azure DNS-01 inputs for cert-manager
• proxy settings
• environment-specific registry replication paths
• optional TLS material through custom_tls

These are circumstantial inputs. They should only be filled when the target environment actually requires them.

What Is Usually Mandatory

In practice, every successful deployment needs clear values for:

• common_config.base_domain
• common_config.rwo_storageclass
• common_config.rwx_storageclass
• registry location and image pull credentials
• git_config.git_repo_url
• git_config.git_branch
• git_config.git_path
• certificate strategy
• DNS ownership model

Even when defaults exist in Terraform, several of those defaults are placeholders or environment-specific and still need to be reviewed before deployment.

What Is Often Optional

These settings are commonly optional or can be left at defaults initially:

• database names and owners for several services
• some service passwords that can be generated automatically
• component version overrides
• advanced sizing values
• advanced affinity or scheduling settings

They still matter for production hardening, but they are not always required to begin a controlled rollout.

What Is Environment-Specific

These settings should be treated as conditional:

• Azure DNS and certificate variables
• proxy configuration
• registry replication details
• external identity federation details
• cloud-specific storage class names

SSO Scope

Most platform components are automatically enrolled into Keycloak for single sign-on. This is controlled per component through the sso_enable flag, which defaults to true.

How it works

When sso_enable is true and the component is enabled, the Terraform layer generates:

• an SSO configuration secret containing the OIDC client definition, groups, and roles
• a PreSync setup job that registers the component with Keycloak before deployment
• a PostDelete cleanup job that removes the Keycloak client when the component is deleted

When sso_enable is set to false, none of these resources are created. The component deploys without Keycloak integration.

Disabling SSO for a component

To disable SSO for any component, set its sso_enable flag to false in the relevant variable block. For example:

components_config = {
  langfuse = {
    # ... other settings ...
    sso_enable = false
  }
}

Or for a modular CoreAI/ProAI component:

coreai_portal_config = {
  sso_enable = false
}

Components with SSO support

The following components have an sso_enable flag:

Keycloak enroll credentials

The setup and cleanup jobs authenticate against Keycloak using a dedicated enroll user. The password for this user is controlled by keycloak_enroll_password. When left empty, a random password is generated.

The enroll credentials are distributed as a Kubernetes secret (keycloak-enroll-credentials) to every namespace that has at least one SSO-enabled component.

For a deeper explanation of how the enrollment mechanism works, see the Keycloak component page.

Safe Review Checklist

Before applying a deployment, validate these questions:

1. Does the target environment have the required storage classes?
2. Does the base domain match a DNS zone that the platform can manage?
3. Is the registry reachable from the cluster?
4. Is the Git path correct for the manifests Argo CD should reconcile?
5. Is the certificate model clear: provided TLS material or DNS-driven issuance?
6. Are only the needed platform tiers enabled?

Minimal Input Shape

common_config = {
  base_domain                  = "<platform-domain>"
  ingressclassname             = "<ingress-class>"
  rwo_storageclass             = "<rwo-storage-class>"
  rwx_storageclass             = "<rwx-storage-class>"
  imagepullsecret              = "<pull-secret-name>"
  registry                     = "<registry-host>"
  registry_platform_repository = "coreai/platform"
  registry_backend_repository  = "coreai/backend"
  registry_portal_repository   = "coreai/portal"
  registry_helm_repository     = "coreai/helm"
  realm_name                   = "dataplatform"
  coreai_components            = true
  proai_components             = true
}

git_config = {
  git_repo_url = "<git-repository-url>"
  git_branch   = "<git-branch>"
  git_path     = "<manifest-path>"
}

custom_tls = {
  enabled = false
  ca_crt  = ""
  tls_crt = ""
  tls_key = ""
}

Use that structure as the baseline, then add only the environment-specific and service-specific inputs required by the chosen deployment model.