Provenienza e ciclo di vita

L'operatore segue una regola decisiva:

Non reinstallare mai ciò che ha installato l'utente. Non disinstallare mai ciò che non possediamo.

Questa pagina spiega come questa regola si applica alle installazioni degli operatori di capacità e alle istanze dei datastore, e come funziona la pulizia in caso di eliminazione e di migrazione.

Due livelli di provenienza

1. Provenienza dell'installazione degli operatori

Quando una risorsa ha bisogno di un operatore di capacità (ad es. un PostgresCluster gestito richiede CloudNativePG), l'installer condiviso dell'operatore rileva lo stato attuale prima di fare qualsiasi cosa:

1. Esiste una release Helm con il nome atteso nel namespace atteso?
   • Con la label di proprietà app.kubernetes.io/managed-by=navique-ai-core-operator e l'annotation core.navique.com/provenance=owned → Owned.
   • Senza queste label → Adopted (l'hai installata tu o un altro strumento).
2. Nessuna nostra release, ma i CRD dell'operatore esistono e il suo controller è in esecuzione in qualsiasi punto del cluster → Adopted.
3. Nulla di presente → Absent.

Il controller viene individuato in base all'identità — le sue label note, con ripiego sul repository della sua immagine container — e non in base a "c'è qualcosa in esecuzione nel namespace che avremmo usato". Due conseguenze da tenere presenti:

• Un operatore che hai installato in un namespace diverso (CNPG in postgres-operator invece che in cnpg-system), oppure tramite OLM / manifest grezzi / un nome di release diverso, viene adottato, non duplicato. Questi operatori possiedono CRD cluster-scoped, quindi un secondo controller entrerebbe in conflitto con il primo sulle stesse risorse.
• Un workload non correlato che condivide soltanto il namespace atteso non viene scambiato per l'operatore, quindi l'operatore viene comunque installato.

I soli CRD non bastano mai: i CRD orfani lasciati da una disinstallazione precedente contano come Absent e vengono reinstallati.

L'azione dipende dallo stato:

Stato	Azione
Absent	Installa la nostra release standalone, contrassegnata con la label/annotation di proprietà
Adopted	Registra l'adozione; coesiste; non ne gestisce mai il ciclo di vita
Owned	È già nostra; se necessario la aggiorna alla versione fissata

Poiché il rilevamento avviene prima di qualsiasi installazione, l'operatore non incorre mai nel conflitto Helm "CRD already owned by another release".

2. Provenienza delle istanze dei datastore

Lo stesso principio un livello più in basso, tramite il campo mode delle risorse datastore:

Mode	Proprietà
managed	L'operatore crea, possiede ed elimina tramite garbage collection la CR del datastore
adopt	Fa riferimento a un datastore creato dall'utente; non viene mai eliminato né riconfigurato
external	Un datastore ospitato dall'utente; viene collegato solo un secret di connessione

Installazioni lazy con conteggio dei riferimenti

Gli operatori di capacità vengono installati in modo lazy — un chart viene installato solo quando una risorsa ne seleziona effettivamente la modalità managed. Se ogni datastore è external o adopt, quell'operatore non viene mai installato.

Le installazioni sono conteggiate per riferimento. L'operatore preferisce ricalcolare il conteggio dei riferimenti anziché persisterlo: a ogni reconcile elenca le risorse pertinenti e calcola quali necessitano ancora di una data dipendenza (qualsiasi Gateway ⇒ litellm-operator; qualsiasi PostgresCluster gestito ⇒ cloudnative-pg; …). Questo meccanismo sopravvive ai riavvii dell'operatore senza alcuna contabilità esterna.

Pulizia in caso di eliminazione

Ogni risorsa ha un finalizer. All'eliminazione, il controller:

1. Elimina le CR upstream emesse, oppure disinstalla la release Helm del workload (per ChatUI / MeilisearchInstance).
2. Per ogni operatore di capacità richiesto dalla risorsa, decrementa il conteggio dei riferimenti e — solo se il conteggio arriva a zero e la release è Owned — lo disinstalla. Le release adottate ed esterne non vengono mai toccate.
3. Per i datastore gestiti, elimina la CR del datastore creata dall'operatore (non quelle adottate).
4. Rimuove il finalizer.

func Release(name, owner) error {
    refcount.Remove(name, owner)
    if refcount.Count(name) > 0 { return nil }   // still needed
    if detect(name) != Owned    { return nil }   // adopted/external — never touch
    return helm.Uninstall(name)                  // only owned + unused
}

Pulizia in caso di migrazione

Quando mode, type o i riferimenti di una risorsa cambiano, l'operatore confronta il vecchio e il nuovo status e rimuove solo le risorse possedute dall'operatore rimaste orfane. Per esempio, passare un PostgresCluster da managed a external elimina il Cluster CNPG creato dall'operatore, quindi rilascia cloudnative-pg se non rimane nessun altro consumatore. Le risorse adottate ed esterne non vengono mai eliminate.

Prontezza dell'installazione — non solo i CRD

"Ready" per un operatore di capacità significa che i suoi CRD sono Established E tutti i Deployment/StatefulSet del chart sono effettivamente Ready — non solo che i CRD esistono. Un operatore il cui pod è bloccato per la mancanza di un certificato del webhook ha CRD established ma non può funzionare, quindi l'operatore attende la prontezza effettiva.

Alcuni chart hanno dei prerequisiti. Per esempio, il certificato del webhook dell'operatore ClickHouse viene emesso da cert-manager, quindi viene prima garantita la piena prontezza di cert-manager. L'operatore tratta cert-manager come prerequisito universale e mantiene abilitati webhook e leader election (fedelmente alla produzione) invece di disabilitarli.

Verificabilità

Lo status della risorsa espone le versioni dei chart inclusi e lo stato di provenienza (owned / adopted), così puoi verificare esattamente che cosa l'operatore ha installato e che cosa ha adottato. L'operatore registra inoltre Event per adozioni, salti dovuti alla licenza, rifiuti per limiti di istanze, downgrade per scadenza e azioni di garbage collection. Vedi Risoluzione dei problemi.