Risolvi 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 seguenti sezioni spiegano alcune delle cause più comuni e come risolverle.

L'operazione su determinate risorse è vietata

Poiché devi concedere a RepoSync oggetti il suo RBAC, potrebbe non disporre delle autorizzazioni necessarie per applicare le risorse.

Puoi verificare che manchino le autorizzazioni 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 viene visualizzato il seguente messaggio, significa che il responsabile della riconciliazione 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 l'account di servizio per l'autorizzazione del riconciliatore per gestire la risorsa non riuscita in quello spazio dei nomi. I dettagli su come aggiungere una risorsa 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 imposti questo campo, a RootSync oggetti 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 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 eseguire l'interruzione del repository Git in quanto l'oggetto è già troppo grande e le modifiche non vengono applicate, puoi ridurlo configurando RootSync o RepoSync per disabilitare 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 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 o gcloud alpha anthos config sync.

Se non visualizzi alcun errore dall'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 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 per il 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 dimensione dell'oggetto etcd:

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

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

Timeout di riconciliazione dell'applicazione della dipendenza

Se stavi sincronizzando 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 delle dipendenze 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 impostandolo su 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 dovrebbe essere rilevata come riconciliata al successivo tentativo di nuovo tentativo di sincronizzazione, sbloccando l'applicazione di tutti i dipendenti. In questi casi, l'errore può essere segnalato brevemente e poi rimosso. Prolungando il timeout di riconciliazione potresti evitare che l'errore venga segnalato a intermittenza.

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 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 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 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 origine di riferimento.

Impossibile apportare modifiche ai campi immutabili

Non puoi modificare alcun campo immutabile in una configurazione cambiando il valore nell'origine attendibile. Il tentativo di apportare questa modifica 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 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 sia verificato 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 rilevare eventuali modifiche al cluster.

Prima della versione 1.28 di Kubernetes, ogni volta che un backend di APIService non era integro o restituiva un risultato elenco vuoto, l'API Discovery non andava a buon fine, causando un errore di Config Sync e di diversi altri componenti Kubernetes. Molti backend APIService comuni non sono ad alta disponibilità e questo può accadere relativamente di frequente, semplicemente aggiornando il backend o ripianificandolo 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 dell'errore di rilevamento dell'API sono i webhook non integri.

Dopo Kubernetes versione 1.28, con la funzionalità Aggregated Discovery abilitata, un backend APIService non integro non causa più errori non gestiti. Al contrario, si vede che il gruppo di risorse gestito da APIService non ha risorse. Ciò consente di continuare la sincronizzazione, purché la risorsa non integro non sia specificata nell'origine.

Riparazione automatica ritardata

La riparazione automatica monitora le risorse gestite, rileva le deviazioni dalla fonte della verità e annullale.

La riparazione automatica è in pausa durante il tentativo di sincronizzazione. Questo comportamento indica che la riparazione automatica potrebbe subire ritardi, in particolare se si verificano 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 di multi-instancing per scalare e isolare i tenant e i domini di errore. Per questo motivo, ogni elemento RootSync e RepoSync riceve la propria istanza di riconciliazione. Oltre alla sincronizzazione ogni volta che vengono apportate modifiche all'origine, ogni istanza del riconciliatore si sincronizza periodicamente nell'ambito del proprio comportamento di riparazione automatica, per annullare eventuali modifiche non rilevate dalla correzione attiva delle deviazioni. L'aggiunta di oggetti RootSync o RepoSync comporta 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, ciò a volte può causare un carico di traffico significativo sull'API Kubernetes.

Per eseguire la sincronizzazione, Config Sync utilizza 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. Ciò garantisce che le modifiche apportate siano corrette, anche se la versione del gruppo di risorse nell'origine non corrisponde alla versione predefinita del gruppo di risorse nel cluster. Tuttavia, potresti vedere le richieste PATCH nell'audit log, anche se non sono state apportate modifiche all'origine o deviazioni dallo stato desiderato. Questo è normale, ma può sorprendere.

Quando la sincronizzazione restituisce un errore, viene tentata un'altra volta finché l'operazione non va a buon fine. Tuttavia, se questo richiede l'interazione umana, Config Sync potrebbe restituire un errore e riprovare per un po' di tempo, aumentando il numero di richieste inviate all'API Kubernetes. I nuovi tentativi vengono restituiti in modo esponenziale, ma se molti oggetti RootSync o RepoSync non vengono sincronizzati contemporaneamente, ciò può causare un carico di traffico significativo sull'API Kubernetes.

Per limitare questi problemi, prova una delle seguenti opzioni:

  • Puoi correggere 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 ed è stato bloccato, segui le istruzioni per l'eliminazione manuale di KubeVirt.

Per mitigare questo problema in futuro, dichiara le dipendenze tra gli oggetti delle risorse per assicurarti che vengano eliminate in ordine inverso delle dipendenze.

Eliminazione degli oggetti bloccata dai finalizzatori

I finalisti di Kubernetes sono voci di 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 un errore 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 ridurre questo problema, identifica la risorsa ancora in fase di finalizzazione e il controller che dovrebbe eseguire la pulizia.

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

Se il controller è integro, deve aver applicato una condizione di stato all'oggetto in corso di eliminazione per spiegare il motivo per cui la pulizia si è bloccata. In caso contrario, controlla i log del controller per trovare indicazioni della 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 delle risorse e assicurati che vengano eliminate in ordine inverso delle dipendenze.

I campi ResourceGroup continuano a essere modificati

Quando viene tentato di sincronizzazione, l'inventario viene aggiornato in modo da modificare lo stato della risorsa in In attesa. Quando la sincronizzazione non riesce, l'inventario viene aggiornato in modo da cambiare lo stato della risorsa in Non riuscita. Quando si ripete la sincronizzazione dopo l'errore, questo pattern si ripete, causando aggiornamenti periodici dell'inventario. In questo modo il gruppo di risorse resourceVersion aumenta a ogni aggiornamento e lo stato di sincronizzazione continua a cambiare. È normale, ma può sorprenderti.

L'errore di sincronizzazione può essere causato da diversi problemi. Uno dei più comuni è le autorizzazioni insufficienti per gestire le risorse specificate nell'origine. Per correggere questo errore, aggiungi i ruoli RoleBinding o ClusterRoleBinding appropriati per concedere l'autorizzazione di riconciliazione RepoSync o RootSync per gestire le risorse che non vengono sincronizzate.

L'applicazione lato server non rimuove né ripristina i campi non specificati nell'origine

Config Sync utilizza 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 è 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. Di conseguenza, quando si adottano oggetti risorse esistenti, i campi non specificati nell'origine non vengono modificati e, di conseguenza, la configurazione unita potrebbe risultare non valida o errata.

Per evitare questo problema quando adotti una risorsa, utilizza gli stessi stessi campi nell'origine quando lo utilizzi per la prima volta e poi 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 il tuo problema è un problema noto.