Introduzione alla risoluzione dei problemi

Se riscontri difficoltà con Config Sync, questa pagina ti presenta alcuni strumenti e procedure comuni che possono aiutarti a identificare e risolvere i problemi che riscontri.

Esegui l'upgrade a una versione supportata

Valuta la possibilità di eseguire l'upgrade di Config Sync a una versione supportata. L'upgrade spesso risolve i problemi comuni e ti dà accesso alle funzionalità più recenti.

Utilizza lo strumento a riga di comando nomos

Lo strumento a riga di comando nomos fornisce informazioni essenziali sulla configurazione di Config Sync. I comandi descritti nelle sezioni seguenti sono particolarmente utili quando cerchi di determinare l'origine del problema o quando devi collaborare con l'assistenza clienti Google Cloud.

Visualizza lo stato di Config Sync

Il comando nomos status fornisce dati ed errori aggregati per aiutarti a capire cosa sta succedendo con l'installazione di Config Sync. Le seguenti informazioni sono disponibili con nomos status:

  • Stato dell'installazione per cluster
  • Errori di sincronizzazione (sia di lettura da Git sia di riconciliazione delle modifiche)

Crea una segnalazione di bug

Se hai un problema con Config Sync che richiede l'assistenza clienti Cloud Customer Care, puoi fornire loro informazioni di debug utili utilizzando il nomos bugreport comando.

Questo comando genera un file zip con timestamp contenente informazioni sul cluster Kubernetes impostato nel contesto kubectl. Il file contiene anche i log dei pod di Config Sync. Non contiene informazioni sulle risorse sincronizzate con Config Sync.

Visualizza la dashboard di panoramica

La dashboard di Config Sync fornisce una panoramica dello stato dei pacchetti gestiti da Config Sync e dello stato delle risorse in questi pacchetti. L'esplorazione di questa dashboard può aiutarti a ottenere una rapida panoramica dello stato dell'installazione di Config Sync e a scoprire eventuali pacchetti che presentano problemi.

  • Per accedere alla dashboard, nella Google Cloud console vai alla pagina Configurazione nella sezione Funzionalità:

    Vai a Configurazione

Utilizza il monitoraggio e l'analisi dei log

Il monitoraggio di Config Sync e l'esplorazione dei relativi log possono aiutarti a determinare l'origine dei bug e a comprendere meglio eventuali comportamenti imprevisti.

Comprendi le metriche di Config Sync

Utilizza le metriche di Config Sync per ottenere visibilità sull'integrità di Config Sync.

Monitoraggio di oggetti RootSync e RepoSync

Quando installi Config Sync utilizzando la Google Cloud console o Google Cloud CLI, Config Sync crea automaticamente un oggetto RootSync per te. Quando Configura la sincronizzazione da più repository, puoi creare RepoSync oggetti che contengono informazioni di configurazione sui repository dello spazio dei nomi.

Il monitoraggio di questi oggetti può rivelare informazioni preziose sullo stato di Config Sync. Per saperne di più, vedi Monitoraggio di oggetti RootSync e RepoSync.

Utilizza gli indicatori del livello del servizio (SLI)

Per ricevere notifiche quando Config Sync non funziona come previsto, utilizza gli SLI di Config Sync.

Esegui query sui log

Puoi utilizzare Esplora log per recuperare, visualizzare e analizzare i dati dei log per Config Sync. Questi log possono contenere dati storici preziosi che non vengono acquisiti da nomos bugreport quando i pod dell'operatore o del riconciliatore vengono riavviati. Per esempi di query che potrebbero aiutarti a diagnosticare il problema, vedi Eseguire query sui log di Config Sync.

Esamina le risorse con lo strumento a riga di comando kubectl

Config Sync è composto da più risorse personalizzate su cui puoi eseguire query utilizzando i comandi kubectl. Questi comandi ti aiutano a comprendere lo stato di ciascuno degli oggetti di Config Sync.

