Risolvi i problemi di Cloud NAT

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

Prima di iniziare

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

  • I ruoli di identità e accesso necessari. Chiedi all'amministratore del progetto IAM di concederti uno o entrambi i seguenti ruoli:
    • Cloud NAT Viewer (cloud-nat-viewer): questo ruolo offre l'accesso di sola lettura alle risorse Cloud NAT. Questo ruolo ti consente di iniziare a diagnosticare il problema.
    • Cloud NAT Developer (cloud-nat-developer): questo ruolo fornisce le autorizzazioni necessarie agli operatori delle applicazioni per creare, leggere, aggiornare ed eliminare (CRUD) gli 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: stato di salute globale.
  • SubnetsReady: la configurazione del pool di IP è valida.
  • PerimeterConfigurationReady: L'infrastruttura di rete a monte è configurata.
  • EgressRoutesReady: le policy di routing per i pod sono attive.

Se uno di questi è False, controlla i campi reason e message nell'output dello 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 della subnet (SubnetsReady è False)

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

Codice di errore Significato Passaggi per correggere l'errore
CloudNATSelectorFieldOverlapsCode Conflitto di configurazione. Il workloadSelector di questo gateway corrisponde agli stessi workload 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 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 è in 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 richiesta è 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: molto 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 correggere l'errore
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 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 in uscita a un nodo fisico integro. In genere, questo significa che la subnet ha esaurito gli IP o che i nodi gateway non sono attivi.
  1. Controlla l'utilizzo della [subnet](/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/subnets-overview). È piena?
  2. Se la subnet ha IP liberi ed è Ready, significa che si è verificato 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. Errore di comunicazione del controller. Azione: contatta l'amministratore della piattaforma.

Errori della route in uscita (EgressRoutesReady è False)

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

Codice di errore Significato Passaggi per correggere l'errore
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 altri.
  3. Modifica le etichette in modo che nessun singolo pod/VM venga selezionato da più di un gateway.
NET-E0304 Errore di programmazione. Il sistema non è riuscito a programmare le regole di instradamento (BPF) per gli IP del gateway specifici.

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

  1. Prova ad apportare un aggiornamento di poco conto al gateway (ad esempio, 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 tuo progetto deve essere esplicitamente autorizzato a inviare traffico in uscita.

  • Verifica: la risorsa Project 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 bypassano il percorso di traffico in uscita standard dei pod e richiedono istruzioni esplicite per utilizzare Cloud NAT.

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

Traffico in uscita dai nodi del cluster standard

Se esegui un cluster Standard, i nodi stessi devono avere l'autorizzazione per il traffico in uscita.

  • Verifica: 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.

Conflitto tra NAT in uscita predefinito e Cloud NAT

Un errore di configurazione comune si verifica quando un workload è configurato per utilizzare il meccanismo NAT di uscita predefinito legacy, ma è anche selezionato 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 le collisioni dei pod

Per i pod, il NAT in uscita predefinito viene in genere attivato 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. Controlla la presenza di etichette in conflitto:

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

    Condizione: se ENTRAMBE le condizioni sono vere, si verifica una collisione.

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

Diagnostica le collisioni delle 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. Controlla se manca l'annotazione:

    • Selezione di Cloud NAT: le etichette della VM corrispondono a un CloudNatGateway?
    • Annotazione di attivazione: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 traffico in 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"