Risolvere i problemi di sincronizzazione delle configurazioni con il cluster

La risoluzione dei problemi di sincronizzazione della configurazione in Config Sync contribuisce a garantire che i cluster rimangano allineati alla fonte di verità centrale. Quando la sincronizzazione non riesce, i deployment possono bloccarsi e le configurazioni dei cluster possono deviare dallo stato dichiarato. Puoi diagnosticare e risolvere i comuni errori di sincronizzazione di KNV2009, come le autorizzazioni di controllo dell'accesso basato su ruoli (RBAC) mancanti, gli oggetti ResourceGroup che superano i limiti di dimensione di etcd e la latenza dei webhook, per ripristinare la riconciliazione automatica.

Risolvi gli errori KNV 2009

Gli errori KNV2009 indicano che Config Sync non è riuscito a sincronizzare alcune configurazioni con il cluster. Le sezioni seguenti spiegano alcune delle cause più comuni e come risolverle.

L'operazione su determinate risorse non è consentita

Poiché devi concedere il RBAC agli oggetti RepoSync, potrebbero mancare le autorizzazioni necessarie per applicare le risorse.

Puoi verificare che le autorizzazioni non siano presenti recuperando lo stato della risorsa RepoSync:

kubectl get reposync repo-sync -n NAMESPACE -o yaml

Sostituisci NAMESPACE con lo spazio dei nomi in cui hai creato il repository dello spazio dei nomi.

Puoi anche utilizzare il comando nomos status.

Se nello stato vengono visualizzati i seguenti messaggi, significa che il reconciler in NAMESPACE non dispone dell'autorizzazione necessaria per applicare la risorsa:

KNV2009: deployments.apps "nginx-deployment" is forbidden: User "system:serviceaccount:config-management-system:ns-reconciler-default" cannot get resource "deployments" in API group "apps" in the namespace "default"

Per risolvere il problema, devi dichiarare una configurazione RoleBinding che conceda al account di servizio per il reconciler l'autorizzazione per gestire la risorsa non riuscita in quel namespace. I dettagli su come aggiungere un RoleBinding sono inclusi in Configura la sincronizzazione da più repository.

Questo problema può interessare anche gli oggetti RootSync se hai utilizzato spec.override.roleRefs per modificare i ruoli concessi all'oggetto RootSync. Se non hai impostato questo campo, agli oggetti RootSync viene concesso il ruolo cluster-admin per impostazione predefinita.

L'oggetto ResourceGroup supera il limite di dimensioni dell'oggetto di etcd

Se ricevi il seguente errore quando un reconciler tenta di applicare le configurazioni al cluster, l'oggetto ResourceGroup supera il limite di dimensioni dell'oggetto etcd:

KNV2009: too many declared resources causing ResourceGroup.kpt.dev, config-management-system/root-sync failed to be applied: task failed (action: "Inventory", name: "inventory-add-0"): Request entity too large: limit is 3145728. To fix, split the resources into multiple repositories.

Ti consigliamo di suddividere il repository Git in più repository. Se non riesci a suddividere il repository Git perché l'oggetto è già troppo grande e le modifiche non vengono mantenute, puoi mitigare il problema configurando RootSync o RepoSync per disattivare temporaneamente la scrittura dello stato dell'oggetto in ResourceGroup. Puoi farlo impostando il campo .spec.override.statusMode dell'oggetto RootSync o RepoSync su disabled. In questo modo, Config Sync interrompe l'aggiornamento dello stato delle risorse gestite nell'oggetto ResourceGroup. Questa azione riduce le dimensioni dell'oggetto ResourceGroup. Tuttavia, non puoi visualizzare lo stato delle risorse gestite da nomos status.

Se non vedi errori dall'oggetto RootSync o RepoSync, significa che gli oggetti della tua fonte di attendibilità sono stati sincronizzati con il cluster. Per verificare se la risorsa ResourceGroup supera il limite di dimensioni dell'oggetto etcd, controlla sia lo stato della risorsa ResourceGroup sia il log del controller ResourceGroup:

  1. Controlla lo stato di ResourceGroup:

    • Per controllare l'oggetto RootSync, esegui questo comando:

      kubectl get resourcegroup root-sync -n config-management-system

    • Per controllare l'oggetto RepoSync, esegui questo comando:

      kubectl get resourcegroup repo-sync -n NAMESPACE

      Sostituisci NAMESPACE con lo spazio dei nomi in cui hai creato il repository dello spazio dei nomi.

    L'output è simile al seguente:

    NAME        RECONCILING   STALLED   AGE
