Concetti fondamentali

Questa pagina definisce il vocabolario usato in tutta la documentazione. Un breve Glossario raccoglie le definizioni in una riga.

Operatore di capacità vs. workload

• Un operatore di capacità è un operatore upstream da cui la piattaforma dipende (CloudNativePG, External Secrets, LiteLLM, …). L'operatore li installa tramite i loro Helm chart ufficiali.
• Un workload è ciò che vuoi effettivamente far girare — un'istanza LiteLLM, un deployment di Langfuse, un cluster Postgres. I workload sono espressi come CR upstream riconciliate dagli operatori di capacità, oppure come release Helm di workload.

Le custom resource descrivono i workload; l'operatore installa gli operatori di capacità di cui quei workload hanno bisogno.

Categorie di custom resource

Categoria	Risorse	Ruolo
Licenza	License	Entitlement a livello di cluster
Segreti	SecretsManagement	Il backend delle credenziali (obbligatorio)
Datastore	PostgresCluster, ClickHouseCluster, RedisInstance, MongoCluster, MeilisearchInstance	Storage e ricerca condivisi
Workload	Gateway, Observability, ChatUI	La piattaforma AI rivolta agli utenti
Piattaforma	ManagementPlane	La console di amministrazione (distribuita di default)
Composizione	Stack, User, Identity, Organization, Team	Bundle e identità (con licenza)

Modalità dei datastore: managed, adopt, external

Ogni risorsa datastore ha un campo mode che stabilisce quanto ne possiede l'operatore:

• managed — l'operatore installa l'operatore di capacità (tenendo conto della provenienza) e crea, possiede ed elimina tramite garbage collection la custom resource del datastore.
• adopt — l'operatore referenzia un datastore già creato dall'utente nel cluster (ad esempio un Cluster CNPG esistente). Può effettuare il provisioning di un database logico al suo interno, ma non elimina né riconfigura mai il cluster stesso.
• external — il datastore si trova fuori dal cluster (ad es. Azure Database for PostgreSQL). L'operatore non installa alcun operatore di capacità e non crea alcuna CR di datastore; si limita a collegare un secret di connessione al workload che lo usa.

Il chart di un operatore di capacità viene installato solo se almeno una risorsa seleziona la sua modalità managed. Se tutto è external o adopt, quell'operatore non viene mai installato.

Adottare un datastore da un altro namespace

Ogni riferimento adopt accetta un namespace opzionale, quindi il datastore adottato può trovarsi ovunque nel cluster — ad esempio in un namespace centrale data condiviso da più namespace applicativi. Due regole rendono possibile questo scenario:

• L'host di connessione viene costruito a partire dal namespace referenziato.status.host punta al service accanto al datastore adottato, non alla propria CR.
• Le credenziali vengono sempre pubblicate nel namespace della CR del datastore. I consumer (Gateway, Observability, ChatUI) leggono status.credentialsSecret nel namespace della risorsa datastore che referenziano; quindi, quando il Secret reale si trova accanto all'istanza adottata, l'operatore lo replica qui in un Secret di sua proprietà denominato <name>-adopted-credentials. Ti basta far puntare il riferimento alle credenziali del blocco adopt al luogo in cui si trova effettivamente il Secret; al resto pensa l'operatore.

I database CNPG vengono creati accanto al cluster adottato

Per PostgresCluster, le risorse CNPG Database che supportano databases[] vengono create nel namespace del cluster adottato — Database.spec.cluster di CNPG viene risolto nel namespace del Database stesso, quindi non potrebbero funzionare altrove. Portano un'etichetta owned-by e vengono rimosse quando elimini il PostgresCluster che effettua l'adozione; il cluster adottato non viene mai toccato.

Se esegui l'operatore con --watch-namespaces, includi ogni namespace da cui adotti — l'operatore deve poter leggere il datastore referenziato e il relativo Secret.

Provenienza a due livelli

