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 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 controllo dell'accesso basato sui ruoli agli oggetti RepoSync, potrebbero mancare le autorizzazioni necessarie per applicare le risorse.

Puoi verificare che le autorizzazioni non siano presenti ottenendo 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 alaccount di serviziot per il riconciliatore l'autorizzazione per 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 viene visualizzato 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 risolvere 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 visualizzi alcun errore dall'oggetto RootSync o RepoSync, significa che gli oggetti della tua fonte attendibile 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 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 al seguente esempio, 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 sincronizzavi oggetti con dipendenze, potresti ricevere un errore simile al seguente esempio quando il riconciliatore 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 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 periodo di 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 dovrebbe essere rilevata come riconciliata al successivo tentativo di sincronizzazione, sbloccando l'applicazione di eventuali elementi dipendenti. In questi casi, 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.

Inventory info is nil

Se ricevi il seguente errore quando il riconciliatore tenta di applicare le configurazioni al cluster, è probabile che il tuo inventario non contenga 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 alcun campo immutabile in una configurazione modificando il valore nell'origine attendibile. 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 tua origine attendibile, attendi che Config Sync lo elimini dal cluster e poi ricrealo nell'origine attendibile 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 di 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, vedi Creare un RoleBinding.

Rilevamento API non riuscito

Se viene visualizzato 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 convalida i tipi di risorse specificati nell'origine e monitora 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 elenco vuoto, il rilevamento API non riusciva, causando errori in Config Sync e in molti altri componenti di Kubernetes. Molti backend APIService comuni non sono a disponibilità elevata, 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. Il gruppo di risorse gestito da APIService viene visualizzato senza risorse. In questo modo la sincronizzazione può continuare, a condizione che la risorsa non integra non sia specificata nell'origine.

Riparazione automatica ritardata

La funzionalità di autoriparazione monitora le risorse gestite, rileva la deviazione dalla fonte attendibile e la ripristina.

L'autoriparazione viene sospesa durante il tentativo di sincronizzazione. Questo comportamento significa che l'autoriparazione potrebbe essere ritardata, soprattutto se si verificano 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 i tenant e i domini di errore. Per questo motivo, ogni RootSync e RepoSync ha la propria istanza di riconciliazione. Oltre alla sincronizzazione ogni volta che vengono apportate modifiche all'origine, ogni istanza di riconciliazione si sincronizza periodicamente nell'ambito del suo comportamento di auto-ripristino, per ripristinare le modifiche perse dalla correzione della deriva attiva. Quando aggiungi oggetti RootSync o RepoSync, si verifica 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 Server-Side Apply. 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 quando la versione del gruppo di risorse nell'origine non corrisponde alla versione predefinita del gruppo di risorse nel cluster. Tuttavia, potresti visualizzare richieste PATCH nel log di controllo, anche quando non sono state apportate modifiche all'origine o non si è verificato uno scostamento dallo stato desiderato. È normale, ma può sorprendere.

Quando la sincronizzazione genera errori, viene eseguita di nuovo finché non va a buon fine. Tuttavia, se ciò richiede l'interazione umana, Config Sync potrebbe generare errori e riprovare per un po' di tempo, aumentando il numero di richieste effettuate all'API Kubernetes. I 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 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 finalizer

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 tentato di disinstallare KubeVirt e l'operazione è stata bloccata, segui le istruzioni per eliminare KubeVirt manualmente.

Per risolvere questo problema in futuro, dichiara le dipendenze tra gli oggetti risorsa per assicurarti che vengano eliminati in 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. 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 risolvere il problema, identifica la risorsa in fase di finalizzazione e il controller che deve eseguire la pulizia.

Se il controller non è integro, la risoluzione 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 perché la pulizia è bloccata. In caso contrario, controlla i log del controller per individuare la causa principale.

Spesso, il blocco dell'eliminazione di un oggetto 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 in ordine inverso di dipendenza.

I campi ResourceGroup cambiano continuamente

Quando viene tentata 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 per modificare lo stato della risorsa in "Non riuscito". Quando la sincronizzazione viene ritentata dopo l'errore, questo pattern si ripete, causando aggiornamenti periodici dell'inventario. In questo modo, 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 motivi più comuni è l'autorizzazione insufficiente per gestire le risorse specificate nell'origine. Per correggere questo errore, aggiungi le associazioni RoleBinding o ClusterRoleBinding appropriate per concedere all'agente di riconciliazione RepoSync o RootSync l'autorizzazione a 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 è Horizontal Pod Autoscaler, che aggiorna il numero di repliche in un deployment. Per questo motivo, Config Sync gestisce solo i campi specificati nel manifest dell'origine. Ciò 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 l'invalidità o l'erroneità della configurazione unita.

Per evitare questo problema quando adotti una risorsa, utilizza esattamente gli stessi campi nell'origine durante l'adozione iniziale, 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 di 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 crea l'oggetto utilizzando Server-Side Apply.

Passaggi successivi