Kernkonzepte

Diese Seite definiert das in der gesamten Dokumentation verwendete Vokabular. Ein kurzes Glossar fasst die einzeiligen Definitionen zusammen.

Capability-Operator vs. Workload

• Ein Capability-Operator ist ein Upstream-Operator, von dem die Plattform abhängt (CloudNativePG, External Secrets, LiteLLM, …). Der Operator installiert diese, indem er ihre offiziellen Helm-Charts ansteuert.
• Ein Workload ist das eigentliche laufende Ding, das Sie interessiert — eine LiteLLM-Instanz, ein Langfuse-Deployment, ein Postgres-Cluster. Workloads werden als die Upstream-CRs ausgedrückt, die Capability-Operatoren reconcilen, oder als ein Workload-Helm-Release.

Ihre Custom Resources beschreiben Workloads; der Operator installiert die Capability-Operatoren, die diese Workloads benötigen.

Custom-Resource-Kategorien

Kategorie	Ressourcen	Rolle
Lizenz	License	Cluster-scoped Entitlements
Secrets	SecretsManagement	Das Anmeldedaten-Backend (erforderlich)
Datenspeicher	PostgresCluster, ClickHouseCluster, RedisInstance, MongoCluster, MeilisearchInstance	Gemeinsam genutzter Speicher und Suche
Workloads	Gateway, Observability, ChatUI	Die benutzerseitige KI-Plattform
Plattform	ManagementPlane	Die Admin-Konsole (standardmäßig bereitgestellt)
Komposition	Stack, User, Identity, Organization, Team	Bündelung und Identität (lizenziert)

Datenspeicher-Modi: managed, adopt, external

Jede Datenspeicher-Ressource trägt einen mode, der entscheidet, wie viel der Operator besitzt:

• managed — der Operator installiert den Capability-Operator (provenance-bewusst) und erstellt, besitzt und garbage-collected die Datenspeicher-Custom-Resource.
• adopt — der Operator referenziert einen Datenspeicher, den Sie bereits in-cluster erstellt haben (zum Beispiel einen bestehenden CNPG Cluster). Er kann eine logische Datenbank darin bereitstellen, aber löscht oder rekonfiguriert niemals den Cluster selbst.
• external — der Datenspeicher lebt außerhalb des Clusters (z. B. Azure Database for PostgreSQL). Der Operator installiert keinen Capability-Operator und erstellt keine Datenspeicher-CR; er verkabelt nur ein Verbindungs-Secret in den konsumierenden Workload.

Ein Capability-Operator-Chart wird nur installiert, wenn mindestens eine Ressource seinen managed-Modus wählt. Wenn alles external oder adopt ist, wird dieser Operator niemals installiert.

Einen Datenspeicher aus einem anderen Namespace adoptieren

Jede adopt-Referenz akzeptiert einen optionalen namespace, der adoptierte Datenspeicher darf also überall im Cluster liegen — etwa in einem zentralen data-Namespace, den sich mehrere Anwendungs-Namespaces teilen. Zwei Regeln machen das möglich:

• Der Verbindungs-Host wird aus dem referenzierten Namespace gebildet.status.host zeigt auf den Service neben dem adoptierten Datenspeicher, nicht auf Ihre CR.
• Anmeldedaten werden immer im eigenen Namespace der Datenspeicher-CR veröffentlicht. Konsumenten (Gateway, Observability, ChatUI) lesen status.credentialsSecret im Namespace der referenzierten Datenspeicher-Ressource. Liegt das echte Secret neben der adoptierten Instanz, spiegelt der Operator es deshalb in ein eigenes Secret namens <name>-adopted-credentials hierher. Zeigen Sie mit der Anmeldedaten-Referenz im adopt-Block einfach dorthin, wo das Secret tatsächlich liegt — den Rest erledigt der Operator.

CNPG-Datenbanken entstehen neben dem adoptierten Cluster

Bei PostgresCluster werden die CNPG-Database-Ressourcen hinter databases[]im Namespace des adoptierten Clusters angelegt — CNPGs Database.spec.cluster wird im eigenen Namespace der Database aufgelöst, anderswo könnten sie also gar nicht funktionieren. Sie tragen ein Owned-by-Label und werden entfernt, wenn Sie den adoptierenden PostgresCluster löschen; der adoptierte Cluster selbst bleibt unangetastet.

Wenn Sie den Operator mit --watch-namespaces betreiben, nehmen Sie jeden Namespace auf, aus dem Sie adoptieren — der Operator muss den referenzierten Datenspeicher und dessen Secret lesen können.

Zweistufige Provenance

