Tipi di controller di Config Connector

Config Connector utilizza un'architettura a livelli per riconciliare le risorse nel tuo Google Cloud ambiente con le tue specifiche Kubernetes. Un controller principale di primo livello indirizza la riconciliazione di ogni risorsa a una delle quattro implementazioni del controller sottostanti.

Comprendere ogni tipo di controller, le differenze tecniche e come controllare il routing a livello di spazio dei nomi può aiutarti a ottimizzare le prestazioni e risolvere i problemi di configurazione.

Tipi di controller sottostanti

Config Connector utilizza i seguenti tipi di controller:

  • Controller diretti: questo controller utilizza la libreria standard di Kubernetes controller-runtime e comunica direttamente con le API Google Cloud utilizzando gli SDK Go ufficiali. Google Cloud Ti consigliamo di utilizzare i controller diretti, se possibile. Non tutte le risorse supportano il controller diretto. Per impostazione predefinita, le nuove risorse utilizzano il controller diretto. Le risorse esistenti vengono migrate regolarmente. Per ulteriori informazioni, consulta le note di rilascio.
  • Controller basati su Terraform (TF): questo controller funge da "wrapper" per il provider Google Terraform. Il controller traduce le specifiche di Kubernetes Resource Model (KRM) in stati compatibili con Terraform e implementa le operazioni plan e apply di Terraform.
  • Controller basati su DCL: questo tipo di controller funge da "wrapper" per la Google Cloud libreria client dichiarativa (DCL).
  • Controller specifici per IAM: si tratta di controller specializzati progettati specificamente per gestire le risorse Identity and Access Management (IAM), tra cui IAMPolicy, IAMPartialPolicy, IAMPolicyMember e IAMAuditConfig. Alcune risorse IAM supportano facoltativamente il controller diretto.

Vantaggi dei controller diretti

Alcuni tipi di risorse supportano più tipi di controller. Se una risorsa supporta il controller diretto, ti consigliamo di utilizzare il controller diretto anziché un altro tipo di controller per i seguenti motivi:

  • Consumo ridotto di risorse: i controller diretti non hanno l'overhead di CPU e memoria associato all'esecuzione e alla traduzione degli stati basati su Terraform o DCL.
  • Latenza di riconciliazione migliorata: i controller diretti possono eseguire operazioni dirette sugli endpoint, riducendo il tempo medio necessario per raggiungere la coerenza dello stato della risorsa. Google Cloud
  • Stato granulare e differenze strutturate: il controller diretto fornisce report sulle differenze strutturate nei log cnrm-controller-manager. Questi log contengono le modifiche precise dei campi che hanno generato errori come i loop di riconciliazione, il che può semplificare la risoluzione dei problemi.
  • Stato osservato nativo: i controller diretti compilano status.observedState nello stato della risorsa, fornendo una visualizzazione trasparente, lato server dei campi delle risorse restituiti direttamente dalle Google Cloud API.
  • Gestione del ciclo di vita migliorata: i controller diretti includono funzionalità aggiuntive come l'eliminazione orfana graduale.

Controller di routing principale

Indipendentemente dal tipo di risorsa, Config Connector intercetta tutte le richieste di riconciliazione all'interno di un controller principale centrale. Il controller principale funge da router, valutando quale logica secondaria gestisce la sincronizzazione attiva utilizzando le seguenti regole di precedenza:

  1. Override dello spazio dei nomi: il controller principale controlla innanzitutto la configurazione della risorsa ConfigConnectorContext nello spazio dei nomi della risorsa di destinazione per eventuali override espliciti del controller.
  2. Valori predefiniti statici: se non vengono specificati override locali, il controller principale utilizza per impostazione predefinita il riconciliatore in fase di compilazione definito nella configurazione di mappatura statica di Config Connector.

Identificare il controller per una risorsa

Puoi determinare quale tipo di controller è configurato o attivo per una Google Cloud risorsa specifica utilizzando la mappatura del codice attivo o esaminando le strutture CustomResourceDefinition (CRD) in Google Kubernetes Engine (GKE).

Per cercare la configurazione statica di una risorsa, esamina la risorsa in GitHub all'indirizzo pkg/controller/resourceconfig/static_config.go e cerca il blocco di configurazione della risorsa, come nell'esempio seguente:

{Group: "alloydb.cnrm.cloud.google.com", Kind: "AlloyDBCluster"}: {
    DefaultController:    k8s.ReconcilerTypeTerraform,
    SupportedControllers: []k8s.ReconcilerType{k8s.ReconcilerTypeDirect, k8s.ReconcilerTypeTerraform},
}
  • DefaultController: indica il riconciliatore predefinito utilizzato se non vengono specificate regole di override del contesto a livello di spazio dei nomi.
  • SupportedControllers: elenca tutti i riconciliatori implementati e disponibili per questa risorsa. Gli override passano ai riconciliatori elencati qui.

Per esaminare le etichette CRD, utilizza il comando kubectl get crd:

kubectl get crd RESOURCE_NAME -o jsonpath='{.metadata.labels}'

