Risoluzione dei problemi relativi alla creazione o all'upgrade del cluster

Puoi diagnosticare e risolvere i problemi che si verificano durante l'installazione o l'upgrade dei cluster Google Distributed Cloud. Il controllo dei log di diagnostica e degli stati dei nodi ti aiuta a identificare le cause degli errori e a ripristinare le operazioni interrotte.

Problemi di installazione

Le sezioni seguenti potrebbero aiutarti a risolvere i problemi relativi all'installazione di Google Distributed Cloud.

Messaggi di errore temporanei

Il processo di installazione di Google Distributed Cloud è un ciclo di riconciliazione continuo. Di conseguenza, durante l'installazione potresti visualizzare messaggi di errore temporanei nel log.

Se l'installazione viene completata correttamente, questi errori possono essere ignorati. Di seguito è riportato un elenco di messaggi di log degli errori temporanei tipici:

  Internal error occurred: failed calling webhook "webhook.cert-manager.io": Post
  https://cert-manager-webhook.cert-manager.svc:443/mutate?timeout=10s:
  dial tcp IP_ADDRESS:443: connect: connection refused
  Internal error occurred: failed calling webhook "vcluster.kb.io": Post
  https://webhook-service.kube-system.svc:443/validate-baremetal-cluster-gke-io-v1-cluster?timeout=30s:
  dial tcp IP_ADDRESS:443: connect: connection refused
  Failed to register cluster with GKE Hub; gcloud output: error running command
  'gcloud container fleet memberships register CLUSTER_NAME  --verbosity=error --quiet':
  error: exit status 1, stderr: 'ERROR: (gcloud.container.hub.memberships.register)
  Failed to check if the user is a cluster-admin: Unable to connect to the server: EOF
  Get
  https://127.0.0.1:34483/apis/infrastructure.baremetal.cluster.gke.io/v1/namespaces/cluster-
  cluster1/baremetalmachines: dial tcp 127.0.0.1:34483: connect: connection refused"
  Create Kind Cluster "msg"="apply run failed" "error"="unable to recognize \"/tmp/kout088683152\": no matches for kind \"NetworkLogging\" in version \"networking.gke.io/v1alpha1\""
  Create Kind Cluster "msg"="apply run failed" "error"="unable to recognize \"/tmp/kout869681888\": no matches for kind \"Provider\" in version \"clusterctl.cluster.x-k8s.io/v1alpha3\""

Se la chiave del service account Google Cloud è scaduta, vengono visualizzati i seguenti messaggi di errore di bmctl:

Error validating cluster config: 3 errors occurred:
        * GKEConnect check failed: Get https://gkehub.googleapis.com/v1beta1/projects/project/locations/global/memberships/admin: oauth2: cannot fetch token: 400 Bad Request
Response: {"error":"invalid_grant","error_description":"Invalid JWT Signature."}
        * ClusterOperations check failed: Post https://cloudresourcemanager.googleapis.com/v1/projects/project:testIamPermissions?alt=json&prettyPrint=false: oauth2: cannot fetch token: 400 Bad Request
Response: {"error":"invalid_grant","error_description":"Invalid JWT Signature."}
        * GCR pull permission for bucket: artifacts.anthos-baremetal-release.appspot.com failed: Get https://storage.googleapis.com/storage/v1/b/artifacts.anthos-baremetal-release.appspot.com/iam/testPermissions?alt=json&permissions=storage.objects.get&permissions=storage.objects.list&prettyPrint=false: oauth2: cannot fetch token: 400 Bad Request
Response: {"error":"invalid_grant","error_description":"Invalid JWT Signature."}

Devi generare una nuova account di servizio account.

Utilizza il cluster di bootstrap per eseguire il debug dei problemi

Quando Google Distributed Cloud crea cluster autogestiti (amministrativi, ibridi o autonomi), esegue il deployment di un cluster Kubernetes in Docker (kind) per ospitare temporaneamente i controller Kubernetes necessari per creare i cluster. Questo cluster temporaneo è chiamato cluster di bootstrap. I cluster utente vengono creati e aggiornati dal cluster di amministrazione o ibrido che li gestisce senza l'utilizzo di un cluster di bootstrap.

Se nel tuo deployment esiste già un cluster kind quando tenti di installarlo, Google Distributed Cloud elimina il cluster kind esistente. L'eliminazione avviene solo dopo che l'installazione o l'upgrade sono stati completati. Per conservare il cluster kind esistente anche dopo l'esito positivo, utilizza il flag --keep-bootstrap-cluster di bmctl.

