Component anatomy

Each deployable component is a directory under one of four parent applications: common, coreai, inference, or proai.

Directory structure

src/manifests/source/<parent>/<component>/
├── variables.toml
├── values.yaml.j2
├── resources/
│   └── *.yaml.j2
└── secrets/
    └── *.yaml.j2

Helm components require variables.toml and values.yaml.j2. Kustomize components require kustomization.yaml; raw-YAML components render resources directly. The CLI validates the required files for the declared format.

Required component metadata

The [component] table declares the component name, namespace, version, format, chart coordinates, release name, URL prefix, parent application, sync wave, and Argo CD options. enabled = false removes the component from generated output.

Names must be unique across all parents. The parent_app value must be one of common, coreai, inference, or proai, and sync_wave must be an integer from 0 through 99.

Template variables

Additional TOML tables become flattened, component-prefixed Jinja variables. For example:

[database]
host = "postgresql-rw.cnpg.svc"
port = 5432

For a component named portal, templates consume portal_database_host and portal_database_port. Global settings use their table prefix, such as common_base_domain and object_storage_url.

The Jinja environment uses StrictUndefined, so missing variables fail the render instead of silently producing incomplete manifests. It also provides a b64encode filter and renders Python booleans as lowercase YAML values.

Secrets

Secret values use metadata nodes such as:

password = { kind = "password", format = "plain", generate_once = true }

Put Kubernetes Secret resources under rendered secret templates. The CLI detects rendered kind: Secret documents and seals them with kubeseal before writing output. A plain .yaml or .yml file is copied verbatim and must never contain secret material.

SSO enrollment

Components with an [sso] section can render Keycloak client configuration and PreSync/PostDelete enrollment jobs. The setup job reconciles the client, roles, groups, and service-account mappings before the workload syncs. Disabling SSO omits those resources for that component.

Generated output

For each enabled component, the CLI writes rendered values and resources plus <component>-argoapp.yaml. It then generates a parent app-of-apps file for every non-empty parent directory. Argo CD reads the Helm chart from the configured OCI registry and the rendered site values from Git.

Add or change a component

1. choose the correct parent and a globally unique name;
2. add variables.toml and the files required by its format;
3. keep site-specific values configurable rather than hard-coded;
4. place secret resources only in rendered templates;
5. add controller drift rules if the component mutates replicas or CRDs;
6. run bsqai validate and a targeted bsqai apply <component>;
7. inspect the generated application and values before a full render.