Devi conoscere le seguenti informazioni sulle risorse Kubernetes gestite da Config Sync:

  • config-management-system è lo spazio dei nomi che utilizziamo per eseguire tutti i componenti di sistema principali di Config Sync.
  • configmanagement.gke.io e configsync.gke.io sono i gruppi API che utilizziamo per tutte le risorse personalizzate.

Esempi

Le sezioni seguenti mostrano come utilizzare i comandi kubectl per esaminare Config Sync.

Elenca le risorse personalizzate

  • Puoi ottenere un elenco completo delle risorse personalizzate eseguendo il seguente comando:

    kubectl api-resources | grep -E "configmanagement.gke.io|configsync.gke.io"

  • Le singole risorse personalizzate possono essere utilizzate eseguendo il seguente comando:

    kubectl get RESOURCE -o yaml.

    Sostituisci RESOURCE con il nome della risorsa su cui vuoi eseguire la query.

    Ad esempio, l'output del seguente comando ti consente di controllare lo stato di un oggetto RootSync:

    kubectl get rootsync -n config-management-system -o yaml

Controlla l'annotazione del token di un oggetto

Potresti voler sapere quando un oggetto Kubernetes gestito è stato aggiornato l'ultima volta da Config Sync. Ogni oggetto gestito viene annotato con l'hash del commit Git quando è stato modificato l'ultima volta e il percorso della configurazione che conteneva la modifica.

Ad esempio, per ottenere l'annotazione di un ClusterRoleBinding denominato namespace-readers, esegui il seguente comando:

kubectl get clusterrolebinding namespace-readers

L'output è simile al seguente:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  annotations:
    configmanagement.gke.io/source-path: cluster/namespace-reader-clusterrolebinding.yaml
    configmanagement.gke.io/token: bbb6a1e2f3db692b17201da028daff0d38797771
  name: namespace-readers
...

Per saperne di più, vedi Etichette e annotazioni.

Accelera la diagnosi con Gemini Cloud Assist

A volte, la causa del problema non è immediatamente ovvia, anche dopo aver utilizzato gli strumenti descritti nelle sezioni precedenti. L'analisi di casi complessi può richiedere molto tempo e competenze approfondite. Per scenari come questo, Gemini Cloud Assist può essere d'aiuto. Può rilevare automaticamente pattern nascosti, anomalie di superficie e fornire riepiloghi per aiutarti a individuare rapidamente una causa probabile.

Accedi a Gemini Cloud Assist

Per accedere a Gemini Cloud Assist, completa i seguenti passaggi:

  1. Nella Google Cloud console, vai a qualsiasi pagina.

  2. Nella Google Cloud barra degli strumenti della console, fai clic Apri o chiudi la chat di Gemini Cloud Assist.

    Si apre il riquadro Cloud Assist. Puoi fare clic sui prompt di esempio se vengono visualizzati oppure puoi inserire un prompt nel campo Inserisci un prompt.

Esplora i prompt di esempio

Per aiutarti a capire come Gemini Cloud Assist può aiutarti, ecco alcuni prompt di esempio:

Tema Scenario Prompt di esempio In che modo Gemini Cloud Assist può aiutarti
Configurazione iniziale Un ingegnere della piattaforma sta configurando Config Sync per la prima volta in modo da poter gestire i cluster GKE da un repository Git. Come faccio a configurare Config Sync per sincronizzare i manifest dal mio repository GitHub al mio cluster GKE? Gemini Cloud Assist fornisce una guida passo passo per la configurazione di Config Sync, che include la registrazione del parco risorse e l'abilitazione della funzionalità, e spiega dettagli come l'URL del repository, il ramo, il percorso e i metodi di autenticazione (ad esempio, public, token o ssh).
Risoluzione dei problemi relativi agli errori di sincronizzazione Uno sviluppatore esegue il commit di un nuovo manifest, ma la risorsa non viene applicata al cluster e lo stato della sincronizzazione mostra un codice di errore. Il mio oggetto RootSync di Config Sync mostra "KNV2009: the server could not find the requested resource". Cosa significa e come posso risolvere il problema? Gemini Cloud Assist analizza il codice di errore, spiegando che in genere indica che Config Sync non riesce a individuare o interagire con una risorsa Kubernetes prevista. Poi descrive le cause comuni, tra cui autorizzazioni RBAC mancanti, superamento dei limiti di dimensione degli oggetti risorsa, percorsi di directory errati, conflitti di inventario esterni e problemi con le risorse non gestite, fornendo passaggi specifici per la risoluzione dei problemi per ogni causa.
Gestione di più team Un'organizzazione deve consentire ai team di applicazioni di gestire le proprie configurazioni in spazi dei nomi specifici senza concedere loro l'accesso al repository della piattaforma centrale. Qual è la differenza tra un oggetto RootSync e un oggetto RepoSync in Config Sync? Quando devo utilizzare RepoSync?