Google Distributed Cloud crea un file di configurazione per il cluster di bootstrap in WORKSPACE_DIR/.kindkubeconfig. Puoi connetterti al cluster di bootstrap solo durante la creazione e l'upgrade del cluster.

Il cluster di bootstrap deve accedere a un repository Docker per eseguire il pull delle immagini. Il registry predefinito è Artifact Registry, a meno che tu non utilizzi un registry privato. Durante la creazione del cluster,bmctl crea i seguenti file:

  • bmctl-workspace/config.json: contiene le credenziali del service account Google Cloud per l'accesso al registry. Le credenziali vengono ottenute dal campo gcrKeyPath nel file di configurazione del cluster.

  • bmctl-workspace/config.toml: contiene la configurazione containerd nel cluster kind.

Esamina i log del cluster di bootstrap

Per eseguire il debug del cluster di bootstrap, puoi procedere nel seguente modo:

  • Connettersi al cluster di bootstrap durante la creazione e l'upgrade del cluster.
  • Recupera i log del cluster di bootstrap.

Puoi trovare i log nella macchina che utilizzi per eseguire bmctl nelle seguenti cartelle:

  • bmctl-workspace/CLUSTER_NAME/log/create-cluster-TIMESTAMP/bootstrap-cluster/
  • bmctl-workspace/CLUSTER_NAME/log/upgrade-cluster-TIMESTAMP/bootstrap-cluster/

Sostituisci CLUSTER_NAME e TIMESTAMP con il nome del tuo cluster e l'ora del sistema corrispondente.

Per recuperare i log direttamente dal cluster di bootstrap, puoi eseguire il seguente comando durante la creazione e l'upgrade del cluster:

docker exec -it bmctl-control-plane bash

Il comando apre un terminale all'interno del container del control plane bmctl che viene eseguito nel cluster di bootstrap.

Per esaminare i log di kubelet e containerd, utilizza i seguenti comandi e cerca errori o avvisi nell'output:

journalctl -u kubelet
journalctl -u containerd

Abilita il logging di debug di containerd

Se i log di containerd standard non forniscono informazioni sufficienti per la risoluzione dei problemi, puoi aumentare il livello di logging. L'aumento del livello di logging è spesso necessario per diagnosticare problemi complessi, come problemi con un mirror del registry o errori ImagePullBackOff.

Per aumentare il livello di logging:

  1. Attiva il logging di debug:

    1. Apri il file di configurazione di containerd (/etc/containerd/config.toml) utilizzando l'editor di testo che preferisci.

    2. Nel file, individua la sezione [debug] e modifica il valore di level da "" a "debug".

    3. Salva il file ed esci dall'editor di testo.

    4. Verifica di aver aggiornato correttamente il file di configurazione:

      cat /etc/containerd/config.toml | grep debug
      

      L'output dovrebbe essere simile all'esempio seguente:

      [debug]
        level = "debug"
          shim_debug = false
      
    5. Per applicare la modifica al livello di logging, riavvia containerd:

      sudo systemctl restart containerd
      
  2. Per generare nuove voci di log, prova a eseguire il pull di un'immagine che non esiste o non è utilizzata da nodi o cluster. Ad esempio:

    # This command fails because the image doesn't exist
    crictl pull us-west1-docker.pkg.dev/gdc-project/samples/non-existent-image:latest
    

    In questo modo, containerd viene forzato a eseguire un'azione e a generare log dettagliati.

  3. Attendi che l'immagine venga estratta o che l'operazione non vada a buon fine, quindi raccogli i log di containerd in un file denominato containerd_log.txt:

    journalctl -u containerd --no-pager --since TIME_PERIOD > containerd_log.txt
    

    Sostituisci TIME_PERIOD con un valore che specifica l'ora di inizio dei log. Racchiudi tra virgolette doppie qualsiasi valore che contenga spazi. Ad esempio, "2 hours ago".

  4. Al termine della risoluzione dei problemi, ripristina il livello di log predefinito. Se lasci abilitato il log di debug, i log di sistema potrebbero essere sovraccaricati, le prestazioni potrebbero essere influenzate e le informazioni sensibili potrebbero essere esposte.

    1. Apri il file /etc/containerd/config.toml e reimposta il valore di level su "", il livello di logging predefinito.

    2. Verifica di aver aggiornato correttamente la configurazione:

      cat /etc/containerd/config.toml | grep level
      

      L'output dovrebbe essere simile all'esempio seguente:

      level = ""
      
    3. Per applicare la modifica, riavvia containerd:

      sudo systemctl restart containerd
      

      Il sistema è ora tornato alla configurazione di logging standard.