„Provenance“ ist die Regel, dass der Operator niemals erneut installiert, was Sie installiert haben, und niemals deinstalliert, was er nicht besitzt. Sie gilt auf zwei Ebenen:

• Operator-Installations-Provenance — beim Sicherstellen eines Capability-Operators erkennt der Operator, ob ein passendes Release bereits existiert. Trägt es das Ownership-Label des Operators, ist es operatoreigen; andernfalls ist es adoptiert. Installationen sind ref-gezählt; ein operatoreigenes Release wird nur deinstalliert, wenn keine Ressource es benötigt.
• Datenspeicher-Instanz-Provenance — dasselbe Prinzip eine Ebene tiefer, ausgedrückt über das obige mode-Feld.

type × mode

Datenspeicher haben sowohl einen type (die Implementierung/das Backend) als auch einen mode (die Provenance). Beispielsweise hat ein PostgresClustertype: cnpg (CloudNativePG) und einen Modus von managed. Der type-Switch ist der Weg, zusätzliche Backends hinzuzufügen — zalando und cockroachdb sind hinter derselben Schnittstelle als Gerüst angelegt und melden einen klaren „noch nicht implementiert“-Status, bis sie fertiggestellt sind.

Auto-Wiring

Auto-Wiring ist die lizenzierte Capability, bei der der Operator Anmeldedaten komponentenübergreifend bereitstellt und injiziert, sodass Sie niemals komponentenübergreifende Secrets von Hand konfigurieren. Beispiele:

• ChatUI.gatewayRef → präge einen virtuellen LiteLLM-Schlüssel für die UI und injiziere die In-Cluster-Gateway-URL + Schlüssel.
• Gateway.observabilityRef → verkabele den Langfuse-Callback von LiteLLM, sodass Traces automatisch exportiert werden.
• Gateway.database.mode: postgresCluster → stelle die litellm-Datenbank bereit und injiziere ihre Anmeldedaten.

Ohne die Funktion auto-wiring hat jede Referenz einen manuellen Fallback — Sie liefern die Anmeldedaten explizit, und die Plattform läuft dennoch. Siehe Komponentenübergreifendes Auto-Wiring.

Secrets-Backends

SecretsManagement wählt eines von zwei Backends:

• ESO (External Secrets Operator) — zieht aus einem externen Secret-Store (Azure Key Vault, HashiCorp Vault, AWS, GCP, …) in namespaced Kubernetes Secrets.
• Sealed Secrets — at-rest verschlüsselte Manifeste, die in-cluster entschlüsselt werden.

Eine dritte Secret-Klasse ist operator-generiert — virtuelle Schlüssel, Callback-Schlüssel und Datenspeicher-Passwörter, die der Operator selbst prägt, gespeichert als operatoreigene Secrets. Siehe Secrets-Verwaltung.

Referenzen

Alle Querverweise verwenden eine kleine Menge von Formen:

• ObjectRef — { name, namespace? }; namespace ist standardmäßig der eigene der Ressource. Namespace-übergreifende Referenzen sind für Datenspeicher, Gateways und Langfuse erlaubt.
• LocalRef — { name }; nur im selben Namespace (verwendet von secretsRef).
• SecretKeyRef — { name, key?, namespace? }; Secret-Referenzen bleiben im Namespace.

Eine Workload-Ressource kann einen secretsRef tragen, der auf eine SecretsManagement im selben Namespace zeigt, die ihre Secrets erzeugt; ohne ihn liest sie Secrets, die Sie selbst verwalten (siehe secretsRef).

Status und Conditions

Jede Ressource exponiert status.conditions mit mindestens einer Ready-Condition plus phasenspezifischen Conditions (SecretsReady, OperatorsReady, DatastoreReady, WorkloadReady, …), die jeweils einen reason und eine message tragen, sowie einer observedGeneration. Der Operator zeichnet Kubernetes-Events für Adoptionen, lizenz-gegatete Skips, Instanz-Cap-Ablehnungen, Ablauf-Herabstufungen und Garbage Collection auf — sodass eine ins Stocken geratene Installation selbsterklärend ist. Siehe Fehlerbehebung.

Lizenz-Entitlements

Die License trägt explizite Entitlements — eine aufgezählte features-Liste und quantitative limits (Instanz-Caps pro Typ). Es gibt keinen Wildcard. Wenn keine gültige Lizenz vorliegt, wendet der Operator eingebaute Community-Defaults an (kostenpflichtige Funktionen aus, Caps auf Free-Niveau), und die Basis-Plattform läuft weiter. Siehe Editionen & Lizenzierung.