Gemini Cloud Assist spiega la differenza principale tra gli oggetti RootSync e RepoSync: gli oggetti RootSync sono con ambito cluster e in genere vengono utilizzati dagli amministratori per le configurazioni a livello di cluster, mentre gli oggetti RepoSync sono con ambito spazio dei nomi e sono progettati per consentire ai team di applicazioni di gestire le risorse all'interno di uno spazio dei nomi specifico, promuovendo la delega e la multi-tenancy.

Gemini Cloud Assist descrive anche gli scenari in cui devono essere utilizzati gli oggetti RepoSync, sottolineando i vantaggi per la multi-tenancy e la riduzione dell'area interessata dalle configurazioni errate.
Convalida proattiva Uno sviluppatore vuole assicurarsi che il nuovo manifest sia valido prima di eseguirne il commit nel repository per evitare di interrompere la sincronizzazione in produzione. Come faccio a controllare i manifest Kubernetes per verificare la presenza di errori di Config Sync sulla mia macchina locale prima di eseguirne il push nel repository Git? Gemini Cloud Assist spiega come controllare i manifest Kubernetes per verificare la presenza di errori di Config Sync utilizzando lo strumento a riga di comando nomos. Descrive come utilizzare il comando nomos vet per la convalida della sintassi e il comando nomos hydrate per visualizzare l'anteprima delle configurazioni sottoposte a rendering da Kustomize o Helm. Gemini Cloud Assist descrive anche un flusso di lavoro consigliato per integrare questi controlli prima di eseguire il push in Git.

Per maggiori informazioni, consulta le seguenti risorse:

Utilizza le indagini di Gemini Cloud Assist

Oltre alla chat interattiva, Gemini Cloud Assist può eseguire analisi più approfondite e automatizzate tramite le indagini di Gemini Cloud Assist. Questa funzionalità è integrata direttamente nei flussi di lavoro come Esplora log ed è un potente strumento di analisi delle cause principali.

Quando avvii un'indagine da un errore o da una risorsa specifica, Gemini Cloud Assist analizza log, configurazioni e metriche. Utilizza questi dati per produrre osservazioni e ipotesi classificate sulle cause principali probabili, quindi ti fornisce i passaggi successivi consigliati. Puoi anche trasferire questi risultati a una Google Cloud richiesta di assistenza per fornire un contesto prezioso che può aiutarti a risolvere il problema più rapidamente.

Per saperne di più, vedi Indagini di Gemini Cloud Assist nella documentazione di Gemini.

Leggi la documentazione aggiuntiva per la risoluzione dei problemi

Se continui a riscontrare problemi, le seguenti risorse potrebbero essere utili:

  • Se hai ricevuto un messaggio di errore, consulta la pagina di riferimento degli errori per ricevere consigli su come risolvere l' errore.

  • Controlla se il problema che stai riscontrando è causato da un problema noto.

  • Se hai difficoltà con un'area specifica, una delle guide mirate per la risoluzione dei problemi elencate nella sezione Risoluzione dei problemi per tipo di problema del sommario potrebbe essere d'aiuto.

Passaggi successivi

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