Problemi di upgrade del cluster

Quando esegui l'upgrade dei cluster Google Distributed Cloud, puoi monitorare l'avanzamento e controllare lo stato dei cluster e dei nodi.

Le seguenti indicazioni possono aiutarti a determinare se l'upgrade sta procedendo normalmente o se si è verificato un problema.

Monitora l'avanzamento dell'upgrade

Utilizza il comando kubectl describe cluster per visualizzare lo stato di un cluster durante il processo di upgrade:

kubectl describe cluster CLUSTER_NAME \
    --namespace CLUSTER_NAMESPACE \
    --kubeconfig ADMIN_KUBECONFIG

Sostituisci i seguenti valori:

  • CLUSTER_NAME: il nome del tuo cluster.
  • CLUSTER_NAMESPACE: lo spazio dei nomi del cluster.
  • ADMIN_KUBECONFIG: il file kubeconfig di amministrazione.
    • Per impostazione predefinita, i cluster di amministrazione, ibridi e autonomi utilizzano un upgrade in loco. Se utilizzi il flag --use-bootstrap=true con il comando bmctl upgrade, l'operazione di upgrade utilizza un cluster di bootstrap. Per monitorare l'avanzamento dell'upgrade quando viene utilizzato un cluster di bootstrap, specifica il percorso del file kubeconfig del cluster di bootstrap, .kindkubeconfig. Questo file si trova nella directory del workspace.

Guarda la sezione Status dell'output, che mostra un'aggregazione dello stato di upgrade del cluster. Se il cluster segnala un errore, utilizza le sezioni seguenti per risolvere il problema.

Controlla se i nodi sono pronti

Utilizza il comando kubectl get nodes per visualizzare lo stato dei nodi in un cluster durante il processo di upgrade:

kubectl get nodes --kubeconfig KUBECONFIG

Per verificare se un nodo ha completato correttamente il processo di upgrade, controlla le colonne VERSION e AGE nella risposta del comando. VERSION è la versione di Kubernetes per il cluster. Per visualizzare la versione di Kubernetes per una determinata versione di Google Distributed Cloud, consulta Controllo delle versioni.

Se il nodo mostra NOT READY, prova a connetterlo e controlla lo stato del kubelet:

systemctl status kubelet

Puoi anche esaminare i log di kubelet:

journalctl -u kubelet

Esamina l'output dello stato e dei log di kubelet per individuare i messaggi che indicano il motivo per cui il nodo ha un problema.

Controlla quale nodo è in fase di upgrade

Per verificare quale nodo del cluster è in fase di upgrade, utilizza il comando kubectl get baremetalmachines:

kubectl get baremetalmachines --namespace CLUSTER_NAMESPACE \
    --kubeconfig ADMIN_KUBECONFIG

Sostituisci i seguenti valori:

  • CLUSTER_NAMESPACE: lo spazio dei nomi del cluster.
  • ADMIN_KUBECONFIG: il file kubeconfig di amministrazione.
    • Se viene utilizzato un cluster di bootstrap per un upgrade autonomo, ibrido o di amministrazione, specifica il file kubeconfig del cluster di bootstrap (bmctl-workspace/.kindkubeconfig).

L'output di esempio seguente mostra che il nodo di cui è stato eseguito l'upgrade ha un ABM VERSION diverso da DESIRED ABM VERSION:

NAME         CLUSTER    READY   INSTANCEID               MACHINE      ABM VERSION   DESIRED ABM VERSION
10.200.0.2   cluster1   true    baremetal://10.200.0.2   10.200.0.2   1.13.0        1.14.0
10.200.0.3   cluster1   true    baremetal://10.200.0.3   10.200.0.3   1.13.0        1.13.0

Controlla quali nodi sono in fase di svuotamento

Durante il processo di upgrade, i pod vengono svuotati dai nodi e la pianificazione viene disabilitata fino al completamento dell'upgrade del nodo. Per vedere quali nodi sono in fase di svuotamento, utilizza il comando kubectl get nodes:

kubectl get nodes --kubeconfig USER_CLUSTER_KUBECONFIG | grep "SchedulingDisabled"

Sostituisci USER_CLUSTER_KUBECONFIG con il percorso del file kubeconfig del cluster utente.

