Concepts fondamentaux

Cette page définit le vocabulaire utilisé tout au long de la documentation. Un bref Glossaire rassemble les définitions en une ligne.

Opérateur de capacité vs. workload

• Un opérateur de capacité est un opérateur en amont dont la plateforme dépend (CloudNativePG, External Secrets, LiteLLM, …). L'opérateur les installe en pilotant leurs Helm charts officiels.
• Un workload est la chose en cours d'exécution qui vous importe réellement — une instance LiteLLM, un déploiement Langfuse, un cluster Postgres. Les workloads sont exprimés sous forme de CR en amont que les opérateurs de capacités réconcilient, ou sous forme de release Helm de workload.

Vos ressources personnalisées décrivent des workloads ; l'opérateur installe les opérateurs de capacités dont ces workloads ont besoin.

Catégories de ressources personnalisées

Catégorie	Ressources	Rôle
License	License	Droits d'utilisation cluster-scoped
Secrets	SecretsManagement	Le backend d'identifiants (requis)
Datastores	PostgresCluster, ClickHouseCluster, RedisInstance, MongoCluster, MeilisearchInstance	Stockage et recherche partagés
Workloads	Gateway, Observability, ChatUI	La plateforme d'IA orientée utilisateur
Plateforme	ManagementPlane	La console d'administration (déployée par défaut)
Composition	Stack, User, Identity, Organization, Team	Bundling et identité (sous licence)

Modes de datastore : managed, adopt, external

Chaque ressource datastore porte un mode qui décide de l'étendue de ce que l'opérateur détient :

• managed — l'opérateur installe l'opérateur de capacité (de manière consciente de la Provenance) et crée, détient et garbage-collecte la ressource personnalisée datastore.
• adopt — l'opérateur référence un datastore que vous avez déjà créé dans le cluster (par exemple un CNPG Cluster existant). Il peut provisionner une base de données logique à l'intérieur, mais ne supprime ni ne reconfigure jamais le cluster lui-même.
• external — le datastore réside en dehors du cluster (par ex. Azure Database for PostgreSQL). L'opérateur n'installe aucun opérateur de capacité et ne crée aucune CR de datastore ; il câble uniquement un secret de connexion dans le workload consommateur.

Un chart d'opérateur de capacité n'est installé que si au moins une ressource sélectionne son mode managed. Si tout est external ou adopt, cet opérateur n'est jamais installé.

Adopter un datastore depuis un autre namespace

Chaque référence adopt accepte un namespace optionnel : le datastore adopté peut donc résider n'importe où dans le cluster — par exemple dans un namespace data central partagé par plusieurs namespaces applicatifs. Deux règles rendent cela possible :

• L'hôte de connexion est construit à partir du namespace référencé.status.host désigne le service situé à côté du datastore adopté, et non votre CR.
• Les identifiants sont toujours publiés dans le namespace de la CR datastore. Les consommateurs (Gateway, Observability, ChatUI) lisent status.credentialsSecret dans le namespace de la ressource datastore qu'ils référencent ; lorsque le vrai Secret se trouve auprès de l'instance adoptée, l'opérateur le recopie donc ici dans un Secret qu'il détient, nommé <name>-adopted-credentials. Faites pointer la référence d'identifiants du bloc adopt là où le Secret se trouve réellement, l'opérateur s'occupe du reste.

Les bases CNPG sont créées à côté du cluster adopté

Pour PostgresCluster, les ressources CNPG Database qui portent databases[] sont créées dans le namespace du cluster adopté — le champ Database.spec.cluster de CNPG est résolu dans le namespace de la Database elle-même, elles ne pourraient donc fonctionner nulle part ailleurs. Elles portent un label owned-by et sont supprimées lorsque vous supprimez le PostgresCluster adoptant ; le cluster adopté, lui, n'est jamais touché.

Si vous exécutez l'opérateur avec --watch-namespaces, incluez chaque namespace depuis lequel vous adoptez — l'opérateur doit pouvoir lire le datastore référencé et son Secret.

Provenance à deux niveaux

