Come funziona

L'operatore è un unico binario Go che esegue un manager controller-runtime. Osserva le proprie custom resource e porta il cluster allo stato che descrivono. Questa pagina illustra l'architettura; Concetti fondamentali definisce il vocabolario, e gli aspetti interni dei reconciler trattano i meccanismi del ciclo di vita.

Due livelli: operatori di capacità e workload

La piattaforma è composta da due tipi di elementi, che l'operatore mantiene nettamente separati:

• Operatori di capacità (i "motori") — LiteLLM, Langfuse, External Secrets, Sealed Secrets, CloudNativePG, cert-manager, l'operatore Redis, l'operatore ClickHouse e i controller MongoDB. Vengono installati tramite i loro Helm chart ufficiali, inclusi nel binario, con l'SDK Go di Helm v4.
• Workload (le "istanze") — il gateway, l'interfaccia, lo stack di osservabilità, i datastore e gli store dei segreti veri e propri. Sono espressi come custom resource upstream riconciliate da quegli operatori (LiteLLMInstance, CNPG Cluster, ESO ExternalSecret, …), oppure come release Helm di workload (LibreChat).

I CRD descrivono i workload; l'operatore installa gli operatori di capacità richiesti da quei workload, quindi emette le CR upstream.

La superficie dell'API

Tutto si trova nel gruppo API 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)

Tutte le risorse workload e datastore sono namespaced e multi-istanza: possono coesistere molti Gateway / Observability / ChatUI, e diversi di essi possono condividere un'unica Observability o un unico PostgresCluster — ogni consumer ottiene un proprio database all'interno del cluster condiviso, anche tra namespace diversi.

Modello di bundling — release autonome, non subchart

L'operatore non usa le dipendenze subchart di Helm. Ogni chart upstream è incluso come .tgz autonomo (incorporato tramite go:embed) e installato come propria release Helm con un nome fisso e un namespace di sistema fisso. Gli operatori di capacità sono singleton a livello di cluster, quindi ciascuno viene installato una sola volta e referenziato dai workload in qualsiasi namespace.

Perché le release autonome sono preferibili ai subchart: un operatore singleton (ad es. CloudNativePG) installato come subchart sia di Gateway sia di Observability produrrebbe due release in conflitto sugli stessi CRD, cosa che Helm rifiuta. Come release autonome, entrambi i workload referenziano l'unica installazione.

Le installazioni sono lazy — un chart viene installato solo quando una risorsa ne ha effettivamente bisogno. Se ogni datastore è external o adopt, vengono installati solo gli operatori realmente richiesti da quei workload. Consulta Chart inclusi.

Il modello di riconciliazione

Ogni controller modella il proprio lavoro come fasi ordinate persistite in status.conditions. Una riconciliazione avanza fin dove la readiness lo consente, poi viene rimessa in coda:

1. Risoluzione e gating delle dipendenze — il SecretsManagement referenziato è pronto? Le risorse datastore/gateway/langfuse referenziate sono pronte?
2. Garanzia degli operatori di capacità — installa (tenendo conto della provenienza) solo gli operatori necessari a questa risorsa, quindi attende che i loro CRD siano Established.
3. Applicazione delle risorse possedute — emette le CR upstream oppure installa/aggiorna la release Helm del workload. Ogni apply è idempotente (create-or-update).
4. Polling della readiness — imposta le condition e rimette in coda fino a Ready.

Due regole rendono questo processo robusto:

• Rimettere in coda, non restituire errori, durante l'attesa. "Non ancora pronto" restituisce un requeue, non un errore. Gli errori sono riservati ai veri malfunzionamenti e vengono gestiti con backoff esponenziale.
• Tutto è idempotente. Ogni apply può essere eseguito in sicurezza a ogni requeue.

Non esistono sync wave globali in stile Argo — i gate di readiness le sostituiscono. Dopo aver installato un chart che include CRD, l'operatore attende che i CRD siano Established e aggiorna il proprio REST mapper prima di creare risorse dei nuovi kind.

Provenienza, su due livelli

L'operatore presta attenzione a ciò che possiede. Questo si manifesta su due livelli:

• Installazione degli operatori — installa la propria release autonoma solo se l'operatore è assente. Se è già stato installato dall'utente, l'operatore lo adotta (coesiste, senza mai gestirne il ciclo di vita). Le installazioni sono soggette a conteggio dei riferimenti tra le risorse, e l'operatore disinstalla solo le release che possiede esso stesso quando nulla ne ha più bisogno.
• Istanza di datastore — ogni risorsa datastore ha un mode: managed (l'operatore la crea, la possiede e la elimina tramite garbage collection), adopt (referenzia un datastore esistente nel cluster; non lo elimina mai) o external (un datastore ospitato dall'utente; si limita a collegare un secret di connessione).

I dettagli sono descritti nella pagina Provenienza e ciclo di vita.

Riferimenti incrociati e collegamento automatico

Le risorse si referenziano a vicenda tramite {name, namespace}. Per ogni riferimento il controller:

1. Risolve e applica il gating — rimette in coda finché la risorsa referenziata non è pronta.
2. Esegue il collegamento automatico se previsto dalla licenza — con la funzionalità auto-wiring, crea e inietta le credenziali in modo che tu non debba configurare alcun segreto a mano (ad es. generando una virtual key LiteLLM per una ChatUI, o collegando il callback Langfuse di un Gateway).
3. Ripiega sulla modalità manuale — senza la funzionalità, usa i campi espliciti forniti dall'utente ed emette una condition che indica esattamente cosa impostare.

Consulta Collegamento automatico tra componenti.

Modello di processo

• Un unico binario, manager controller-runtime, leader election attiva.
• MaxConcurrentReconciles = 1 per controller (l'action.Configuration di Helm non è concurrency-safe).
• Osserva tutti i namespace di default, limitabili tramite --watch-namespaces.
• Un ClusterRole ampio — l'operatore installa CRD, RBAC, webhook e workload in più namespace.
• Distribuito come immagine più tre metodi di installazione: kustomize, un bundle OLM e un Helm chart.

Postura di sicurezza

Tutte le credenziali fornite dagli utenti provengono da External Secrets (Azure Key Vault tramite Workload Identity di default, ma è supportato qualsiasi provider ESO) o da Sealed Secrets — mai inline in una CR, in un valore di chart o in un template. Le credenziali generate dall'operatore (virtual key, chiavi di callback, password dei datastore) sono conservate come semplici Secret di sua proprietà con owner reference per la garbage collection. Consulta Gestione dei segreti.