Sostituisci RESOURCE_NAME con il nome esatto della CRD di Config Connector, ad esempio bigquerydatasets.bigquery.cnrm.cloud.google.com.

Controlla i risultati per le seguenti informazioni:

  • cnrm.cloud.google.com/tf2crd: "true": la risorsa viene gestita dal controller basato su Terraform (TF).
  • cnrm.cloud.google.com/dcl2crd: "true": la risorsa viene gestita dal controller basato su DCL.
  • Assenza di queste etichette: la risorsa viene gestita dal controller diretto.

Eseguire l'override del controller predefinito

Esistono due metodi principali per eseguire l'override del tipo di controller in Config Connector. La distinzione tra questi metodi riguarda principalmente l'ambito operativo, l'overhead di manutenzione e la precedenza che hanno durante la riconciliazione.

La tabella seguente riassume le differenze tra i due approcci:

Funzionalità Anotazione della risorsa Override di ConfigConnectorContext
Ambito Singola istanza di risorsa Tutte le risorse di un tipo in uno spazio dei nomi
Precedenza Massima (esegue l'override di ConfigConnectorContext) Media (esegue l'override del valore predefinito statico)
Consigliata? No Sì
Ideale per Test una tantum Rollout a livello di team o progetto

Eseguire l'override del controller per una risorsa specifica

Puoi forzare l'esecuzione di un'istanza di risorsa specifica con un riconciliatore specifico aggiungendo l'annotazione alpha.cnrm.cloud.google.com/reconciler ai metadati della risorsa. Sebbene questo approccio non sia consigliato per i motivi specificati nella sezione precedente, potrebbe essere necessario per testare le configurazioni per una singola istanza di risorsa o per mantenere le configurazioni legacy.

apiVersion: bigquery.cnrm.cloud.google.com/v1beta1
kind: BigQueryDataset
metadata:
  name: my-bq-ds
  namespace: NAMESPACE_NAME
  annotations:
    alpha.cnrm.cloud.google.com/reconciler: direct
spec:
  ...

I valori supportati per l'annotazione sono direct, tf o dcl.

Eseguire l'override del controller per uno spazio dei nomi

Per configurare un override a livello di spazio dei nomi utilizzando la risorsa personalizzata ConfigConnectorContext, completa i seguenti passaggi:

  1. Recupera il nome e il gruppo dalle definizioni delle risorse. Ad esempio, per la risorsa BigQueryDataset, il tipo di risorsa è BigQueryDataset e il gruppo è bigquery.cnrm.cloud.google.com.

  2. Modifica l'oggetto ConfigConnectorContext all'interno dello spazio dei nomi contenente le risorse gestite:

    kubectl edit configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME

    Sostituisci NAMESPACE_NAME con lo spazio dei nomi di destinazione.

  3. Aggiungi gli override di destinazione. Ad esempio, per eseguire l'override di tutte le istanze BigQueryDataset in questo spazio dei nomi in modo che vengano eseguite con il controller diretto, definisci la configurazione come segue:

    apiVersion: core.cnrm.cloud.google.com/v1beta1
kind: ConfigConnectorContext
metadata:
  name: configconnectorcontext.core.cnrm.cloud.google.com
  namespace: NAMESPACE_NAME
spec:
  googleServiceAccount: "kcc-sa@my-project.iam.gserviceaccount.com"
  experiments:
    controllerOverrides:
      BigQueryDataset.bigquery.cnrm.cloud.google.com: direct

  4. Salva e applica la risorsa. Il controller principale applica automaticamente le nuove regole di routing del riconciliatore diretto in modo dinamico a tutte le risorse corrispondenti in questo spazio dei nomi.

Vincoli e casi d'uso dell'override dello spazio dei nomi

  • Requisito di supporto esplicito: affinché un override abbia esito positivo, il tipo di controller di destinazione deve essere implementato per il tipo di risorsa. Per verificare se un tipo di controller è supportato, consulta Identificare il controller per una risorsa. Se il tipo di controller specificato nell'override non è supportato, il controller principale ignora l'override e il riconciliatore predefinito continua a gestire la risorsa.
  • Limite dello spazio dei nomi: gli override in un ConfigConnectorContext si applicano collettivamente a tutte le istanze di quel tipo di risorsa che risiedono all'interno di quello spazio dei nomi specifico. Non puoi scegliere come target singole istanze di risorse con override con ambito di spazio dei nomi.
  • Controllo degli accessi: l'aggiornamento di un oggetto ConfigConnectorContext in genere richiede privilegi del team della piattaforma di livello superiore rispetto alle modifiche standard delle risorse.
  • Report sullo stato dell'override: se negli override di ConfigConnectorContext viene specificato un tipo di controller non valido o non supportato, il controller principale contrassegna il contesto come non integro. Puoi verificarlo eseguendo kubectl get configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME -o yaml e controllando i campi .status.healthy e .status.errors.
  • Quando utilizzare: questo è l'approccio consigliato per eseguire l'override dei controller. Utilizzalo per attivare l'utilizzo di controller moderni (come quelli diretti) per interi spazi dei nomi o per applicare la coerenza architetturale in un progetto.