La « Provenance » est la règle selon laquelle l'opérateur ne réinstalle jamais ce que vous avez installé, et ne désinstalle jamais ce qu'il ne détient pas. Elle s'applique sur deux niveaux :

• Provenance d'installation d'opérateur — lorsqu'il garantit un opérateur de capacité, l'opérateur détecte si une release correspondante existe déjà. Si elle porte le label de propriété de l'opérateur, elle est détenue ; sinon elle est adoptée. Les installations sont ref-comptées ; une release détenue n'est désinstallée que lorsque aucune ressource n'en a besoin.
• Provenance d'instance de datastore — le même principe un niveau plus bas, exprimé via le champ mode ci-dessus.

type × mode

Les datastores ont à la fois un type (l'implémentation/le backend) et un mode (la provenance). Par exemple un PostgresCluster a type: cnpg (CloudNativePG) et un mode managed. Le commutateur type est la manière dont des backends additionnels sont ajoutés — zalando et cockroachdb sont scaffoldés derrière la même interface et rapportent un statut clair « not yet implemented » jusqu'à leur achèvement.

Câblage automatique

Le câblage automatique est la capacité sous licence où l'opérateur provisionne et injecte des identifiants entre composants, afin que vous ne configuriez jamais de secrets inter-composants à la main. Exemples :

• ChatUI.gatewayRef → émettre une clé virtuelle LiteLLM pour l'interface et injecter l' URL + la clé de la gateway dans le cluster.
• Gateway.observabilityRef → câbler le callback Langfuse de LiteLLM afin que les traces s'exportent automatiquement.
• Gateway.database.mode: postgresCluster → provisionner la base de données litellm et injecter ses identifiants.

Sans la fonctionnalité auto-wiring, chaque référence dispose d'une solution manuelle de repli — vous fournissez les identifiants explicitement et la plateforme fonctionne quand même. Voir Câblage automatique entre composants.

Backends de secrets

SecretsManagement sélectionne l'un des deux backends :

• ESO (External Secrets Operator) — tire depuis un magasin de secrets externe (Azure Key Vault, HashiCorp Vault, AWS, GCP, …) vers des Secrets Kubernetes namespacés.
• Sealed Secrets — manifestes chiffrés au repos déchiffrés dans le cluster.

Une troisième classe de secret est générée par l'opérateur — clés virtuelles, clés de callback et mots de passe de datastore que l'opérateur émet lui-même, stockés comme Secrets détenus. Voir Gestion des secrets.

Références

Toutes les références croisées utilisent un petit ensemble de formes :

• ObjectRef — { name, namespace? } ; le namespace prend par défaut celui de la ressource elle-même. Les références cross-namespace sont autorisées pour les datastores, les gateways et Langfuse.
• LocalRef — { name } ; même namespace uniquement (utilisé par secretsRef).
• SecretKeyRef — { name, key?, namespace? } ; les références de Secret restent dans le namespace.

Une ressource de workload peut porter un secretsRef pointant vers une SecretsManagement du même namespace qui produit ses Secrets ; sans lui, elle lit des Secrets que vous gérez vous-même (voir secretsRef).

Statut et conditions

Chaque ressource expose status.conditions avec au moins une condition Ready plus des conditions par phase (SecretsReady, OperatorsReady, DatastoreReady, WorkloadReady, …), chacune portant un reason et un message, ainsi qu'un observedGeneration. L'opérateur enregistre des Events Kubernetes pour les adoptions, les skips verrouillés par licence, les refus de plafond d'instances, les rétrogradations à l'expiration et le garbage collection — de sorte qu'une installation bloquée s'explique d'elle-même. Voir Dépannage.

Droits d'utilisation de la licence

La License porte des droits d'utilisation explicites — une liste énumérée de features et des limits quantitatives (plafonds d'instances par type). Il n'y a aucun wildcard. Lorsqu' il n'y a pas de licence valide, l'opérateur applique des valeurs par défaut Community intégrées (fonctionnalités payantes désactivées, plafonds au niveau gratuit) et la plateforme de base continue de fonctionner. Voir Éditions et licences.