La colonna STATUS viene filtrata utilizzando grep per mostrare solo i nodi che segnalano SchedulingDisabled. Questo stato indica che i nodi sono in fase di svuotamento.

Puoi anche controllare lo stato dei nodi dal cluster di amministrazione:

kubectl get baremetalmachines -n CLUSTER_NAMESPACE \
  --kubeconfig ADMIN_KUBECONFIG

Sostituisci i seguenti valori:

  • CLUSTER_NAMESPACE: lo spazio dei nomi del cluster.
  • ADMIN_KUBECONFIG: il file kubeconfig di amministrazione.
    • Se viene utilizzato un cluster di bootstrap per un upgrade autonomo, ibrido o di amministrazione, specifica il file kubeconfig del cluster di bootstrap (bmctl-workspace/.kindkubeconfig).

Il nodo in fase di svuotamento mostra lo stato nella colonna MAINTENANCE.

Controlla perché un nodo è in stato di svuotamento da molto tempo

Utilizza uno dei metodi descritti nella sezione precedente per identificare il nodo che viene svuotato utilizzando il comando kubectl get nodes. Utilizza il comando kubectl get pods e filtra in base al nome del nodo per visualizzare ulteriori dettagli:

kubectl get pods --all-namespaces -o wide --field-selector spec.nodeName=NODE_NAME

Sostituisci NODE_NAME con il nome del nodo da svuotare. L'output restituisce un elenco di pod bloccati o lenti da svuotare. L'upgrade procede, anche con pod bloccati, quando il processo di svuotamento di un nodo richiede più di 20 minuti.

A partire dalla versione 1.29, il processo di svuotamento dei nodi utilizza l'API Eviction, che rispetta i PodDisruptionBudgets (PDB).

Le seguenti impostazioni del PDB possono causare problemi di svuotamento dei nodi:

  • Pod gestiti da più PDB

  • Configurazioni statiche del PDB come le seguenti:

    • maxUnavailable == 0
    • minUnavailable >= repliche totali

    Il numero totale di repliche è difficile da determinare dalla risorsa PDB, perché è definito in una risorsa di livello superiore, come Deployment, ReplicaSet o StatefulSet. I PDB corrispondono ai pod solo in base al selettore nella loro configurazione. Un buon approccio per diagnosticare se una configurazione PDB statica sta causando un problema è verificare se pdb.Status.ExpectPods <= pdb.Status.DesiredHealthy e vedere se una delle configurazioni statiche menzionate consente che ciò accada.

Anche le violazioni di runtime, come il valore DisruptionsAllowed calcolato per una risorsa PDB pari a 0, possono bloccare lo svuotamento dei nodi. Se hai configurato oggetti PodDisruptionBudget che non possono consentire ulteriori interruzioni, gli upgrade dei nodi potrebbero non riuscire a eseguire l'upgrade alla versione del control plane dopo ripetuti tentativi. Per evitare questo errore, ti consigliamo di fare lo scale up di Deployment o HorizontalPodAutoscaler per consentire lo svuotamento del nodo rispettando la configurazione di PodDisruptionBudget.

Elenca tutti gli oggetti PodDisruptionBudget nel cluster che non consentono interruzioni:

kubectl --kubeconfig CLUSTER_KUBECONFIG \
    get poddisruptionbudget --all-namespaces \
    -o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'

Sostituisci CLUSTER_KUBECONFIG con il percorso del file kubeconfig del cluster.

I PDB predefiniti kube-system/log-aggregator e kube-system/prometheus vengono visualizzati nell'output con disruptionsAllowed: 0 quando non hanno pod corrispondenti e status.expectedPods è 0. Poiché questi PDB non bloccano lo svuotamento dei nodi, puoi ignorarli.

Controlla perché i pod non sono integri

Gli upgrade possono non riuscire se un pod contiene indirizzi IP del control plane upgrade-first-node o upgrade-node. Questo comportamento è solitamente dovuto al fatto che i pod statici non sono integri.

  1. Controlla i pod statici con il comando crictl ps -a e cerca eventuali pod Kubernetes o etcd in arresto anomalo. Se sono presenti pod con errori, esamina i log dei pod per capire perché si arrestano in modo anomalo.

    Ecco alcuni possibili esempi di comportamento di crashloop:

    • Le autorizzazioni o il proprietario dei file montati su pod statici non sono corretti.
    • La connettività all'indirizzo IP virtuale non funziona.
    • Problemi con etcd.
  2. Se il comando crictl ps non funziona o non restituisce nulla, controlla lo stato di kubelet e containerd. Utilizza i comandi systemctl status SERVICE e journalctl -u SERVICE per visualizzare i log.

