Risolvere i problemi di sincronizzazione delle configurazioni con il cluster

Questa pagina mostra come risolvere i problemi di sincronizzazione delle configurazioni con il cluster.

Risolvere gli errori di 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 è vietata

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

Puoi verificare che le autorizzazioni manchino 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 riconciliatore 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 all'account di servizio per il riconciliatore l'autorizzazione per gestire la risorsa non riuscita nel relativo spazio dei nomi. I dettagli su come aggiungere un RoleBinding sono inclusi in Configurare 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, per impostazione predefinita agli oggetti RootSync viene assegnato il ruolo cluster-admin.

L'oggetto ResourceGroup supera il limite di dimensioni di etcd

Se ricevi il seguente errore quando un riconciliatore tenta di applicare le configurazioni al cluster, l'oggetto ResourceGroup supera il limite di dimensione 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 conservate, puoi mitigare il problema configurando RootSync o RepoSync per disattivare temporaneamente la scrittura dello stato dell'oggetto nel ResourceGroup. Puoi farlo impostando il campo .spec.override.statusMode dell'oggetto RootSync o RepoSync su disabled. In questo modo, Config Sync smette di aggiornare lo 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 o gcloud alpha anthos config sync.

Se non visualizzi alcun errore nell'oggetto RootSync o RepoSync, significa che gli oggetti della tua origine attendibile sono stati sincronizzati con il cluster. Per verificare se la risorsa ResourceGroup supera il limite di dimensione dell'oggetto etcd, controlla sia lo stato della risorsa ResourceGroup sia il log del controller ResourceGroup:

1. Controlla lo stato del gruppo di risorse:

   • Per controllare l'oggetto RootSync, esegui il seguente comando:

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

   • Per controllare l'oggetto RepoSync, esegui il seguente 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 esempio:

   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 gruppo di risorse diventi troppo grande, riduci il numero di risorse nel tuo repository Git. Puoi suddividere un repository principale in più repository principali.

Timeout di riconciliazione dell'applicazione delle dipendenze

Se stavi sincronizzando oggetti con dipendenze, potresti ricevere un errore simile all'esempio seguente quando il riconciliatore tenta di applicare gli 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 ricognizione 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 sostituire il timeout di riconciliazione predefinito con un valore più lungo impostando spec.override.reconcileTimeout.

È anche possibile che la dipendenza venga riconciliata al termine del tentativo di sincronizzazione iniziale. In questo caso, la dipendenza dovrebbe essere rilevata come riconciliata al successivo tentativo di ripetizione della sincronizzazione, sbloccando l'applicazione di eventuali elementi dipendenti. In questi casi, l'errore potrebbe essere segnalato brevemente e poi rimosso. Allungare il 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 riconciliatore tenta di applicare le configurazioni al cluster, è probabile che il tuo inventario non abbia risorse o che il manifest contenga 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 a procedere nel seguente modo:

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 riconciliatore tenta di applicare le configurazioni al cluster, è probabile che tu abbia una configurazione dell'inventario generata da kpt nella fonte attendibile, 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 attendibile.

Impossibile apportare modifiche ai campi immutabili

Non puoi modificare un campo immutabile in una configurazione modificando il valore nella verità. Il tentativo di apportare una modifica di questo tipo genera 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 aggiornare un campo immutabile, elimina manualmente l'oggetto nel cluster. Config Sync può quindi ricreare l'oggetto con il nuovo valore del campo.

Rilevamento dell'API non riuscito

Se viene visualizzato un messaggio di errore simile al seguente, è possibile che si tratti di 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 rivelamento dell'API Kubernetes per cercare le risorse supportate dal cluster. In questo modo, Config Sync convalida i tipi di risorse specificati nell'origine e controlla se sono presenti modifiche in queste risorse nel cluster.

Prima della versione 1.28 di Kubernetes, ogni volta che il backend di APIService non era in stato di salute o restituiva un risultato di elenco vuoto, la scoperta dell'API non andava a buon fine, causando errori in Config Sync e in molti altri componenti di Kubernetes. Molti backend APIService comuni non sono altamente disponibili, quindi questo può accadere relativamente spesso, semplicemente aggiornando il backend o riprogrammandolo su un altro nodo.

Alcuni esempi di backend APIService con una singola replica sono metrics-server e custom-metrics-stackdriver-adapter. Alcuni backend di APIService restituiscono sempre risultati di elenchi vuoti, come custom-metrics-stackdriver-adapter. Un'altra causa comune di errore di rilevamento dell'API è rappresentata da webhook non funzionanti.

Dopo la versione 1.28 di Kubernetes, con la funzionalità di ricerca aggregata abilitata, un backend APIService non valido non causa più errori non gestiti. Al contrario, il gruppo di risorse gestito da APIService non ha risorse. In questo modo, la sincronizzazione continua, a condizione che la risorsa non funzionante non sia specificata nell'origine.

Nota: la funzionalità di rilevamento aggregato è stata aggiunta come funzionalità beta nella versione Kubernetes 1.27.0, ma un bug ne ha causato la disattivazione nella versione GKE 1.27.4-gke.1600. È stato riattivato nella versione GKE 1.28.0 con una correzione.

