Cloud NAT のトラブルシューティング

このガイドは、Cloud NAT を使用してワークロード（Pod または VM）が外部ネットワークにアクセスできない理由を診断するのに役立ちます。デベロッパーは主に CloudNatGateway リソースを操作します。このリソースのステータスは、デバッグの主な信頼できる情報源です。

始める前に

Cloud NAT 構成のトラブルシューティングを行うには、次のものが必要です。

必要な ID とアクセスロール。プロジェクト IAM 管理者に、次のロールのいずれかまたは両方を付与するよう依頼します。
- Cloud NAT 閲覧者（cloud-nat-viewer）: このロールは、Cloud NAT リソースへの読み取り専用アクセスを提供します。このロールは、問題の診断を開始するために使用します。
- Cloud NAT デベロッパー（cloud-nat-developer）: このロールは、割り当てられたプロジェクト内で Cloud NAT オブジェクトの作成、読み取り、更新、削除（CRUD）を行うために必要な権限をアプリケーションオペレーターに付与します。このロールを使用すると、このページで説明する修正の多くを実行できます。
- 特定の診断対策や修正には、追加のロールが必要になる場合があります。

初期診断

エラーコードについて説明する前に、基本リソースが存在し、アクセス可能であることを確認してください。

コマンド:

kubectl get cloudnatgateway GATEWAY_NAME -n PROJECT_NAMESPACE -o yaml

次のように置き換えます。

GATEWAY_NAME: CloudNatGateway リソースの名前。
PROJECT_NAMESPACE: プロジェクトの Namespace。

ステータス条件を確認する: 正常なゲートウェイでは、次の条件がすべて True に設定されている必要があります。

Ready: グローバルヘルスステータス。
SubnetsReady: IP プールの構成は有効です。
PerimeterConfigurationReady: 上流のネットワークインフラストラクチャが構成されています。
EgressRoutesReady: Pod のルーティングポリシーが有効になっています。

いずれかが False の場合は、ステータス出力の reason フィールドと message フィールドを確認し、次のセクションの表を参照してください。

エラーコードのリファレンスと修復

kubectl get cloudnatgateway から返されるエラーコードは、主に次の 3 つのカテゴリに分類されます。

サブネットエラー（`SubnetsReady` が False）

この条件は、ゲートウェイに割り当てられた IP アドレスプールに関する問題を示します。

エラーコード	意味	修復手順
`CloudNATSelectorFieldOverlapsCode`	構成の競合。このゲートウェイの `workloadSelector` が、プロジェクト内の別のゲートウェイと同じワークロードと一致しています。トラフィックを決定論的にルーティングできません。	プロジェクト内のすべての Cloud NAT ゲートウェイを一覧表示します。`kubectl get cloudnatgateway` このゲートウェイの `workloadSelector` を他のゲートウェイと比較します。 1 つの Pod/VM が複数のゲートウェイによって選択されないようにラベルを変更します。
`CloudNATSubnetRefsFieldInvalidCode`	サブネットが無効です。`subnetRefs` で指定されたサブネットは使用できません。一般的な原因: サブネットが存在しません。サブネットが `Ready` 状態ではありません。サブネットのタイプが `Leaf` ではありません。	サブネットが存在することを確認します。`kubectl get subnet <SUBNET_NAME>` サブネットのステータスが `Ready` であることを確認します。サブネット `type` が `Leaf` であることを確認します（Cloud NAT は Root サブネットまたは Loopback サブネットを使用できません）。
`CloudNATSubnetAlreadyInUseCode`	サブネットの競合。リクエストしたサブネットは、別の Cloud NAT ゲートウェイによってすでに「所有」されています。サブネットは一度に 1 つのゲートウェイにのみアタッチできます。	このゲートウェイに別のサブネットを選択します。または、まず他のゲートウェイからサブネットを削除します。
`UNETAPIServerErrorCode`	システムエラー。コントローラが API サーバーと通信してサブネットを検証できません。	対応: これは一時的なプラットフォームの問題である可能性があります。問題が解決しない場合は、プラットフォーム管理者にお問い合わせください。

境界構成エラー（`PerimeterConfigurationReady` が False）

この条件は、境界ゲートウェイのステータスを反映します。

エラーコード	意味	修復手順
`NET-E0305`	構成の競合。（上記と同じ）。セレクタが重複していると、システムが正しいルーティンググループを計算できません。	プロジェクト内のすべての Cloud NAT ゲートウェイを一覧表示します。`kubectl get cloudnatgateway` このゲートウェイの `workloadSelector` を他のゲートウェイと比較します。 1 つの Pod/VM が複数のゲートウェイによって選択されないようにラベルを変更します。
`NET-E0301`	リソースの枯渇 / ノード障害。システムは構成を作成しましたが、正常な物理ノードに下り（外向き）IP を割り当てることができませんでした。通常、これはサブネットの IP が不足しているか、ゲートウェイノードがダウンしていることを意味します。	[サブネット](/distributed-cloud/hosted/docs/latest/gdch/platform/pa-user/subnets-overview) の使用状況を確認します。満席ですか？サブネットに空き IP があり、`Ready` の場合は、プラットフォーム側のインフラストラクチャ障害（使用可能な正常なゲートウェイノードがないなど）を示します。対応: プラットフォーム管理者に連絡します。
`NET-E0001`	システムエラー。コントローラとの通信に失敗しました。	対応: プラットフォーム管理者に連絡します。

