Risolvi i problemi di Cloud NAT

Questa guida ti aiuta a diagnosticare il motivo per cui i tuoi carichi di lavoro (pod o VM) non possono accedere a reti esterne utilizzando Cloud NAT. In qualità di sviluppatore, interagisci principalmente con la risorsa CloudNatGateway. Lo stato di questa risorsa è la tua principale fonte di verità per il debug.

Prima di iniziare

Per risolvere i problemi relativi a una configurazione Cloud NAT, devi disporre di quanto segue:

  • I ruoli di identità e accesso necessari. Chiedi all'amministratore IAM del progetto di concederti uno o entrambi i seguenti ruoli:
    • Visualizzatore Cloud NAT (cloud-nat-viewer): questo ruolo offre l'accesso in sola lettura alle risorse Cloud NAT. Questo ruolo ti consente di iniziare a diagnosticare il problema.
    • Sviluppatore Cloud NAT (cloud-nat-developer): questo ruolo fornisce le autorizzazioni necessarie agli operatori delle applicazioni per creare, leggere, aggiornare ed eliminare (CRUD) oggetti Cloud NAT all'interno dei progetti assegnati. Questo ruolo ti consente di eseguire molte delle correzioni descritte in questa pagina.
    • Per alcune misure diagnostiche e correzioni specifiche potrebbero essere necessari ruoli aggiuntivi.

Diagnostica iniziale

Prima di esaminare i codici di errore, assicurati che le risorse di base siano presenti e raggiungibili.

Comando:

kubectl get cloudnatgateway GATEWAY_NAME -n PROJECT_NAMESPACE -o yaml

Sostituisci quanto segue:

  • GATEWAY_NAME: il nome della risorsa CloudNatGateway.
  • PROJECT_NAMESPACE: lo spazio dei nomi del progetto.

Controlla le condizioni di stato:un gateway integro deve avere tutte le seguenti condizioni impostate su True:

  • Ready: lo stato di integrità globale.
  • SubnetsReady: la configurazione del pool IP è valida.
  • PerimeterConfigurationReady: L'infrastruttura di rete upstream è configurata.
  • EgressRoutesReady: Le policy di routing per i pod sono attive.

Se uno di questi è False, controlla i campi reason e message nell'output di stato e consulta le tabelle nelle sezioni seguenti.

Significato dei codici di errore e correzione

I codici di errore restituiti da kubectl get cloudnatgateway rientrano in tre categorie principali.

Errori di subnet (SubnetsReady è False)

Questa condizione indica problemi con il pool di indirizzi IP assegnato al gateway.

Codice di errore Significato Passaggi per la correzione
CloudNATSelectorFieldOverlapsCode Conflitto di configurazione. Il workloadSelector di questo gateway corrisponde agli stessi carichi di lavoro di un altro gateway nel tuo progetto. Il traffico non può essere instradato in modo deterministico.
  1. Elenca tutti i gateway Cloud NAT nel tuo progetto: kubectl get cloudnatgateway
  2. Confronta il workloadSelector di questo gateway con gli altri.
  3. Modifica le etichette in modo che nessun singolo pod/VM venga selezionato da più di un gateway.
CloudNATSubnetRefsFieldInvalidCode

Subnet non valida. La subnet specificata in subnetRefs non è utilizzabile. Motivi comuni:

  • La subnet non esiste.
  • La subnet non è nello stato Ready.
  • La subnet non è di tipo Leaf.
  1. Verifica che la subnet esista: kubectl get subnet <SUBNET_NAME>
  2. Verifica che lo stato della subnet sia Ready.
  3. Assicurati che la subnet type sia Leaf (Cloud NAT non può utilizzare subnet root o di loopback).
CloudNATSubnetAlreadyInUseCode Conflitto di subnet. La subnet che hai richiesto è già "di proprietà" di un altro gateway Cloud NAT. Una subnet può essere collegata a un solo gateway alla volta.
  1. Scegli una subnet diversa per questo gateway.
  2. In alternativa, rimuovi prima la subnet dall'altro gateway.
UNETAPIServerErrorCode Errore di sistema. Il controller non può comunicare con il server API per convalidare le subnet. Azione: probabilmente si tratta di un problema temporaneo della piattaforma. Se il problema persiste, contatta l'amministratore della piattaforma.

Errori di configurazione del perimetro (PerimeterConfigurationReady è False)

Questa condizione riflette lo stato dei gateway perimetrali.

Codice di errore Significato Passaggi per la correzione
NET-E0305 Conflitto di configurazione. (Come sopra). I selettori sovrapposti impediscono al sistema di calcolare il gruppo di routing corretto.
  1. Elenca tutti i gateway Cloud NAT nel tuo progetto: kubectl get cloudnatgateway
  2. Confronta il workloadSelector di questo gateway con gli altri.
  3. Modifica le etichette in modo che nessun singolo pod/VM venga selezionato da più di un gateway.
NET-E0301 Esaurimento delle risorse / Errore del nodo. Il sistema ha creato la configurazione, ma non è stato possibile assegnare gli IP di uscita a un nodo fisico integro. In genere significa che la subnet non ha più indirizzi IP o che i nodi gateway non sono attivi.
  1. Controlla l'utilizzo della [subnet](/distributed-cloud/hosted/docs/latest/gdch/platform/pa-user/subnets-overview). È piena?
  2. Se la subnet ha IP liberi ed è Ready, ciò indica un errore dell'infrastruttura lato piattaforma (ad esempio, non sono disponibili nodi gateway integri). Azione: contatta l'amministratore della piattaforma.
