Panoramica delle Custom Resource

Tutte le risorse appartengono all'API group core.navique.com, versione v1alpha1. Questa pagina è la mappa; ogni risorsa ha una propria pagina di riferimento con tutti i campi, i valori predefiniti, lo stato e gli esempi.

La mappa delle risorse

Risorsa	Scope	Ruolo
License	Cluster	Licenza offline firmata singleton; abilita funzionalità e limiti di istanze
SecretsManagement	Namespaced	Obbligatoria. Backend delle credenziali — ESO o Sealed Secrets
PostgresCluster	Namespaced	PostgreSQL condiviso, multi-database
ClickHouseCluster	Namespaced	ClickHouse
RedisInstance	Namespaced	Redis
MongoCluster	Namespaced	MongoDB condiviso, multi-database
MeilisearchInstance	Namespaced	Backend di ricerca Meilisearch
Gateway	Namespaced	Gateway AI (LiteLLM o Wäg, tramite spec.type) + modelli / team / organizzazioni
Observability	Namespaced	Osservabilità LLM (Langfuse v3)
ChatUI	Namespaced	UI LibreChat, collegata a un Gateway
ManagementPlane	Namespaced	Configura la console di amministrazione (distribuita di default)
Stack	Namespaced	Umbrella opzionale — bundle curato e collegato automaticamente (con licenza)
User	Namespaced	Una persona / postazione licenziata (conteggiata nel limite users)
Identity / Organization / Team	Namespaced	Account per backend e tenancy gestiti (con licenza)
Lock	Namespaced	Protegge una risorsa dall'eliminazione accidentale (lock in stile Azure)
ServiceMesh	Cluster	Installa/adotta Istio (Sail) per mTLS + isolamento dei tenant (con licenza)

Convenzioni comuni a tutte le risorse

Valgono per ogni risorsa, salvo diversa indicazione nella relativa pagina.

secretsRef (opzionale sui workload)

Ogni workload (Gateway, Observability, ChatUI) fa riferimento direttamente a ciascuna credenziale di cui ha bisogno — un Secret dell'account admin, un Secret delle chiavi, un Secret di connessione. secretsRef indica facoltativamente una SecretsManagement nello stesso namespace che produce questi Secret (ESO da un vault, oppure SealedSecrets); il workload attende quindi che sia Ready.

Ometti secretsRef per eseguire un workload su semplici Secret Kubernetes creati da te — senza bisogno di ESO o SealedSecrets. Uno Stack lo imposta solo quando ha un backend spec.secrets.

Database per i workload che fanno riferimento a un datastore

Un workload che fa riferimento a un datastore gestito condiviso ha bisogno di un proprio database al suo interno: un Observability su un PostgresCluster (langfuse.postgres.databaseName) e su un ClickHouseCluster (langfuse.clickhouse.databaseName), un Gateway su un PostgresCluster (database.databaseName, predefinito litellm) e — per Wäg con storage separato — su un ClickHouseCluster (waeg.clickhouseDatabase, predefinito waeg), una ChatUI su un MongoCluster (mongo.databaseName, predefinito LibreChat).

• Con la licenza auto-wiring il datastore individua questi riferimenti e crea da sé i database, accanto a quelli dichiarati nel suo spec.databases. La sua spec non viene mai modificata (uno strumento GitOps non ha nulla da ripristinare); ogni database in status.databases elenca in claimedBy i workload che lo usano. Il Secret di connessione del workload viene creato e montato come di consueto.
• Senza di essa, dichiara il database nel spec.databases del datastore. Finché non lo fai, la condition DatastoreReady del workload indica la voce esatta da aggiungere.

Un database non viene mai eliminato quando il suo workload scompare: i dati sopravvivono a un'eliminazione accidentale. Uno Stack dichiara i propri database, quindi funziona in entrambi i casi.

Forme dei riferimenti

Tipo	Forma	Note
ObjectRef	{ name, namespace? }	Il namespace predefinito è quello della risorsa stessa; cross-namespace consentito per datastore / gateway / observability
LocalRef	{ name }	Solo stesso namespace (secretsRef)
SecretKeyRef	{ name, key?, namespace? }	I riferimenti ai Secret restano nello stesso namespace

Stato e condition

Ogni risorsa espone status.conditions []metav1.Condition con almeno una condition Ready più condition per fase, e un observedGeneration. Le colonne di stampa consigliate per kubectl get mostrano fase/Ready, mode/type e un endpoint o un conteggio significativo per ogni risorsa.

Datastore type × mode

Le cinque risorse datastore condividono la stessa forma: un type (implementazione del backend) e un mode (provenienza — managed / adopt / external). Vedi Concetti fondamentali.

Come si compongono

Le risorse si fanno riferimento a vicenda per formare la piattaforma:

ChatUI ──gatewayRef──▶ Gateway ──observabilityRef──▶ Observability
  │                       │                              │
  ├─mongo──▶ MongoCluster │                              ├─postgres──▶ PostgresCluster
  └─meili──▶ Meilisearch  └─database──▶ PostgresCluster  ├─clickhouse▶ ClickHouseCluster
                                                         └─redis─────▶ RedisInstance

All workloads ──secretsRef (optional)──▶ SecretsManagement (same namespace)
License (cluster) ──gates──▶ every controller's feature flags + instance caps

I riferimenti possono attraversare i namespace (tranne i riferimenti ai Secret, che restano nello stesso namespace), e più workload possono condividere un unico datastore o un unico Observability.