下り（外向き）ルートエラー（`EgressRoutesReady` が False）

この条件は、クラスタ内のルーティングポリシーのステータスを反映します。

エラーコード意味修復手順

エラーコード	意味	修復手順
`NET-E0305`	構成の競合。（上記と同じ）。	プロジェクト内のすべての Cloud NAT ゲートウェイを一覧表示します。`kubectl get cloudnatgateway` このゲートウェイの `workloadSelector` を他のゲートウェイと比較します。 1 つの Pod/VM が複数のゲートウェイによって選択されないようにラベルを変更します。
`NET-E0304`	プログラミングの失敗。システムが特定のゲートウェイ IP のルーティングルール（BPF）をプログラムできませんでした。	アクション: 内部プログラミングエラーまたは状態の不整合です。 Gateway に些細な更新（ラベルの編集など）を加えて、調整をトリガーしてみてください。問題が解決しない場合は、プラットフォーム管理者にお問い合わせください。

NET-E0305

構成の競合。（上記と同じ）。

プロジェクト内のすべての Cloud NAT ゲートウェイを一覧表示します。kubectl get cloudnatgateway
このゲートウェイの workloadSelector を他のゲートウェイと比較します。
1 つの Pod/VM が複数のゲートウェイによって選択されないようにラベルを変更します。

NET-E0304

プログラミングの失敗。システムが特定のゲートウェイ IP のルーティングルール（BPF）をプログラムできませんでした。

アクション: 内部プログラミングエラーまたは状態の不整合です。

Gateway に些細な更新（ラベルの編集など）を加えて、調整をトリガーしてみてください。
問題が解決しない場合は、プラットフォーム管理者にお問い合わせください。

その他の一般的な問題

Gateway のステータスが Ready: True であってもトラフィックが失敗する場合は、次の一般的な構成ミスを確認してください。

プロジェクトレベルの権限がない

プロジェクトが下り（外向き）トラフィックを許可されている必要があります。

確認: プロジェクトリソースに networking.gdc.goog/enable-default-egress-allow-to-outside-the-org: "true" というラベルが付いていますか？
解決策: プロジェクト管理者にこのラベルの適用を依頼してください。

VM アノテーションがない（仮想マシンのみ）

VM は標準の Pod 上り（内向き）パスをバイパスするため、Cloud NAT を使用するための明示的な指示が必要です。

確認: VM の VirtualMachineExternalAccess（VMEA）オブジェクトにアノテーション egress.networking.gke.io/use-cloud-nat: "true" がありますか？
修正: アノテーションを VMEA オブジェクトに追加します。

Standard クラスタノードの下り（外向き）

Standard クラスタを実行している場合、ノード自体に下り（外向き）の権限が必要です。

確認: Cluster オブジェクトに cluster.gdc.goog/enable-node-egress-to-outside-the-org: "true" というラベルが付いていますか？
修正: プラットフォーム管理者にクラスタオブジェクトのラベル付けを依頼します。

デフォルトの下り（外向き）NAT と Cloud NAT の競合

一般的な構成エラーは、ワークロードが以前のデフォルトの下り（外向き）NAT メカニズムを使用するように構成されていると同時に、Cloud NAT ゲートウェイによって選択されている場合に発生します。この組み合わせにより、データプレーンが競合するルーティング手順を受信し、パケットロスや非決定論的なルーティング動作が発生する衝突が発生します。

Pod の衝突を診断する

Pod の場合、通常は特定のラベルを追加することでデフォルトの下り（外向き）NAT が有効になります。Cloud NAT ゲートウェイのターゲットになっている Pod にこのラベルを設定することはできません。

ターゲット Pod を特定する: 接続の問題が発生している Pod のラベルを取得します。
```
kubectl get pod <POD_NAME> -n <NAMESPACE> --show-labels
```
競合するラベルを確認する:
- Cloud NAT の選択: Pod のラベルは、Namespace 内の CloudNatGateway の workloadSelector と一致しますか？
- デフォルトの下り（外向き）ラベル: Pod に egress.networking.gke.io/enabled: "true" ラベルが付いていますか？
条件: 両方が true の場合、衝突が発生します。
解決策: Pod（またはその親 Deployment/StatefulSet）からレガシーのデフォルトの下り（外向き）ラベルを削除して、Cloud NAT が排他的制御を引き継ぐようにします。

VM の衝突を診断する

仮想マシンの場合、メカニズムは異なります。VirtualMachineExternalAccess（VMEA）オブジェクトを含む VM は、デフォルトのアクセス用に構成されることがよくあります。Cloud NAT を使用するには、デフォルトパスを無効にして Cloud NAT パスを有効にするアノテーションを追加して、明示的にオプトインする必要があります。

VMEA を特定する: VM に関連付けられている VirtualMachineExternalAccess オブジェクトを見つけます。
```
kubectl get vmea -n <NAMESPACE>
```
アノテーションが欠落していないか確認します。
- Cloud NAT の選択: VM のラベルは CloudNatGateway と一致しますか？
- オプトインアノテーション: アノテーション egress.networking.gke.io/use-cloud-nat: "true" の VMEA を確認します。
条件: VM がゲートウェイと一致するが、このアノテーションがない場合、トラフィックはデフォルトの下り（外向き）システムと競合します。

解決策: アノテーションを VMEA オブジェクトに追加します。

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

Cloud NAT のトラブルシューティング コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。