NET-E0001 Errore di sistema. Comunicazione con il controller non riuscita. Azione:contatta l'amministratore della piattaforma.

Errori di route in uscita (EgressRoutesReady è False)

Questa condizione riflette lo stato delle norme di routing all'interno del cluster.

Codice di errore Significato Passaggi per la correzione
NET-E0305 Conflitto di configurazione. (Come sopra).
  1. Elenca tutti i gateway Cloud NAT nel tuo progetto: kubectl get cloudnatgateway
  2. Confronta il workloadSelector di questo gateway con gli altri.
  3. Modifica le etichette in modo che nessun singolo pod/VM venga selezionato da più di un gateway.
NET-E0304 Programmazione non riuscita. Il sistema non è riuscito a programmare le regole di routing (BPF) per gli IP gateway specifici.

Azione:si tratta di un errore di programmazione interno o di un'incoerenza di stato.

  1. Prova ad apportare un aggiornamento banale al gateway (ad es. modifica un'etichetta) per attivare una riconciliazione.
  2. Se il problema persiste, contatta l'amministratore della piattaforma.

Altri problemi comuni

Se lo stato del gateway è Ready: True, ma il traffico continua a non funzionare, controlla queste configurazioni errate comuni:

Autorizzazione a livello di progetto mancante

Il progetto deve essere autorizzato esplicitamente a inviare traffico in uscita.

  • Controlla:la risorsa Progetto ha l'etichetta networking.gdc.goog/enable-default-egress-allow-to-outside-the-org: "true"?
  • Correzione:chiedi all'amministratore del progetto di applicare questa etichetta.

Annotazione VM mancante (solo macchine virtuali)

Le VM ignorano il percorso di uscita standard del pod e hanno bisogno di istruzioni esplicite per utilizzare Cloud NAT.

  • Controlla:l'oggetto VirtualMachineExternalAccess (VMEA) per la tua VM ha l'annotazione egress.networking.gke.io/use-cloud-nat: "true"?
  • Correzione:aggiungi l'annotazione all'oggetto VMEA.

Traffico in uscita dei nodi del cluster standard

Se esegui un cluster standard, i nodi stessi devono disporre dell'autorizzazione per l'uscita.

  • Controlla:l'oggetto Cluster ha l'etichetta cluster.gdc.goog/enable-node-egress-to-outside-the-org: "true"?
  • Correzione:chiedi all'amministratore della piattaforma di etichettare l'oggetto Cluster.

Collisione tra NAT in uscita predefinito e Cloud NAT

Un errore di configurazione comune si verifica quando un workload è configurato per utilizzare il meccanismo NAT in uscita predefinito legacy e viene selezionato contemporaneamente da un gateway Cloud NAT. Questa combinazione genera una collisione in cui il piano dati riceve istruzioni di routing in conflitto, con conseguente perdita di pacchetti o comportamento di routing non deterministico.

Diagnostica delle collisioni dei pod

Per i pod, il NAT in uscita predefinito viene in genere abilitato aggiungendo un'etichetta specifica. Un pod non può avere questa etichetta se è anche il target di un gateway Cloud NAT.

  1. Identifica il pod di destinazione:recupera le etichette del pod che presenta problemi di connettività.

    kubectl get pod <POD_NAME> -n <NAMESPACE> --show-labels

  2. Verifica la presenza di etichette in conflitto:

    • Selezione di Cloud NAT: le etichette del pod corrispondono al workloadSelector di qualsiasi CloudNatGateway nello spazio dei nomi?
    • Etichetta di uscita predefinita:il pod ha l'etichetta egress.networking.gke.io/enabled: "true"?

    Condizione:se BOTH è true, si verifica una collisione.

  3. Risoluzione:rimuovi l'etichetta di uscita predefinita legacy dal pod (o dal relativo Deployment/StatefulSet principale) per consentire a Cloud NAT di assumere il controllo esclusivo.

Diagnostica delle collisioni di VM

Per le macchine virtuali, il meccanismo è diverso. Le VM con oggetti VirtualMachineExternalAccess (VMEA) sono spesso configurate per l'accesso predefinito. Per utilizzare Cloud NAT, devono attivarlo esplicitamente aggiungendo un'annotazione per disattivare il percorso predefinito e attivare il percorso Cloud NAT.

  1. Identifica il VMEA: trova l'oggetto VirtualMachineExternalAccess associato alla VM.

    kubectl get vmea -n <NAMESPACE>

  2. Controllare la presenza di annotazioni mancanti:

    • Selezione di Cloud NAT:le etichette della VM corrispondono a un CloudNatGateway?
    • Adesione all'annotazione:controlla il VMEA per l'annotazione egress.networking.gke.io/use-cloud-nat: "true".

    Condizione: se la VM corrisponde a un gateway, ma NON ha questa annotazione, il traffico entrerà in conflitto con il sistema di uscita predefinito.

  3. Risoluzione:aggiungi l'annotazione all'oggetto VMEA.

    kubectl annotate vmea <VMEA_NAME> -n <NAMESPACE> egress.networking.gke.io/use-cloud-nat="true"