Risolvi gli errori di convalida del CIDR durante l'upgrade del cluster

A partire dalla versione 1.34 di Google Distributed Cloud, bmctl e il webhook di ammissione di convalida del cluster (vcluster.kb.io) applicano una convalida CIDR canonica rigorosa su spec.clusterNetwork.pods.cidrBlocks e spec.clusterNetwork.services.cidrBlocks. La notazione CIDR standard richiede che tutti i bit host oltre la lunghezza del prefisso della subnet siano impostati su zero.

L'upgrade di un cluster creato con un blocco CIDR di pod o servizi non canonici alla versione 1.34 o successive non va a buon fine e restituisce un errore simile al seguente:

[E000018] Unable to Parse Cluster Configuration File: ...
* Cluster.baremetal.cluster.gke.io "CLUSTER_NAME" is invalid:
  spec.clusterNetwork.services.cidrBlocks: Invalid value: "NON_CANONICAL_CIDR":
  must not have bits set beyond the prefix length

L'aggiornamento della stringa CIDR nella risorsa personalizzata Cluster e nel file di configurazione del cluster al relativo indirizzo di rete canonico non rialloca gli indirizzi IP dei pod o dei servizi esistenti, non altera il routing e non interrompe i workload.

Per aggiornare il blocco CIDR non canonico alla notazione di rete canonica e sbloccare l'upgrade, segui questi passaggi:

  1. Determina l'indirizzo di rete canonico per il blocco CIDR interessato impostando su zero tutti i bit host oltre la lunghezza del prefisso della subnet. Ad esempio, se il blocco CIDR non valido è 10.96.0.1/16, il blocco CIDR canonico è 10.96.0.0/16.

  2. Modifica la risorsa lcm-validating-webhook-configuration ValidatingWebhookConfiguration nel cluster di amministrazione:

    kubectl --kubeconfig ADMIN_KUBECONFIG \
        edit validatingwebhookconfiguration lcm-validating-webhook-configuration
    

    Sostituisci ADMIN_KUBECONFIG con il percorso del file kubeconfig del cluster di amministrazione (o del file kubeconfig del cluster per i cluster autonomi o ibridi).

  3. Nella configurazione del webhook, trova la regola vcluster.kb.io che convalida baremetal.cluster.gke.io/v1 clusters. Rimuovi temporaneamente UPDATE dal suo elenco operations in modo che il webhook consenta l'aggiornamento della configurazione, quindi salva ed esci dall'editor.

  4. Modifica la risorsa personalizzata Cluster interessata:

    kubectl --kubeconfig ADMIN_KUBECONFIG \
        edit cluster CLUSTER_NAME \
        -n CLUSTER_NAMESPACE
    

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster interessato
    • CLUSTER_NAMESPACE: lo spazio dei nomi del cluster interessato, ad esempio cluster-CLUSTER_NAME
  5. Aggiorna spec.clusterNetwork.pods.cidrBlocks o spec.clusterNetwork.services.cidrBlocks alla notazione CIDR canonica, quindi salva ed esci dall'editor.

  6. Modifica di nuovo lcm-validating-webhook-configuration e ripristina il webhook di convalida aggiungendo di nuovo UPDATE all'elenco operations per vcluster.kb.io (se non viene modificato, il controller del ciclo di vita riconcilia e ripristina automaticamente questa regola).

  7. Se utilizzi bmctl upgrade cluster, aggiorna spec.clusterNetwork.pods.cidrBlocks o spec.clusterNetwork.services.cidrBlocks nel file di configurazione del cluster locale (bmctl-workspace/CLUSTER_NAME/CLUSTER_NAME.yaml) alla stessa notazione CIDR canonica.

  8. Riprova a eseguire l'upgrade del cluster.

Passaggi successivi

Se hai bisogno di ulteriore assistenza, contatta l'assistenza clienti Google Cloud. Puoi anche consultare Assistenza per ulteriori informazioni sulle risorse di assistenza, tra cui:

  • Requisiti per l'apertura di una richiesta di assistenza.
  • Strumenti per aiutarti a risolvere i problemi, ad esempio la configurazione dell'ambiente, i log e le metriche.
  • Componenti supportati.