Core Concepts

This page defines the vocabulary used throughout the documentation. A short Glossary collects the one-line definitions.

Capability operator vs. workload

• A capability operator is an upstream operator the platform depends on (CloudNativePG, External Secrets, LiteLLM, …). The operator installs these by driving their official Helm charts.
• A workload is the actual running thing you care about — a LiteLLM instance, a Langfuse deployment, a Postgres cluster. Workloads are expressed as the upstream CRs that capability operators reconcile, or as a workload Helm release.

Your custom resources describe workloads; the operator installs the capability operators those workloads need.

Custom resource categories

Category	Resources	Role
License	License	Cluster-scoped entitlements
Secrets	SecretsManagement	The credential backend (required)
Datastores	PostgresCluster, ClickHouseCluster, RedisInstance, MongoCluster, MeilisearchInstance	Shared storage and search
Workloads	Gateway, Observability, ChatUI	The user-facing AI platform
Platform	ManagementPlane	The admin console (deployed by default)
Composition	Stack, User, Identity, Organization, Team	Bundling and identity (licensed)

Datastore modes: managed, adopt, external

Every datastore resource carries a mode that decides how much the operator owns:

• managed — the operator installs the capability operator (provenance-aware) and creates, owns, and garbage-collects the datastore custom resource.
• adopt — the operator references a datastore you already created in-cluster (for example an existing CNPG Cluster). It can provision a logical database inside it, but never deletes or reconfigures the cluster itself.
• external — the datastore lives outside the cluster (e.g. Azure Database for PostgreSQL). The operator installs no capability operator and creates no datastore CR; it only wires a connection secret into the consuming workload.

A capability operator chart is installed only if at least one resource selects its managed mode. If everything is external or adopt, that operator is never installed.

Adopting a datastore from another namespace

Every adopt reference takes an optional namespace, so the datastore you adopt may live anywhere in the cluster — a central data namespace shared by several application namespaces, for example. Two rules make that work:

• The connection host is built from the referenced namespace. status.host points at the service next to the adopted datastore, not at your CR.
• Credentials are always published in the datastore CR's own namespace. Consumers (Gateway, Observability, ChatUI) read status.credentialsSecret in the namespace of the datastore resource they reference, so when the real Secret lives beside the adopted instance the operator mirrors it into an owned Secret named <name>-adopted-credentials here. Point the adopt block's credentials reference at wherever the Secret really is; the operator does the rest.

CNPG databases are created next to the adopted cluster

For PostgresCluster, the CNPG Database resources that back databases[] are created in the adopted cluster's namespace — CNPG's Database.spec.cluster is resolved in the Database's own namespace, so they could not work anywhere else. They carry an owned-by label and are removed when you delete the adopting PostgresCluster; the adopted cluster itself is never touched.

If you run the operator with --watch-namespaces, include every namespace you adopt from — the operator has to read the referenced datastore and its Secret.

Two-level provenance

"Provenance" is the rule that the operator never re-installs what you installed, and never uninstalls what it does not own. It applies at two levels:

• Operator install provenance — when ensuring a capability operator, the operator detects whether a matching release already exists. If it carries the operator's ownership label it is owned; otherwise it is adopted. Installs are ref-counted; an owned release is uninstalled only when no resource needs it.
• Datastore instance provenance — the same principle one level down, expressed through the mode field above.

type × mode

Datastores have both a type (the implementation/backend) and a mode (the provenance). For example a PostgresCluster has type: cnpg (CloudNativePG) and a mode of managed. The type switch is how additional backends are added — zalando and cockroachdb are scaffolded behind the same interface and report a clear "not yet implemented" status until finished.

Auto-wiring

Auto-wiring is the licensed capability where the operator provisions and injects credentials across components, so you never configure cross-component secrets by hand. Examples:

• ChatUI.gatewayRef → mint a LiteLLM virtual key for the UI and inject the in-cluster gateway URL + key.
• Gateway.observabilityRef → wire LiteLLM's Langfuse callback so traces export automatically.
• Gateway.database.mode: postgresCluster → provision the litellm database and inject its credentials.

Without the auto-wiring feature, every reference has a manual fallback — you supply the credentials explicitly and the platform still runs. See Cross-Component Auto-Wiring.

Secrets backends

SecretsManagement selects one of two backends:

• ESO (External Secrets Operator) — pulls from an external secret store (Azure Key Vault, HashiCorp Vault, AWS, GCP, …) into namespaced Kubernetes Secrets.
• Sealed Secrets — encrypted-at-rest manifests decrypted in-cluster.

A third class of secret is operator-generated — virtual keys, callback keys, and datastore passwords the operator mints itself, stored as owned Secrets. See Secrets Management.

References

All cross-references use a small set of shapes:

• ObjectRef — { name, namespace? }; namespace defaults to the resource's own. Cross-namespace references are allowed for datastores, gateways, and Langfuse.
• LocalRef — { name }; same-namespace only (used by secretsRef).
• SecretKeyRef — { name, key?, namespace? }; Secret references stay in-namespace.

A workload resource can carry a secretsRef pointing at a same-namespace SecretsManagement that produces its Secrets; without one it reads Secrets you manage yourself (see secretsRef).

Status and conditions

Every resource exposes status.conditions with at least a Ready condition plus per-phase conditions (SecretsReady, OperatorsReady, DatastoreReady, WorkloadReady, …), each carrying a reason and message, and an observedGeneration. The operator records Kubernetes Events for adoptions, license-gated skips, instance-cap refusals, expiry downgrades, and garbage collection — so a stalled install is self-explaining. See Troubleshooting.

License entitlements

The License carries explicit entitlements — an enumerated features list and quantitative limits (per-type instance caps). There is no wildcard. When there is no valid license, the operator applies built-in Community defaults (paid features off, caps at the free level) and the base platform keeps running. See Editions & Licensing.