Résoudre les problèmes liés à Cloud NAT

Ce guide vous aide à identifier pourquoi vos charges de travail (pods ou VM) ne peuvent pas accéder aux réseaux externes à l'aide de Cloud NAT. En tant que développeur, vous interagissez principalement avec la ressource CloudNatGateway. L'état de cette ressource est votre principale source de vérité pour le débogage.

Avant de commencer

Pour résoudre les problèmes liés à une configuration Cloud NAT, vous devez disposer des éléments suivants :

  • Les rôles d'identité et d'accès nécessaires. Demandez à votre administrateur de projet IAM de vous attribuer l'un des rôles suivants, ou les deux :
    • Lecteur Cloud NAT (cloud-nat-viewer) : ce rôle offre un accès en lecture seule aux ressources Cloud NAT. Ce rôle vous permet de commencer à diagnostiquer le problème.
    • Développeur Cloud NAT (cloud-nat-developer) : ce rôle fournit les autorisations nécessaires aux opérateurs d'applications pour créer, lire, mettre à jour et supprimer (CRUD) des objets Cloud NAT dans les projets qui leur sont attribués. Ce rôle vous permet d'effectuer de nombreuses corrections décrites sur cette page.
    • Des rôles supplémentaires peuvent être nécessaires pour certaines mesures de diagnostic et corrections spécifiques.

Diagnostic initial

Avant de vous intéresser aux codes d'erreur, assurez-vous que les ressources de base sont présentes et accessibles.

Commande :

kubectl get cloudnatgateway GATEWAY_NAME -n PROJECT_NAMESPACE -o yaml

Remplacez les éléments suivants :

  • GATEWAY_NAME : nom de la ressource CloudNatGateway.
  • PROJECT_NAMESPACE : espace de noms de votre projet.

Vérifiez les conditions d'état : une passerelle opérationnelle doit remplir toutes les conditions suivantes, définies sur True :

  • Ready : état de santé global.
  • SubnetsReady : la configuration du pool d'adresses IP est valide.
  • PerimeterConfigurationReady : l'infrastructure réseau en amont est configurée.
  • EgressRoutesReady : les règles de routage de vos pods sont actives.

Si l'un d'entre eux est False, vérifiez les champs reason et message dans la sortie d'état, puis consultez les tableaux des sections suivantes.

Informations de référence sur les codes d'erreur et correction

Les codes d'erreur renvoyés par kubectl get cloudnatgateway se répartissent en trois catégories principales.

Erreurs de sous-réseau (SubnetsReady est défini sur "False")

Cette condition indique des problèmes au niveau du pool d'adresses IP attribué à la passerelle.

Code d'erreur Signification Étapes de correction
CloudNATSelectorFieldOverlapsCode Conflit de configuration. La valeur workloadSelector de cette passerelle correspond aux mêmes charges de travail qu'une autre passerelle de votre projet. Le trafic ne peut pas être acheminé de manière déterministe.
  1. Répertoriez toutes les passerelles Cloud NAT de votre projet : kubectl get cloudnatgateway.
  2. Comparez le workloadSelector de cette passerelle avec d'autres.
  3. Modifiez les étiquettes de sorte qu'aucun pod/VM ne soit sélectionné par plus d'une passerelle.
CloudNATSubnetRefsFieldInvalidCode

Sous-réseau non valide. Le sous-réseau spécifié dans subnetRefs est inutilisable. Raisons courantes :

  • Le sous-réseau n'existe pas.
  • Le sous-réseau n'est pas à l'état Ready.
  • Le sous-réseau n'est pas de type Leaf.
  1. Vérifiez que le sous-réseau existe : kubectl get subnet <SUBNET_NAME>
  2. Vérifiez que l'état du sous-réseau est Ready.
  3. Assurez-vous que le sous-réseau type est Leaf (Cloud NAT ne peut pas utiliser de sous-réseaux racine ou de bouclage).
CloudNATSubnetAlreadyInUseCode Conflit de sous-réseau. Le sous-réseau que vous avez demandé est déjà "détenu" par une autre passerelle Cloud NAT. Un sous-réseau ne peut être associé qu'à une seule passerelle à la fois.
  1. Choisissez un autre sous-réseau pour cette passerelle.
  2. Vous pouvez également supprimer d'abord le sous-réseau de l'autre passerelle.
UNETAPIServerErrorCode Erreur système. Le contrôleur ne peut pas communiquer avec le serveur d'API pour valider les sous-réseaux. Action : il s'agit probablement d'un problème temporaire de la plate-forme. Si le problème persiste, contactez l'administrateur de votre plate-forme.

Erreurs de configuration du périmètre (PerimeterConfigurationReady est défini sur "False")

Cette condition reflète l'état des passerelles de périmètre.

Code d'erreur Signification Étapes de correction
NET-E0305 Conflit de configuration. (comme ci-dessus). Les sélecteurs qui se chevauchent empêchent le système de calculer le groupe de routage approprié.
  1. Répertoriez toutes les passerelles Cloud NAT de votre projet : kubectl get cloudnatgateway.
  2. Comparez le workloadSelector de cette passerelle avec d'autres.
  3. Modifiez les étiquettes de sorte qu'aucun pod/VM ne soit sélectionné par plus d'une passerelle.
