How It Works

The operator is a single Go binary running a controller-runtime manager. It watches its custom resources and converges the cluster to match them. This page explains the architecture; Core Concepts defines the vocabulary, and Reconciler internals cover the lifecycle mechanics.

Two layers: capability operators and workloads

The platform is built from two kinds of thing, and the operator keeps them cleanly separated:

• Capability operators (the "engines") — LiteLLM, Langfuse, External Secrets, Sealed Secrets, CloudNativePG, cert-manager, the Redis operator, the ClickHouse operator, and the MongoDB controllers. These are installed by driving their official Helm charts, bundled in the binary, via the Helm v4 Go SDK.
• Workloads (the "instances") — the actual gateway, UI, observability stack, datastores, and secret stores. These are expressed as the upstream custom resources those operators reconcile (LiteLLMInstance, CNPG Cluster, ESO ExternalSecret, …), or as a workload Helm release (LibreChat).

Your CRDs describe workloads; the operator installs whatever capability operators those workloads require, then emits the upstream CRs.

The API surface

Everything lives in the API group core.navique.com/v1alpha1.

Cluster-scoped
└── License ............ singleton; the signed offline license

Namespaced
├── SecretsManagement .. required; ESO or Sealed Secrets credential backend
├── PostgresCluster .... shared PostgreSQL, multi-database
├── ClickHouseCluster .. ClickHouse
├── RedisInstance ...... Redis
├── MongoCluster ....... shared MongoDB, multi-database
├── MeilisearchInstance  Meilisearch search backend
├── Gateway ............ LiteLLM gateway + models / teams / orgs
├── Langfuse ........... Langfuse v3 observability
├── ChatUI ............. LibreChat UI, wired to a Gateway
├── ManagementPlane .... configures the admin console (deployed by default)
├── Stack .............. optional umbrella; a curated, auto-wired bundle (licensed)
└── Organization/Team/User  managed identities (licensed)

All workload and datastore resources are namespaced and multi-instance: many Gateway / Observability / ChatUI can coexist, and several can share a single Observability or a single PostgresCluster — each consumer gets its own database inside the shared cluster, possibly across namespaces.

Bundling model — standalone releases, not subcharts

The operator does not use Helm subchart dependencies. Each upstream chart is vendored as a standalone .tgz (embedded via go:embed) and installed as its own Helm release with a fixed name and a fixed system namespace. Capability operators are cluster-scoped singletons, so each is installed once and referenced by workloads in any namespace.

Why standalone beats subcharts: a singleton operator (e.g. CloudNativePG) installed as a subchart of both Gateway and Observability would produce two releases fighting over the same CRDs, which Helm rejects. As standalone releases, both workloads reference the single install.

Installs are lazy — a chart is installed only when a resource actually needs it. If every datastore is external or adopt, only the operators those workloads truly require get installed. See Bundled Charts.

The reconcile model

Each controller models its work as ordered phases persisted in status.conditions. A reconcile advances as far as readiness allows, then requeues:

1. Resolve & gate dependencies — is the referenced SecretsManagement ready? Are the referenced datastore/gateway/langfuse resources ready?
2. Ensure capability operators — install (provenance-aware) only the operators this resource needs, then wait for their CRDs to be Established.
3. Apply owned resources — emit the upstream CRs or install/upgrade the workload Helm release. Every apply is idempotent (create-or-update).
4. Poll readiness — set conditions and requeue until Ready.

Two rules make this robust:

• Requeue, don't error, while waiting. "Not ready yet" returns a requeue, not an error. Errors are reserved for genuine failures and get exponential backoff.
• Everything is idempotent. Every apply is safe to run on every requeue.

There are no Argo-style global sync waves — readiness gates replace them. After installing a chart that ships CRDs, the operator waits for the CRDs to be Established and refreshes its REST mapper before creating resources of the new kinds.

Provenance, two levels deep

The operator is careful about what it owns. This shows up at two levels:

• Operator install — it installs its standalone release only if the operator is absent. If you already installed it, the operator adopts it (coexists, never manages its lifecycle). Installs are ref-counted across resources, and the operator uninstalls only releases it owns when nothing needs them.
• Datastore instance — every datastore resource has a mode: managed (the operator creates, owns, and garbage-collects it), adopt (reference an existing in-cluster datastore; never delete it), or external (a user-hosted datastore; only wire a connection secret).

Read the details on the Provenance & Lifecycle page.

Cross-references and auto-wiring

Resources reference each other by {name, namespace}. For each reference the controller:

1. Resolves and gates — requeues until the referenced resource is ready.
2. Auto-wires if licensed — with the auto-wiring feature, it provisions and injects the credentials so you configure no secrets by hand (e.g. minting a LiteLLM virtual key for a ChatUI, or wiring a Gateway's Langfuse callback).
3. Falls back to manual — without the feature, it uses the explicit fields you supply and emits a condition naming exactly what to set.

See Cross-Component Auto-Wiring.

Process model

• A single binary, controller-runtime manager, leader election on.
• MaxConcurrentReconciles = 1 per controller (the Helm action.Configuration is not concurrency-safe).
• Watches all namespaces by default, restrictable via --watch-namespaces.
• A broad ClusterRole — the operator installs CRDs, RBAC, webhooks, and workloads across namespaces.
• Shipped as an image plus three install methods: kustomize, an OLM bundle, and a Helm chart.

Security posture

All human-supplied credentials flow from External Secrets (Azure Key Vault via Workload Identity by default, but any ESO provider is supported) or Sealed Secrets — never inline in a CR, a chart value, or a template. Operator-generated credentials (virtual keys, callback keys, datastore passwords) are stored as plain owned Secrets with owner references for garbage collection. See Secrets Management.