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 consente di accedere alle funzionalità più recenti.

Utilizzare 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 coassistenza clienti Google Cloudre.

Visualizzare lo stato di Config Sync

Il comando nomos status fornisce dati e 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 durante la lettura da Git sia durante la riconciliazione delle modifiche)

Creare una segnalazione di bug

Se hai un problema con Config Sync che richiede l'aiuto dell'assistenza clienti Google Cloud, puoi fornire informazioni di debug preziose utilizzando il comando nomos bugreport.

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 Config Sync. Non contiene informazioni dalle risorse sincronizzate con Config Sync.

Visualizzare la dashboard di panoramica

La dashboard 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 console Google Cloud vai alla pagina Config nella sezione Funzionalità:

    Vai a Configurazione

Utilizzare 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 qualsiasi comportamento imprevisto.

Comprendere 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 console Google Cloud o Google Cloud CLI, Config Sync crea automaticamente un oggetto RootSync per te. Quando configuri la sincronizzazione da più repository, puoi creare oggetti RepoSync che contengono informazioni di configurazione sui repository di spazi 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.

Utilizzare gli indicatori del livello del servizio (SLI)

Per ricevere notifiche quando Config Sync non funziona come previsto, utilizza gli indicatori di livello del servizio (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, consulta 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 che puoi interrogare 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 di API che utilizziamo per tutte le risorse personalizzate.

Esempi

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

Elenca risorse personalizzate

  • Per ottenere un elenco completo delle risorse personalizzate, esegui 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

Controllare 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 è 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ù, consulta Etichette e annotazioni.

Accelerare 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'indagine su casi complessi può richiedere molto tempo e competenze approfondite. Per scenari come questo, Gemini Cloud Assist può aiutarti. Può rilevare automaticamente pattern nascosti, anomalie di superficie e fornire riepiloghi per aiutarti a individuare rapidamente una causa probabile.

Accedere a Gemini Cloud Assist

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

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

  2. Nella barra degli strumenti della console Google Cloud , fai clic su 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ò esserti utile, ecco alcuni esempi di prompt:

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 illustra la registrazione del parco risorse e l'attivazione della funzionalità e spiega dettagli come URL del repository, ramo, percorso e 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 di sincronizzazione mostra un codice di errore. Il mio oggetto Config Sync RootSync mostra "KNV2009: the server could not find the requested resource". Che cosa significa e come posso risolvere il problema? Gemini Cloud Assist analizza il codice di errore e spiega che in genere indica che Config Sync non riesce a individuare o interagire con una risorsa Kubernetes prevista. Vengono poi descritte 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 ciascuna causa.
Gestire 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 progettati per i team di applicazioni per gestire le risorse all'interno di uno spazio dei nomi specifico, promuovendo la delega e la multitenancy.

Gemini Cloud Assist descrive anche gli scenari in cui devono essere utilizzati gli oggetti RepoSync, sottolineando i vantaggi per il multi-tenancy e riducendo l'area interessata da errori di configurazione.
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 posso controllare i miei manifest Kubernetes per rilevare 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 rilevare errori di Config Sync utilizzando lo strumento a riga di comando nomos. Viene descritto in dettaglio 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 delinea anche un workflow consigliato per integrare questi controlli prima di eseguire il push su Git.

Per maggiori informazioni, consulta le seguenti risorse:

Utilizzare 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 in 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 probabili cause principali, quindi ti fornisce i passaggi successivi consigliati. Puoi anche trasferire questi risultati a una richiesta di assistenza Google Cloud per fornire un contesto prezioso che può aiutarti a risolvere il problema più rapidamente.

Per saperne di più, consulta la sezione Indagini di Gemini Cloud Assist nella documentazione di Gemini.

Leggi la documentazione aggiuntiva per la risoluzione dei problemi

Se i problemi persistono, le seguenti risorse potrebbero esserti utili:

  • Se hai ricevuto un messaggio di errore, consulta la pagina Riferimento agli errori per suggerimenti 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 alla risoluzione dei problemi mirate elencate nella sezione Risoluzione dei problemi per tipo di problema del sommario potrebbe esserti d'aiuto.

Passaggi successivi