NET-E0301 Épuisement des ressources / Défaillance du nœud. Le système a créé la configuration, mais n'a pas pu attribuer vos adresses IP de sortie à un nœud physique opérationnel. Cela signifie généralement que le sous-réseau n'a plus d'adresses IP ou que les nœuds de passerelle sont indisponibles.
  1. Vérifiez l'utilisation de votre [sous-réseau](/distributed-cloud/hosted/docs/latest/gdcag/platform/pa-user/subnets-overview). Est-il plein ?
  2. Si le sous-réseau dispose d'adresses IP libres et qu'il est Ready, cela indique une défaillance de l'infrastructure côté plate-forme (par exemple, aucun nœud de passerelle opérationnel n'est disponible). Action : contactez l'administrateur de la plate-forme.
NET-E0001 Erreur système. Échec de la communication avec le contrôleur. Action : contactez l'administrateur de la plate-forme.

Erreurs de route de sortie (EgressRoutesReady est défini sur "False")

Cette condition reflète l'état des règles de routage dans le cluster.

Code d'erreur Signification Étapes de correction
NET-E0305 Conflit de configuration. (comme ci-dessus).
  1. Répertoriez toutes les passerelles Cloud NAT de votre projet : kubectl get cloudnatgateway.
  2. Comparez le workloadSelector de cette passerelle avec d'autres.
  3. Modifiez les étiquettes de sorte qu'aucun pod/VM ne soit sélectionné par plus d'une passerelle.
NET-E0304 Échec de la programmation. Le système n'a pas réussi à programmer les règles de routage (BPF) pour vos adresses IP de passerelle spécifiques.

Action : il s'agit d'une erreur de programmation interne ou d'une incohérence d'état.

  1. Essayez d'apporter une modification mineure à la passerelle (par exemple, modifier un libellé) pour déclencher un rapprochement.
  2. Si le problème persiste, contactez l'administrateur de la plate-forme.

Autres problèmes courants

Si l'état de la passerelle est Ready: True, mais que le trafic échoue toujours, vérifiez les erreurs de configuration courantes suivantes :

Autorisation manquante au niveau du projet

Votre projet doit être explicitement autorisé à envoyer du trafic sortant.

  • Vérification : Votre ressource Project comporte-t-elle l'étiquette networking.gdc.goog/enable-default-egress-allow-to-outside-the-org: "true" ?
  • Solution : Demandez à l'administrateur de votre projet d'appliquer ce libellé.

Annotation de VM manquante (machines virtuelles uniquement)

Les VM contournent le chemin de sortie standard des pods et ont besoin d'instructions explicites pour utiliser Cloud NAT.

  • Vérification : l'objet VirtualMachineExternalAccess (VMEA) de votre VM comporte-t-il l'annotation egress.networking.gke.io/use-cloud-nat: "true" ?
  • Correction : Ajoutez l'annotation à l'objet VMEA.

Sortie de nœud de cluster standard

Si vous exécutez un cluster standard, les nœuds eux-mêmes doivent disposer d'une autorisation de sortie.

  • Vérification : l'objet Cluster comporte-t-il l'étiquette cluster.gdc.goog/enable-node-egress-to-outside-the-org: "true" ?
  • Solution : Demandez à l'administrateur de votre plate-forme d'ajouter un libellé à l'objet Cluster.

Collision entre la fonctionnalité NAT de sortie par défaut et Cloud NAT

Une erreur de configuration courante se produit lorsqu'une charge de travail est configurée pour utiliser l'ancien mécanisme NAT de sortie par défaut, tout en étant sélectionnée par une passerelle Cloud NAT. Cette combinaison entraîne une collision où le plan de données reçoit des instructions de routage contradictoires, ce qui entraîne une perte de paquets ou un comportement de routage non déterministe.

Diagnostiquer les collisions de pods

Pour les pods, le NAT de sortie par défaut est généralement activé en ajoutant un libellé spécifique. Un pod ne peut pas avoir ce libellé s'il est également ciblé par une passerelle Cloud NAT.

  1. Identifier le pod cible : obtenez les étiquettes du pod qui rencontre des problèmes de connectivité.

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

  2. Vérifier les libellés en conflit :

    • Sélection Cloud NAT : les étiquettes du pod correspondent-elles au workloadSelector d'un CloudNatGateway de l'espace de noms ?
    • Étiquette de sortie par défaut : le pod possède-t-il l'étiquette egress.networking.gke.io/enabled: "true" ?

    Condition : si les DEUX conditions sont remplies, il y a collision.

  3. Résolution : Supprimez l'ancien libellé de sortie par défaut du pod (ou de son déploiement/StatefulSet parent) pour permettre à Cloud NAT de prendre le contrôle exclusif.

Diagnostiquer les collisions de VM

Pour les machines virtuelles, le mécanisme est différent. Les VM avec des objets VirtualMachineExternalAccess (VMEA) sont souvent configurées pour un accès par défaut. Pour utiliser Cloud NAT, ils doivent explicitement l'activer en ajoutant une annotation pour désactiver le chemin d'accès par défaut et activer le chemin d'accès Cloud NAT.

  1. Identifier le VMEA : recherchez l'objet VirtualMachineExternalAccess associé à la VM.

    kubectl get vmea -n <NAMESPACE>

  2. Vérifier l'absence d'annotation :

    • Sélection Cloud NAT : les libellés de la VM correspondent-ils à une CloudNatGateway ?
    • Annotation d'activation : vérifiez l'annotation egress.networking.gke.io/use-cloud-nat: "true" dans l'API VME.

    Condition : si la VM correspond à une passerelle, mais qu'elle N'A PAS cette annotation, le trafic entrera en conflit avec le système de sortie par défaut.

  3. Résolution : ajoutez l'annotation à l'objet VMEA.

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