root-sync   True          False     35m

    Se il valore nella colonna RECONCILING è True, significa che la risorsa ResourceGroup è ancora in fase di riconciliazione.

  2. Controlla i log del controller ResourceGroup:

    kubectl logs deployment resource-group-controller-manager -c manager -n resource-group-system

    Se nell'output viene visualizzato un errore simile all'esempio seguente, la risorsa ResourceGroup è troppo grande e supera il limite di dimensioni dell'oggetto etcd:

    "error":"etcdserver: request is too large"

Per evitare che il ResourceGroup diventi troppo grande, riduci il numero di risorse nel repository Git. Puoi suddividere un repository root in più repository root.

Timeout della riconciliazione dell'applicazione della dipendenza

Se stavi sincronizzando oggetti con dipendenze, potresti ricevere un errore simile al seguente esempio quando il reconciler tenta di applicare oggetti con l'annotazione config.kubernetes.io/depends-on al cluster:

KNV2009: skipped apply of Pod, bookstore/pod4: dependency apply reconcile timeout: bookstore_pod3__Pod  For more information, see https://g.co/cloud/acm-errors#knv2009

Questo errore indica che l'oggetto di dipendenza non è stato riconciliato entro il timeout di riconciliazione predefinito di cinque minuti. Config Sync non può applicare l'oggetto dipendente perché, con l'annotazione config.kubernetes.io/depends-on, Config Sync applica gli oggetti solo nell'ordine che preferisci. Puoi eseguire l'override del timeout di riconciliazione predefinito impostando un tempo più lungo con spec.override.reconcileTimeout.

È anche possibile che la dipendenza venga riconciliata dopo il completamento del tentativo di sincronizzazione iniziale. In questo caso, la dipendenza dovrebbe essere rilevata come riconciliata al successivo tentativo di sincronizzazione, sbloccando l'applicazione di eventuali dipendenti. In questo caso, l'errore potrebbe essere segnalato brevemente e poi rimosso. L'estensione del timeout di riconciliazione potrebbe contribuire a evitare che l'errore venga segnalato in modo intermittente.

Le informazioni sull'inventario sono nulle

Se ricevi il seguente errore quando il reconciler tenta di applicare le configurazioni al cluster, è probabile che il tuo inventario non contenga risorse o che il manifest abbia un'annotazione non gestita:

KNV2009: inventory info is nil\n\nFor more information, see https://g.co/cloud/acm-errors#knv2009

Per risolvere il problema, prova i seguenti passaggi:

  1. Evita di configurare sincronizzazioni in cui tutte le risorse hanno l'annotazione configmanagement.gke.io/managed: disabled, assicurandoti che almeno una risorsa sia gestita da Config Sync.
  2. Aggiungi l'annotazione configmanagement.gke.io/managed: disabled solo dopo aver completato una sincronizzazione iniziale della risorsa senza questa annotazione.

Più modelli di oggetti di inventario

Se ricevi il seguente errore quando il reconciler tenta di applicare le configurazioni al cluster, è probabile che tu abbia una configurazione dell'inventario generata da kpt nella fonte di attendibilità, ad esempio un repository Git:

KNV2009: Package has multiple inventory object templates.  The package should have one and only one inventory object template.   For more information, see https://g.co/cloud/acm-errors#knv2009

Il problema si verifica perché Config Sync gestisce la propria configurazione dell'inventario. Per risolvere il problema, elimina la configurazione dell'inventario nella tua fonte di riferimento.

Impossibile apportare modifiche ai campi immutabili

Non puoi modificare un campo immutabile in una configurazione modificando il valore nella fonte di attendibilità. Il tentativo di apportare una modifica di questo tipo causa un errore simile al seguente:

KNV2009: failed to apply RESOURCE: admission webhook "deny-immutable-field-updates.cnrm.cloud.google.com" denied the request: cannot make changes to immutable field(s):

Se devi modificare un campo immutabile, elimina l'oggetto dalla fonte di verità, attendi che Config Sync lo elimini dal cluster, quindi ricrealo nella fonte di verità con gli aggiornamenti.

Polling per lo stato non riuscito

Puoi autorizzare Config Sync a gestire le risorse in un namespace utilizzando un oggetto RepoSync. Se questo tipo di oggetto RepoSync utilizza un oggetto RoleBinding che fa riferimento a un ClusterRole o Role personalizzato, potresti ricevere il seguente messaggio di errore dal deployment del Reconciler:

KNV2009: polling for status failed: unknown

Per risolvere il problema, assicurati che gli oggetti ClusterRole e Role dispongano almeno delle seguenti autorizzazioni per ogni risorsa gestita dall'oggetto RepoSync:

  • list
  • watch
  • get
  • patch
  • delete
  • create

Per istruzioni su come aggiungere queste autorizzazioni, consulta Crea un RoleBinding.

