Funktionsweise

Der Operator ist ein einzelnes Go-Binary, das einen controller-runtime-Manager ausführt. Er beobachtet seine Custom Resources und konvergiert den Cluster passend dazu. Diese Seite erklärt die Architektur; Kernkonzepte definiert das Vokabular, und Reconciler-Interna behandeln die Lebenszyklus-Mechanik.

Zwei Schichten: Capability-Operatoren und Workloads

Die Plattform ist aus zwei Arten von Dingen aufgebaut, und der Operator hält sie sauber getrennt:

• Capability-Operatoren (die „Engines“) — LiteLLM, Langfuse, External Secrets, Sealed Secrets, CloudNativePG, cert-manager, der Redis-Operator, der ClickHouse-Operator und die MongoDB-Controller. Diese werden installiert, indem ihre offiziellen Helm-Charts, die im Binary gebündelt sind, via Helm v4 Go SDK angesteuert werden.
• Workloads (die „Instanzen“) — das eigentliche Gateway, die UI, der Observability-Stack, die Datenspeicher und die Secret-Stores. Diese werden als die Upstream-Custom-Resources ausgedrückt, die jene Operatoren reconcilen (LiteLLMInstance, CNPG Cluster, ESO ExternalSecret, …), oder als ein Workload-Helm-Release (LibreChat).

Ihre CRDs beschreiben Workloads; der Operator installiert die Capability-Operatoren, die diese Workloads benötigen, und emittiert dann die Upstream-CRs.

Die API-Oberfläche

Alles liegt in der API-Gruppe 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)

Alle Workload- und Datenspeicher-Ressourcen sind namespaced und Multi-Instance: Viele Gateway / Observability / ChatUI können koexistieren, und mehrere können sich ein einzelnes Observability oder einen einzelnen PostgresClusterteilen — jeder Verbraucher erhält seine eigene Datenbank innerhalb des geteilten Clusters, möglicherweise namespace-übergreifend.

Bündelungsmodell — eigenständige Releases, keine Subcharts

Der Operator verwendet keine Helm-Subchart-Abhängigkeiten. Jedes Upstream-Chart wird als eigenständiges .tgz gevendort (via go:embed eingebettet) und als sein eigenes Helm-Release mit festem Namen und festem System-Namespace installiert. Capability-Operatoren sind cluster-scoped Singletons, daher wird jeder einmal installiert und von Workloads in jedem beliebigen Namespace referenziert.

Warum eigenständig besser ist als Subcharts: Ein Singleton-Operator (z. B. CloudNativePG), der als Subchart sowohl von Gateway als auch von Observability installiert wird, würde zwei Releases erzeugen, die um dieselben CRDs streiten — was Helm ablehnt. Als eigenständige Releases referenzieren beide Workloads dieselbe Installation.

Installationen sind bedarfsgesteuert — ein Chart wird nur installiert, wenn eine Ressource es tatsächlich benötigt. Wenn jeder Datenspeicher external oder adopt ist, werden nur die Operatoren installiert, die diese Workloads wirklich benötigen. Siehe Gebündelte Charts.

Das Reconcile-Modell

Jeder Controller modelliert seine Arbeit als geordnete Phasen, persistiert in status.conditions. Ein Reconcile schreitet so weit voran, wie es die Readiness erlaubt, und reiht sich dann erneut ein:

1. Abhängigkeiten auflösen & gaten — ist die referenzierte SecretsManagement bereit? Sind die referenzierten Datastore-/Gateway-/Langfuse-Ressourcen bereit?
2. Capability-Operatoren sicherstellen — installiere (provenance-bewusst) nur die Operatoren, die diese Ressource benötigt, und warte dann, bis ihre CRDs Established sind.
3. Besessene Ressourcen anwenden — emittiere die Upstream-CRs oder installiere/aktualisiere das Workload-Helm-Release. Jedes Apply ist idempotent (create-or-update).
4. Readiness pollen — setze Conditions und reihe erneut ein, bis Ready.

Zwei Regeln machen dies robust:

• Erneut einreihen, nicht fehlern, während des Wartens. „Noch nicht bereit“ liefert ein Requeue, keinen Fehler. Fehler sind echten Fehlschlägen vorbehalten und erhalten exponentielles Backoff.
• Alles ist idempotent. Jedes Apply kann sicher bei jedem Requeue ausgeführt werden.

Es gibt keine Argo-artigen globalen Sync-Wellen — Readiness-Gates ersetzen sie. Nach dem Installieren eines Charts, das CRDs ausliefert, wartet der Operator, bis die CRDs Established sind, und aktualisiert seinen REST-Mapper, bevor er Ressourcen der neuen Arten erstellt.

Provenance, zwei Ebenen tief

Der Operator ist sorgfältig damit, was er besitzt. Dies zeigt sich auf zwei Ebenen:

• Operator-Installation — er installiert sein eigenständiges Release nur, wenn der Operator fehlt. Falls Sie ihn bereits installiert haben, adoptiert der Operator ihn (koexistiert, verwaltet niemals seinen Lebenszyklus). Installationen sind ref-gezählt über Ressourcen hinweg, und der Operator deinstalliert nur Releases, die er besitzt, wenn nichts sie benötigt.
• Datenspeicher-Instanz — jede Datenspeicher-Ressource hat einen mode: managed (der Operator erstellt, besitzt und garbage-collected sie), adopt (referenziere einen bestehenden In-Cluster-Datenspeicher; lösche ihn niemals) oder external (ein vom Benutzer gehosteter Datenspeicher; verkabele nur ein Verbindungs-Secret).

Lesen Sie die Details auf der Seite Provenance & Lebenszyklus.

Querverweise und Auto-Wiring

Ressourcen referenzieren einander über {name, namespace}. Für jede Referenz tut der Controller Folgendes:

1. Auflösen und gaten — reiht erneut ein, bis die referenzierte Ressource bereit ist.
2. Auto-Wiring, falls lizenziert — mit der Funktion auto-wiring stellt er die Anmeldedaten bereit und injiziert sie, sodass Sie keine Secrets von Hand konfigurieren (z. B. das Prägen eines virtuellen LiteLLM-Schlüssels für eine ChatUI oder das Verkabeln des Langfuse-Callbacks eines Gateway).
3. Fallback auf manuell — ohne die Funktion verwendet er die expliziten Felder, die Sie angeben, und emittiert eine Condition, die genau benennt, was zu setzen ist.

Siehe Komponentenübergreifendes Auto-Wiring.

Prozessmodell

• Ein einzelnes Binary, controller-runtime-Manager, Leader Election an.
• MaxConcurrentReconciles = 1 pro Controller (die Helm-action.Configuration ist nicht concurrency-sicher).
• Beobachtet standardmäßig alle Namespaces, einschränkbar via --watch-namespaces.
• Eine breite ClusterRole — der Operator installiert CRDs, RBAC, Webhooks und Workloads namespace-übergreifend.
• Ausgeliefert als Image plus drei Installationsmethoden: kustomize, ein OLM-Bundle und ein Helm-Chart.

Sicherheitslage

Alle vom Menschen bereitgestellten Anmeldedaten fließen aus External Secrets (standardmäßig Azure Key Vault via Workload Identity, aber jeder ESO-Provider wird unterstützt) oder Sealed Secrets — niemals inline in einer CR, einem Chart-Wert oder einem Template. Vom Operator erzeugte Anmeldedaten (virtuelle Schlüssel, Callback-Schlüssel, Datenspeicher-Passwörter) werden als einfache operatoreigene Secrets mit Owner-References für die Garbage Collection gespeichert. Siehe Secrets-Verwaltung.