Riparazione automatica ritardata

La riparazione automatica controlla le risorse gestite, rileva la deviazione dall'origine della verità e la ripristina.

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

Numero elevato di richieste API Kubernetes

Config Sync utilizza una strategia di istanze multiple per scalare e isolare i tenant e i domini di errore. Per questo motivo, ogni RootSync e RepoSync ha la propria istanza di Mediator. Oltre a sincronizzarsi ogni volta che vengono apportate modifiche all'origine, ogni istanza di riconciliatore si sincronizza periodicamente nell'ambito del proprio comportamento di riparazione automatica per ripristinare eventuali modifiche non rilevate dalla correzione della deriva attiva. L'aggiunta di oggetti RootSync o RepoSync provoca un aumento lineare del numero di richieste API effettuate dai riconciliatori 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 la funzionalità Applicazione lato server. In questo modo, il normale flusso di richieste GET e PATCH viene sostituito da 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 è stata apportata alcuna modifica alla sorgente o non è stato registrato alcun allontanamento dallo stato desiderato. È normale, ma può sorprenderti.

Quando la sincronizzazione genera un errore, viene riprovata fino a quando non va a buon fine. Tuttavia, se questo richiede l'interazione umana, Config Sync potrebbe generare errori e riprovare per un po' di tempo, aumentando il numero di richieste all'API Kubernetes. I tentativi di nuovo si riducono in modo esponenziale, ma se la sincronizzazione di molti oggetti RootSync o RepoSync non riesce contemporaneamente, ciò può causare un carico di traffico significativo sull'API Kubernetes.

Per ridurre al minimo questi problemi, prova una delle seguenti opzioni:

• Correggi rapidamente gli errori di configurazione in modo che non si accumulino.
• Combina più oggetti RootSync o RepoSync per ridurre il numero di agenti di riconciliazione che inviano richieste all'API Kubernetes.

La disinstallazione di KubeVirt è bloccata dai finalizzatori

KubeVirt è un pacchetto Kubernetes che utilizza più finalizzatori e richiede 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 si è bloccato, segui le istruzioni per eliminare KubeVirt manualmente.

Per ridurre il problema in futuro, dichiara le dipendenze tra gli oggetti della risorsa per assicurarti che vengano eliminati nell'ordine inverso delle dipendenze.

Eliminazione degli oggetti bloccata dai finalizzatori

I finalizer Kubernetes sono voci dei metadati che indicano a Kubernetes di non consentire la rimozione di un oggetto fino a quando un controller specifico non ha eseguito la pulizia. Ciò può causare il fallimento della sincronizzazione o della riconciliazione se le condizioni per la pulizia non sono soddisfatte o se il controller che esegue la pulizia della risorsa non è in stato operativo o è stato eliminato.

Per risolvere il problema, identifica la risorsa che è ancora in fase di finalizzazione e il controllore che deve eseguire la pulizia.

Se il controller non è in stato di esecuzione, la correzione della causa principale dovrebbe consentire il completamento del cleanup della risorsa, sbloccando la rimozione dell'oggetto.

Se il controller è in stato di esecuzione, deve aver applicato una condizione di stato all'oggetto da eliminare per spiegare il motivo dell'interruzione della pulizia. In caso contrario, controlla i log del controller per individuare la causa principale.

Spesso, l'impossibilità di eliminare un oggetto è un'indicazione del fatto che gli oggetti sono stati eliminati nell'ordine sbagliato. Per evitare questo tipo di problemi in futuro, dichiara le dipendenze tra gli oggetti della risorsa, per assicurarti che vengano eliminati nell'ordine inverso della dipendenza.

I campi ResourceGroup continuano a cambiare

Quando si tenta la sincronizzazione, l'inventario viene aggiornato per modificare lo stato della risorsa in In attesa. Quando la sincronizzazione non va a buon fine, l'inventario viene aggiornato in modo da modificare lo stato della risorsa in Non riuscito. Quando viene eseguito un nuovo tentativo di sincronizzazione dopo un errore, questo schema si ripete, provocando aggiornamenti periodici dell'inventario. Di conseguenza, ResourceGroupresourceVersion aumenta a ogni aggiornamento e lo stato di sincronizzazione oscilla. È normale, ma può sorprenderti.

L'errore di sincronizzazione può essere causato da diversi problemi. Uno dei problemi più comuni è rappresentato dalle autorizzazioni insufficienti per gestire le risorse specificate nell'origine. Per risolvere questo errore, aggiungi le associazioni RoleBinding o ClusterRoleBinding appropriate per concedere all'agente di riconciliazione RepoSync o RootSync l'autorizzazione per gestire le risorse di cui non riesce a eseguire la sincronizzazione.

L'applicazione lato server 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 di questo è 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 di risorse esistenti, i campi non specificati nell'origine non vengono modificati, il che a volte può causare l'invalidità o l'errore della configurazione unita.

Per evitare questo problema durante l'adozione di una risorsa, utilizza gli stessi campi esatti 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.

Passaggi successivi

• Se i problemi persistono, controlla se si tratta di un problema noto.