Rilevamento API non riuscito

Se visualizzi un messaggio di errore simile al seguente, potresti riscontrare un errore di rilevamento dell'API:

KNV2002: API discovery failed: APIServer error: unable to retrieve the complete list of server APIs: external.metrics.k8s.io/v1beta1: received empty response for: external.metrics.k8s.io/v1beta1

Config Sync utilizza il rilevamento dell'API Kubernetes per cercare le risorse supportate dal cluster. In questo modo, Config Sync può convalidare i tipi di risorse specificati nell'origine e monitorare le modifiche di queste risorse nel cluster.

Prima della versione 1.28 di Kubernetes, ogni volta che un backend APIService non era integro o restituiva un risultato di elenco vuoto, il rilevamento dell'API non andava a buon fine, causando errori di Config Sync e di molti altri componenti di Kubernetes. Molti backend APIService comuni non sono ad alta affidabilità, quindi questo può accadere con relativa frequenza, semplicemente aggiornando il backend o riprogrammandolo su un altro nodo.

Esempi di backend APIService con una singola replica includono metrics-server e custom-metrics-stackdriver-adapter. Alcuni backend APIService restituiscono sempre risultati di elenchi vuoti, come custom-metrics-stackdriver-adapter. Un'altra causa comune di errore di rilevamento dell'API sono i webhook non integri.

Dopo la versione 1.28 di Kubernetes, con la funzionalità Aggregated Discovery abilitata, un backend APIService non integro non causa più errori non gestiti. Invece, il gruppo di risorse gestito da quell'APIService viene mostrato senza risorse. In questo modo, la sincronizzazione continua, a condizione che la risorsa non integra non sia specificata nell'origine.

Riparazione automatica ritardata

La riparazione automatica monitora le risorse gestite, rileva la deviazione dalla fonte di attendibilità e la annulla.

La riparazione automatica viene messa in pausa durante il tentativo di sincronizzazione. Questo comportamento significa che la riparazione automatica potrebbe essere ritardata, soprattutto se sono presenti errori di sincronizzazione che impediscono il completamento del processo di riconciliazione. Per riattivare la riparazione automatica, correggi tutti gli errori di sincronizzazione segnalati.

Numero elevato di richieste API Kubernetes

Config Sync utilizza una strategia multi-istanza per scalare e isolare i tenant e i domini di errore. Per questo motivo, ogni RootSync e RepoSync riceve la propria istanza di riconciliatore. Oltre alla sincronizzazione ogni volta che vengono apportate modifiche all'origine, ogni istanza del reconciler si sincronizza periodicamente nell'ambito del suo comportamento di riparazione automatica, per annullare le modifiche non rilevate dalla correzione attiva della deviazione. Quando aggiungi oggetti RootSync o RepoSync, si verifica un aumento lineare del numero di richieste API effettuate dai reconciler che sincronizzano le risorse con Kubernetes. Pertanto, se hai molti oggetti RootSync e RepoSync, a volte questo può causare un carico di traffico significativo sull'API Kubernetes.

Per eseguire la sincronizzazione, Config Sync utilizza l'applicazione lato server. In questo modo, il normale flusso di richieste GET e PATCH viene sostituito con una singola richiesta PATCH, riducendo il numero totale di chiamate API, ma aumentando il numero di chiamate PATCH. In questo modo, le modifiche apportate sono corrette, anche se la versione del gruppo di risorse nell'origine non corrisponde alla versione predefinita del gruppo di risorse nel cluster. Tuttavia, potresti visualizzare richieste PATCH nell'audit log, anche se non sono state apportate modifiche all'origine o deviazioni dallo stato desiderato. Questo è normale, ma può sorprendere.

Se la sincronizzazione genera un errore, viene ripetuta fino a quando non va a buon fine. Tuttavia, se ciò richiede l'interazione umana, Config Sync potrebbe generare errori e riprovare per un po', aumentando il numero di richieste effettuate all'API Kubernetes. I nuovi tentativi vengono eseguiti con backoff esponenziale, ma se molti oggetti RootSync o RepoSync non riescono a sincronizzarsi contemporaneamente, ciò può causare un carico di traffico significativo sull'API Kubernetes.

Per mitigare questi problemi, prova una delle seguenti opzioni:

  • Correggi rapidamente gli errori di configurazione per evitare che si accumulino.
  • Combina più oggetti RootSync o RepoSync per ridurre il numero di riconciliatori che effettuano richieste API Kubernetes.

Disinstallazione di KubeVirt bloccata dai finalizzatori