La "provenienza" è la regola per cui l'operatore non reinstalla mai ciò che l'utente ha installato e non disinstalla mai ciò che non possiede. Si applica a due livelli:

• Provenienza dell'installazione degli operatori — quando deve garantire la presenza di un operatore di capacità, l'operatore rileva se esiste già una release corrispondente. Se porta l'etichetta di proprietà dell'operatore è owned; altrimenti è adopted. Le installazioni sono soggette a conteggio dei riferimenti; una release owned viene disinstallata solo quando nessuna risorsa ne ha bisogno.
• Provenienza delle istanze di datastore — lo stesso principio un livello più in basso, espresso tramite il campo mode descritto sopra.

type × mode

I datastore hanno sia un type (l'implementazione/il backend) sia un mode (la provenienza). Ad esempio un PostgresCluster ha type: cnpg (CloudNativePG) e modalità managed. Lo switch type è il meccanismo con cui si aggiungono nuovi backend — zalando e cockroachdb sono predisposti dietro la stessa interfaccia e riportano uno stato chiaro "not yet implemented" finché non saranno completati.

Collegamento automatico

Il collegamento automatico (auto-wiring) è la capacità con licenza con cui l'operatore crea e inietta le credenziali tra i componenti, così da non dover mai configurare a mano i segreti tra componenti. Esempi:

• ChatUI.gatewayRef → genera una virtual key LiteLLM per l'interfaccia e inietta l'URL interno del gateway + la chiave.
• Gateway.observabilityRef → collega il callback Langfuse di LiteLLM in modo che le trace vengano esportate automaticamente.
• Gateway.database.mode: postgresCluster → effettua il provisioning del database litellm e ne inietta le credenziali.

Senza la funzionalità auto-wiring, ogni riferimento ha un fallback manuale — fornisci tu le credenziali esplicitamente e la piattaforma funziona comunque. Consulta Collegamento automatico tra componenti.

Backend dei segreti

SecretsManagement seleziona uno tra due backend:

• ESO (External Secrets Operator) — importa i dati da uno store di segreti esterno (Azure Key Vault, HashiCorp Vault, AWS, GCP, …) in Secret Kubernetes namespaced.
• Sealed Secrets — manifest cifrati a riposo, decifrati nel cluster.

Una terza classe di segreti è quella generata dall'operatore — virtual key, chiavi di callback e password dei datastore create dall'operatore stesso, conservate come Secret di sua proprietà. Consulta Gestione dei segreti.

Riferimenti

Tutti i riferimenti incrociati usano un piccolo insieme di forme:

• ObjectRef — { name, namespace? }; il namespace è per default quello della risorsa stessa. I riferimenti cross-namespace sono ammessi per datastore, gateway e Langfuse.
• LocalRef — { name }; solo nello stesso namespace (usato da secretsRef).
• SecretKeyRef — { name, key?, namespace? }; i riferimenti ai Secret restano nello stesso namespace.

Una risorsa workload può avere un secretsRef che punta a un SecretsManagement dello stesso namespace che ne produce i Secret; in assenza di questo, legge i Secret gestiti direttamente dall'utente (consulta secretsRef).

Stato e condition

Ogni risorsa espone status.conditions con almeno una condition Ready più condition per singola fase (SecretsReady, OperatorsReady, DatastoreReady, WorkloadReady, …), ciascuna con un reason e un message, oltre a un observedGeneration. L'operatore registra Event Kubernetes per adozioni, salti dovuti alla licenza, rifiuti per limite di istanze, downgrade alla scadenza e garbage collection — così un'installazione bloccata si spiega da sola. Consulta Risoluzione dei problemi.

Entitlement della licenza

La License contiene entitlement espliciti — un elenco enumerato di features e limits quantitativi (limiti di istanze per tipo). Non esistono wildcard. In assenza di una licenza valida, l'operatore applica i default Community integrati (funzionalità a pagamento disattivate, limiti al livello gratuito) e la piattaforma di base continua a funzionare. Consulta Edizioni e licenze.