Risolvere i problemi di sincronizzazione delle configurazioni con il cluster

Questa pagina spiega come risolvere i problemi relativi alla sincronizzazione delle configurazioni con il cluster.

Risolvere 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 è vietata

Poiché devi concedere gli oggetti RepoSync al loro RBAC, potrebbe 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 nomos status comando.

Se visualizzi i seguenti messaggi nello stato, 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 al account di servizio per il riconciliatore l'autorizzazione a gestire la risorsa non riuscita in quello 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, agli oggetti RootSync viene concesso il ruolo cluster-admin per impostazione predefinita.

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

Se ricevi il seguente errore quando un riconciliatore 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 dividere 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 attenuare il problema configurando RootSync o RepoSync in modo da disattivare temporaneamente la scrittura dello stato dell'oggetto in ResourceGroup. Per farlo, imposta 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 visualizzi alcun errore dall'oggetto RootSync o RepoSync, significa che gli oggetti della tua origine di verità 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 il comando seguente:

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

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

      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 visualizzi un errore simile al seguente, la risorsa ResourceGroup è troppo grande e supera il limite di dimensioni dell'oggetto etcd:

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

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

Timeout di riconciliazione dell'applicazione delle dipendenze

Se hai sincronizzato oggetti con dipendenze, potresti ricevere un errore simile al seguente esempio 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 significa 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 solo gli oggetti nell'ordine che preferisci. Puoi sostituire il timeout di riconciliazione predefinito con un tempo più lungo impostando spec.override.reconcileTimeout.

È anche possibile che la dipendenza venga riconciliata dopo il completamento del tentativo di sincronizzazione iniziale. In questo caso, la dipendenza deve essere rilevata come riconciliata al successivo tentativo di sincronizzazione, sbloccando l'applicazione di eventuali dipendenti. Quando ciò accade, l'errore potrebbe essere segnalato brevemente e poi rimosso. L'allungamento 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 riconciliatore tenta di applicare le configurazioni al cluster, è probabile che l'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 a seguire questi passaggi:

  1. Evita di configurare le 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 di inventario generata da kpt nell'origine di verità, 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 di inventario. Per risolvere il problema, elimina la configurazione dell'inventario nell'origine di verità.

Impossibile apportare modifiche ai campi immutabili

Non puoi modificare alcun campo immutabile in una configurazione modificando il valore nell'origine di verità. Se tenti di apportare una modifica di questo tipo, si verifica 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 dall'origine di verità, attendi che Config Sync elimini l'oggetto dal cluster e poi ricrea l'oggetto nell'origine di verità con gli aggiornamenti.

Polling per lo stato non riuscito

Puoi autorizzare Config Sync a gestire le risorse in uno spazio dei nomi 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 riconciliatore:

KNV2009: polling for status failed: unknown

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

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

Per istruzioni su come aggiungere queste autorizzazioni, vedi Creare 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 apportate a 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 riusciva, causando errori in Config Sync e in più componenti di Kubernetes. Molti backend APIService comuni non sono a elevata disponibilità, 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 elenco vuoto, come custom-metrics-stackdriver-adapter. Un'altra causa comune di errore di rilevamento dell'API sono gli webhook non integri.

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

Autoriparazione ritardata

L'autoriparazione monitora le risorse gestite, rileva la deviazione dall'origine di verità e la ripristina.

L'autoriparazione viene messa in pausa durante il tentativo di sincronizzazione. Questo comportamento significa che l'autoriparazione potrebbe essere ritardata, soprattutto se sono presenti errori di sincronizzazione che impediscono al riconciliatore di completare l'operazione. Per riattivare l'autoriparazione, correggi tutti gli errori di sincronizzazione segnalati.

Numero elevato di richieste API Kubernetes

Config Sync utilizza una strategia multi-istanza per scalare e isolare tenant e domini di errore. Per questo motivo, ogni RootSync e RepoSync ottiene la propria istanza di riconciliatore. Oltre a sincronizzare ogni volta che vengono apportate modifiche all'origine, ogni istanza di riconciliatore esegue anche la sincronizzazione periodicamente nell'ambito del suo comportamento di autoriparazione, per ripristinare eventuali modifiche perse dalla correzione della deviazione attiva. Quando aggiungi oggetti RootSync o RepoSync, il numero di richieste API effettuate dai riconciliatori che sincronizzano le risorse con Kubernetes aumenta in modo lineare. 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. Questo sostituisce il normale flusso di richieste GET e PATCH 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 quando la versione del gruppo di risorse nell'origine non corrisponde alla versione predefinita del gruppo di risorse nel cluster. Tuttavia, potresti visualizzare le richieste PATCH nel log di audit, anche se non sono state apportate modifiche all'origine o alla deviazione dallo stato desiderato. Questo è normale, ma può essere sorprendente.

Quando la sincronizzazione genera errori, viene ritentata fino al completamento. Tuttavia, se è necessaria l'interazione umana, Config Sync potrebbe generare errori e riprovare per un po' di tempo, aumentando la quantità di richieste effettuate all'API Kubernetes. I tentativi vengono eseguiti con un backoff esponenziale, ma se molti oggetti RootSync o RepoSync non riescono a sincronizzarsi contemporaneamente, questo può causare un carico di traffico significativo sull'API Kubernetes.

Per attenuare 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 riconciliatori che effettuano richieste API Kubernetes.

Disinstallazione di KubeVirt bloccata dai finalizzatori

KubeVirt è un pacchetto Kubernetes che utilizza più finalizzatori, che richiedono 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 manualmente KubeVirt.

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

Eliminazione dell'oggetto bloccata dai finalizzatori

I finalizzatori di 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. Questo può causare il mancato funzionamento della sincronizzazione o della 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 attenuare questo problema, identifica la risorsa che è ancora in fase di finalizzazione e il controller che deve eseguire la pulizia.

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

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

Spesso, un oggetto bloccato durante l'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 di 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. Quando la sincronizzazione non riesce, l'inventario viene aggiornato per modificare lo stato della risorsa in Non riuscita. Quando la sincronizzazione viene ritentata dopo un errore, questo pattern si ripete, causando aggiornamenti periodici dell'inventario. In questo modo, resourceVersion di ResourceGroup aumenta a ogni aggiornamento e lo stato di sincronizzazione cambia continuamente. Questo è normale, ma può essere sorprendente.

L'errore di sincronizzazione può essere causato da diversi problemi. Uno dei più comuni è l'insufficienza delle autorizzazioni per gestire le risorse specificate nell'origine. Per correggere questo errore, aggiungi i RoleBinding o ClusterRoleBinding appropriati per concedere al riconciliatore RepoSync o RootSync l'autorizzazione a gestire le risorse che non riescono a sincronizzarsi.

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

Config Sync uses l'applicazione lato server per applicare i manifest dall'origine a Kubernetes. Questa operazione è necessaria 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ò rendere non valida o errata la configurazione unita.

Per evitare questo problema quando adotti una risorsa, utilizza gli stessi campi nell'origine durante l'adozione iniziale e poi modificali 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 dall'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 gli stessi campi nell'origine quando adotti inizialmente l'oggetto oppure crealo utilizzando l'applicazione lato server.

Passaggi successivi

  • Se riscontri ancora problemi, controlla se il tuo problema è un problema noto.

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