KubeVirt è un pacchetto Kubernetes che utilizza più finalizzatori, richiedendo un ordine di eliminazione preciso per facilitare la pulizia. Se gli oggetti KubeVirt vengono eliminati nell'ordine sbagliato, l'eliminazione di altri oggetti KubeVirt potrebbe bloccarsi o smettere di rispondere a tempo indeterminato.

Se hai provato a disinstallare KubeVirt e l'operazione è stata bloccata, segui le istruzioni per eliminare KubeVirt manualmente.

Per mitigare questo problema in futuro, dichiara le dipendenze tra gli oggetti risorsa per assicurarti che vengano eliminati nell'ordine inverso della dipendenza.

Eliminazione degli oggetti bloccata dai finalizzatori

I finalizzatori Kubernetes sono voci di metadati che indicano a Kubernetes di non consentire la rimozione di un oggetto finché un controller specifico non ha eseguito la pulizia. Ciò può causare errori di sincronizzazione o riconciliazione se le condizioni per la pulizia non sono soddisfatte o se il controller che esegue la pulizia per la risorsa non è integro o è stato eliminato.

Per mitigare questo problema, identifica quale risorsa è ancora in fase di finalizzazione e quale controller deve eseguire la pulizia.

Se il controller non è integro, la correzione della causa principale dovrebbe consentire il completamento della pulizia delle risorse, sbloccando la rimozione dell'oggetto.

Se il controller è integro, dovrebbe aver applicato una condizione di stato all'oggetto in fase di eliminazione per spiegare il motivo per cui la pulizia è stata interrotta. In caso contrario, controlla i log del controller per individuare la causa principale.

Spesso, un oggetto bloccato in fase di eliminazione indica che gli oggetti sono stati eliminati nell'ordine sbagliato. Per evitare questo tipo di problema in futuro, dichiara le dipendenze tra gli oggetti risorsa, per assicurarti che vengano eliminati nell'ordine inverso della dipendenza.

I campi ResourceGroup continuano a cambiare

Quando viene tentata la sincronizzazione, l'inventario viene aggiornato per modificare lo stato della risorsa in In attesa. Se la sincronizzazione non va a buon fine, l'inventario viene aggiornato per modificare lo stato della risorsa in "Non riuscito". Quando la sincronizzazione viene riprovata dopo un errore, questo pattern si ripete, causando aggiornamenti periodici dell'inventario. In questo modo, il ResourceGroup resourceVersion aumenta a ogni aggiornamento e lo stato di sincronizzazione cambia continuamente. È normale, ma può sorprendere.

L'errore di sincronizzazione può essere causato da diversi problemi. Uno dei più comuni è la mancanza di autorizzazioni sufficienti per gestire le risorse specificate nell'origine. Per correggere questo errore, aggiungi le associazioni RoleBinding o ClusterRoleBinding appropriate per concedere al reconciler RepoSync o RootSync l'autorizzazione per gestire le risorse che non vengono sincronizzate.

Config Sync non rimuove né ripristina i campi non specificati nell'origine

Config Sync utilizza Server-Side Apply per applicare i manifest dall'origine a Kubernetes. Questo è necessario per consentire ad altri controller di gestire i campi metadata e spec. Un esempio è l'Horizontal Pod Autoscaler, che aggiorna il numero di repliche in un deployment. Per questo motivo, Config Sync gestisce solo i campi specificati nel manifest di origine. Questo ha l'effetto collaterale che, quando si adottano oggetti risorsa esistenti, i campi non specificati nell'origine non vengono modificati, il che a volte può causare una configurazione unita non valida o errata.

Per evitare questo problema durante l'adozione di una risorsa, utilizza esattamente gli stessi campi nell'origine durante l'adozione iniziale, quindi modifica i campi nell'origine dopo la sincronizzazione, in modo che Config Sync rimuova correttamente i campi applicati in precedenza e li sostituisca con i nuovi campi dell'origine. Un altro modo per evitare questo problema è eliminare prima la risorsa dal cluster e consentire a Config Sync di applicare la nuova versione.

Config Sync non conserva i campi dell'applicazione lato client kubectl quando adotta gli oggetti

Poiché Config Sync utilizza l'applicazione lato server, quando adotta un oggetto creato originariamente con l'applicazione lato client kubectl, annulla l'impostazione di tutti i campi impostati con l'applicazione lato client, ma non dichiarati nell'origine.

Se vuoi che questi campi vengano conservati, utilizza esattamente gli stessi campi nell'origine quando adotti inizialmente l'oggetto o crei l'oggetto utilizzando Server-Side Apply.

Passaggi successivi

  • Se i problemi persistono, controlla se il tuo problema è un problema noto.

Se non riesci a trovare una soluzione al tuo problema nella documentazione, consulta Richiedi assistenza per ulteriore aiuto, inclusi consigli sui seguenti argomenti: