AKS での Container Network Insights エージェントのトラブルシューティング

この記事では、AKS で Container Network Insights エージェントをデプロイ、設定、または使用するときに発生する可能性がある一般的な問題について説明します。各セクションは、 現象→原因→解決形式に 従います。

デプロイ手順については、 AKS での Container Network Insights エージェントのデプロイと使用に関する記事を参照してください。

拡張機能のインストールが失敗する

症状：az k8s-extension create コマンドが失敗するか、拡張機能のプロビジョニング状態にFailedが表示されます。

Cause: ソブリンクラウドリージョン (拡張機能は、Azureパブリックリージョンでのみサポートされます)、クラスター機能の不足、または十分なアクセス許可がありません。

解決方法:

詳細については、拡張機能のプロビジョニング状態を確認します。

az k8s-extension show \
    --cluster-name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --cluster-type managedClusters \
    --name containernetworkingagent \
    --query "{state:provisioningState, statuses:statuses}" -o json

クラスターがAzureパブリックリージョン内にあるかどうかを確認します。この拡張機能は、AKS がサポートされているすべてのAzureパブリックリージョンで利用できますが、Azure Government、21Vianet によって運用Microsoft Azure、またはその他のソブリンクラウドでは使用できません。

クラスターでワークロード ID と OIDC 発行者が有効になっていることを確認します。

az aks show \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --query "{oidcEnabled:oidcIssuerProfile.enabled, workloadIdentityEnabled:securityProfile.workloadIdentity.enabled}"

リソースグループに Contributor ロールと User Access Administrator ロールがあることを確認します。
az k8s-extension createを既に 1 回実行した場合は、拡張機能が既に存在するため、もう一度実行するとエラーが返されます。 az k8s-extension updateを使用して、既存の拡張機能の構成設定を変更します。
```
az k8s-extension update \
  --cluster-name $CLUSTER_NAME \
  --resource-group $RESOURCE_GROUP \
  --cluster-type managedClusters \
  --name containernetworkingagent \
  --configuration-settings config.SOME_SETTING=new-value
```

ID とアクセス許可のエラー

症状： エージェントポッドは起動しますが、要求の処理時に 401 Unauthorized エラーまたは 403 Forbidden エラーを返します。ポッドログには、認証または承認の失敗が表示されます。

原因： マネージド ID に必要な RBAC ロールの割り当てが不足しているか、フェデレーション資格情報のサブジェクトがエージェントのサービスアカウントと一致しません。

解決方法:

マネージド ID に必要な 4 つのロールの割り当てがすべて含まれているかどうかを確認します。

az role assignment list --assignee <identity-principal-id> --all -o table

これらのロールが存在していることを確認してください。

役割	Scope
`Cognitive Services OpenAI User`	Azure OpenAI リソース
`Azure Kubernetes Service Cluster User Role`	AKS クラスター
`Azure Kubernetes Service Contributor Role`	AKS クラスター
`Reader`	リソースグループ

クラスターでワークロード ID が有効になっていることを確認します。

az aks show \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --query "securityProfile.workloadIdentity.enabled"

フェデレーション資格情報のサブジェクトがサービスアカウントと一致するかどうかを確認します。
```
az identity federated-credential list \
    --identity-name $IDENTITY_NAME \
    --resource-group $RESOURCE_GROUP
```
subject フィールドはsystem:serviceaccount:kube-system:container-networking-agent-readerする必要があります。

Kubernetes サービスアカウントに正しいワークロード ID 注釈があることを確認します。

kubectl get serviceaccount container-networking-agent-reader -n kube-system -o yaml

azure.workload.identity/client-id注釈は、マネージド ID のクライアント ID と一致する必要があります。一致しない場合は、修正してポッドを再起動します。

kubectl annotate serviceaccount container-networking-agent-reader \
  -n kube-system \
  azure.workload.identity/client-id=$IDENTITY_CLIENT_ID \
  --overwrite

kubectl rollout restart deployment container-networking-agent -n kube-system

ヒント

Azure RBAC ロールの割り当てが反映されるまでに最大 10 分かかることがあります。セットアップ直後に 401 エラーまたは 403 エラーが表示された場合は、数分待ってからポッドを再起動します。

Azure OpenAI の接続に関する問題

症状： エージェントポッドが起動しますが、チャット要求は失敗します。ポッドログには、401 Unauthorized、404 Not Found、または Azure OpenAI エンドポイントを参照する接続エラーが表示されます。

Cause: Azure OpenAI エンドポイント、デプロイ名、またはマネージド ID 資格情報が正しく構成されていないか、エンドポイントへのネットワークトラフィックがブロックされます。

解決方法:

ポッドログで特定のエラーパターンを確認します。

ログメッセージ	原因	修正
`401 Unauthorized`	マネージド ID に `Cognitive Services OpenAI User` ロールがありません	OpenAI リソースにロールを割り当てる
`404 Not Found`	エンドポイントの URL またはデプロイ名が正しくありません	`AZURE_OPENAI_ENDPOINT`と`AZURE_OPENAI_DEPLOYMENT`を確認する
`Connection refused` / `Name resolution failed`	ネットワークまたは DNS の問題	NSG/ファイアウォール規則を確認し、エンドポイントのホスト名を確認する
`Token acquisition failed`	ワークロード ID が構成されていません	サービスアカウントの注釈とフェデレーション資格情報を確認する

マネージド ID に、Azure OpenAI リソースに対する Cognitive Services OpenAI User ロールがあることを確認します。

az role assignment list \
  --assignee <managed-identity-principal-id> \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<openai-resource-name> \
  --output table

ネットワークポリシー、Azure Firewall、または NSG を使用する場合は、kube-system 名前空間から Azure OpenAI エンドポイントへの送信 HTTPS トラフィック (ポート 443) が許可されていることを確認します。送信トラフィックをブロックしているネットワークポリシーがないことを確認します。
```
kubectl get networkpolicies -n kube-system
```

アプリの登録とEntra ID認証エラー

Symptom: Microsoft Entra ID (MSAL) ログインフローが失敗するか、ログインリダイレクトがエラーを返すか、ポッドログに 44444444-4444-4444-4444-444444444444 のプレースホルダー値 ENTRA_CLIENT_ID が表示されます。

原因： アプリの登録が正しく構成されていないか、拡張機能のデプロイ中に ENTRA_CLIENT_ID が設定されませんでした。

解決方法:

ポッドログに 44444444-4444-4444-4444-444444444444プレースホルダーの値が表示されている場合は、実際のアプリ登録クライアント ID で拡張機能を更新します。

az k8s-extension update \
  --cluster-name $CLUSTER_NAME \
  --resource-group $RESOURCE_GROUP \
  --cluster-type managedClusters \
  --name containernetworkingagent \
  --configuration-settings config.ENTRA_CLIENT_ID=<your-app-registration-client-id>

ログインコールバックが redirect_uri mismatch エラーで失敗した場合は、Azure ポータルの App Registrations > Your App > Authentication > Redirect URI でリダイレクト URI を確認します。ポート転送ローカルアクセスの場合、URI は http://localhost:8080/auth/callbackする必要があります。

注

現在、 localhost リダイレクト URI のみがサポートされています。パブリック LoadBalancer URL は、リダイレクト URI ではサポートされていません。
アプリ登録に、必要な Microsoft Graph委任されたアクセス許可 (openid、profile、User.Read、offline_access) があることを確認します。管理者の同意が必要な場合は、次の条件を付与します。
```
az ad app permission admin-consent --id <app-registration-object-id>
```

ポッドログで認証固有のエラーを確認します。

kubectl logs -n kube-system -l app=container-networking-agent | grep -i "auth\|msal\|entra"

起動時に環境変数が見つからない

症状： エージェントポッドは、起動時に次の状態で直ちにクラッシュします。

RuntimeError: Missing required Azure OpenAI environment variable(s): AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT, AZURE_OPENAI_API_VERSION.

原因： 拡張機能のデプロイ時に、1 つ以上の必要な構成値が設定されませんでした。

解決方法:

ConfigMap でプレースホルダー値または不足している設定を確認します。
```
kubectl get configmap -n kube-system -l app=container-networking-agent -o yaml
```

これらの必須変数が実際の値で設定されていることを確認します ( 00000000-0000-0000-0000-000000000000のようなプレースホルダーではありません)。

Variable	説明	例
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI リソースエンドポイント	`https://your-instance.openai.azure.com/`
`AZURE_OPENAI_DEPLOYMENT`	モデル展開名	`gpt-4o`
`AZURE_OPENAI_API_VERSION`	API バージョン	`2025-03-01-preview`
`AZURE_CLIENT_ID`	マネージドアイデンティティクライアントID	UUID（ユニバーサリー・ユニーク・アイデンティファイア）
`AZURE_TENANT_ID`	Azure テナント ID	UUID（ユニバーサリー・ユニーク・アイデンティファイア）
`AZURE_SUBSCRIPTION_ID`	Azure サブスクリプション ID	UUID（ユニバーサリー・ユニーク・アイデンティファイア）
`AKS_CLUSTER_NAME`	AKS クラスター名	クラスター名
`AKS_RESOURCE_GROUP`	クラスターのリソースグループ	該当するリソースグループ

値にプレースホルダーが表示されている場合は、正しい設定で拡張機能を更新します。

az k8s-extension update \
  --cluster-name $CLUSTER_NAME \
  --resource-group $RESOURCE_GROUP \
  --cluster-type managedClusters \
  --name containernetworkingagent \
  --configuration-settings config.AZURE_OPENAI_ENDPOINT=<your-endpoint> \
  --configuration-settings config.AZURE_OPENAI_DEPLOYMENT=<your-deployment>

エージェントポッドが実行されていないか、異常終了している

症状： エージェントポッドは、 CrashLoopBackOff、 Error、または Pending 状態です。

Cause: 構成の誤り、OpenAI 接続Azure不足、またはクラスターリソースの不足。

解決方法:

ポッドイベントで即時のエラーを確認します。

kubectl describe pod -n kube-system -l app=container-networking-agent

ポッドログでエラーメッセージを確認します。

kubectl logs -n kube-system -l app=container-networking-agent --tail=200

ログメッセージを既知の原因と照合します。

ログメッセージ	原因	修正
`Missing required Azure OpenAI environment variable(s)`	ConfigMap にはプレースホルダー値があります	を使用して正しい値を設定します。 `az k8s-extension update`
`bootstrap.validation_agent_failed`	Azure OpenAI に接続できない	ネットワーク、エンドポイント URL、およびマネージド ID RBAC を確認する
`AKS MCP binary not found`	画像にバイナリが見つからない	公式の拡張機能イメージを`acnpublic.azurecr.io`から使用する
`FailedMount` / ボリュームマウントエラー	Hubble 証明書シークレットが見つからない	`hubble.enabled=false`を使用してデプロイするか、ACNS が有効になっていることを確認する
`Token acquisition failed`	ワークロード ID が構成されていません	サービスアカウントの注釈とフェデレーション資格情報を確認する

Azure OpenAI エンドポイントにクラスターから到達可能であることを確認します。エグレス制限を使用する場合は、kube-system 名前空間から Azure OpenAI エンドポイントへの送信 HTTPS (ポート 443) が許可されていることを確認します。

readiness probe のエラー

症状： ポッドは Running の状態ですが、0/1 の準備完了状態を示しています。 /ready エンドポイントは HTTP 503 を返します。

原因： 1 つ以上のスタートアップチェックが完了していません。ウォームアップエージェントプールがまだ初期化されていないか、クラスターのプロパティにエラーがあるか、事前にウォーム化されたエージェントが使用できません。

解決方法:

ウォームアッププールが事前にウォームアップされたエージェントを作成するまで、デプロイ後最大 2 から 3 分待ちます。

特定のエラーの理由について、準備状況の応答を確認します。

kubectl port-forward svc/container-networking-agent-service -n kube-system 8080:80
curl -s http://localhost:8080/ready | jq

ポッドのログを確認し、ウォームアップに関連する問題がないかチェックします。
```
kubectl logs -n kube-system -l app=container-networking-agent | grep -i "warmup\|ready\|error"
```
クラスターのプロパティが失敗した場合は、拡張機能の構成で AKS_CLUSTER_NAME、 AKS_RESOURCE_GROUP、および AZURE_SUBSCRIPTION_ID が正しく設定されていることを確認します。

ウォームアッププールが動作に失敗し続けている

症状： ポッドはRunning状態ですが、準備が整うことはありません。ポッドログには、数分待機した後でも "Failed to create warmed agent" エラーが繰り返し表示されます。

原因： バックグラウンドウォームアッププールで、事前にウォームされたエージェントインスタンスを作成できない。これは通常、未解決の Azure OpenAI 接続の問題またはエージェントの作成を妨げる MCP 初期化エラーが原因で発生します。

解決方法:

ログで、基になる特定のエラーを確認します。

kubectl logs -n kube-system -l app=container-networking-agent | grep -i "warmup\|Failed to create"

エラーを修正方法と照らし合わせる。

ログのエラー	修正
`401 Unauthorized` または `403 Forbidden`	Azure OpenAI 接続の問題を参照し、マネージド ID ロールの割り当てを確認します
`Token acquisition failed`	ID とアクセス許可のエラーを参照してください
`404 Not Found` エンドポイント上	ConfigMap で `AZURE_OPENAI_ENDPOINT` と `AZURE_OPENAI_DEPLOYMENT` を確認する
`AKS MCP binary not found`	エージェントポッドが稼働していないかクラッシュしている

根本的な問題が解決されると、ウォームアッププールは自動的に再試行を行います。根本原因を修正した後もエラーが解決しない限り、ポッドを再起動する必要はありません。

Hubble コマンドが失敗する

症状： エージェントは、Hubble 関連の診断のエラーを報告するか、Hubble フロー分析を使用できません。

原因： クラスターで Advanced Container Networking Services (ACNS) または Cilium データプレーンが有効になっていません。

解決方法:

クラスターで ACNS が使用されていない場合は、 hubble.enabled=false と config.AKS_MCP_ENABLED_COMPONENTS=kubectlを使用して拡張機能をデプロイします。エージェントは引き続き、Hubble を使用せずに DNS、パケットドロップ、標準の Kubernetes ネットワーク診断を提供します。
Hubble を有効にするには、クラスターで Azure CNI powered by Cilium を使用し、Advanced Container Networking Services (ACNS) を有効にする必要があります。
クラスターで Hubble が実行されていることを確認します。
```
kubectl get pods -n kube-system -l k8s-app=hubble-relay
```
ポッドが返されない場合、Hubble は有効になっていません。クラスターで ACNS を有効にするか、拡張機能の構成で hubble.enabled=false を設定します。

チャットレート制限

症状： チャット要求は、 X-RateLimit-* または X-LLM-RateLimit-* 応答ヘッダーを含む HTTP 429 を返します。

原因： 組み込みのレートリミッターは、サービスを保護するための要求を調整します。

解決方法:

Container Network Insights エージェントには、次の 3 つのレート制限レイヤーがあります。

レートリミッター	デフォルト	行動
チャット	1秒あたり13リクエスト、バーストは13件	チャットメッセージのセッションごとの制限
Auth	1 要求/秒、バーストは 20	ログインエンドポイントとコールバックエンドポイントに対して制限をかける
LLM (アダプティブ)	100 件の要求/秒のグローバル制限はユーザー間で共有されます。	アクティブなユーザーごとの公平な共有を使用したグローバルスループット制御

チャット 429 エラーの場合: メッセージの頻度を減らし、レート制限バケットが補充されるまで待ちます。
LLM 429 エラーの場合: Azure ポータルで Azure OpenAI Tokens-Per-Minute (TPM) クォータを確認します。より高いスループットが必要な場合は、Cognitive Services > クォータ の引き上げを要求してください。

チャットメッセージは送信されましたが、応答なし

症状： チャットメッセージは送信されますが、応答は表示されません。要求がハングするか、最終的にタイムアウトエラーが返されます。

Cause: Azure OpenAI はレート制限または到達不能である可能性があり、事前ウォーミングされたエージェントがまだ使用できないか、実行時間の長い診断コマンドがまだ実行されている可能性があります。

解決方法:

ポッドにアクティブなセッションがあるかどうか、およびエージェントが割り当てられているかどうかを確認します。
```
kubectl port-forward svc/container-networking-agent-service -n kube-system 8080:80
curl -s http://localhost:8080/api/status/sessions | jq
```

ポッドログでエラーパターンを確認します。

kubectl logs -n kube-system -l app=container-networking-agent --tail=50

ログインジケータ	原因	修正
`429` エラー	Azure OpenAI 料金制限あり	レート制限がリセットされるまで待ちます。TPM クォータを確認する
`"No pre-warmed agents available"`	ウォームアップ用プールの準備が整っていない	初期化を待ちます。ウォームアッププールが失敗し続けるのを確認する
接続のタイムアウト	ネットワークまたは NSG の問題	ポッドネットワーク、DNS、NSG の規則を確認する

要求が 2 分後も保留中の場合は、新しい会話を開始し、最初に単純なクエリを送信して (たとえば、"既定の名前空間にポッドを一覧表示する")、複雑な診断の質問をする前にエージェントが応答しているかどうかを確認します。

最初の要求が遅い

症状： デプロイまたはポッドの再起動後の最初のチャットメッセージは、応答に 10 ~ 30 秒かかります。

原因： Container Network Insights エージェントは、待ち時間を短縮するために、事前にウォーム化されたエージェントのプールを維持します。ポッドの再起動後、ウォームアッププールは各エージェントを初期化する時間を必要とします。これには、MCP プラグインの起動、Azure資格情報のセットアップ、AI フレームワークの初期化が必要です。

解像度： これは予期される動作です。 /ready エンドポイントが HTTP 200 を返すのを待ってから、少なくとも 1 つの事前ウォーミングされたエージェントが使用可能であることを確認する要求を送信します。後続の要求では、事前にウォームされたプールが使用され、より高速に応答します (通常、単純なクエリの場合は 5 ~ 10 秒)。

kubectl port-forward svc/container-networking-agent-service -n kube-system 8080:80
curl -s http://localhost:8080/ready | jq

複雑な診断の応答が遅い

症状： 診断応答の完了には 30 秒から 2 分かかります。

Cause: 複数ステップの診断には、OpenAI をAzureするための最初の LLM 分類呼び出し、クラスターに対して複数の kubectl/cilium/hubble コマンドが実行され、収集された証拠の最終的な LLM 分析など、連続した操作が含まれます。各ステップで待機時間が追加されます。

解像度： これは、複雑な診断に必要です。次の表は、一般的な応答時間を示しています。

クエリの種類	予想される時間
単純なクラスタークエリ (ポッド、サービスの一覧表示)	5 ~ 10 秒
単一ドメイン診断 (特定のポッド DNS チェック、サービスエンドポイントチェック)	15 ~ 30 秒
マルチノードパケットドロップ分析または広範なネットワーク診断	30 ~ 120 秒

待機時間を短縮するには:

広範な質問ではなく、既知の症状を対象とする特定のクエリを使用します。たとえば、「名前空間my-svcのサービスmy-nsの DNS 解決を確認する」は、"すべてのネットワークの問題を診断する" よりも高速です。
ネットワークのラウンドトリップ時間を最小限に抑えるために、Azure OpenAI リソースが AKS クラスターと同じAzure リージョンにあることを確認します。
Azure OpenAI TPM クォータを確認します。クォータが大きいほど、より並列なトークン処理が可能になります。

診断コマンドのタイムアウト

症状： エージェントは、コマンドがタイムアウトしたと報告するか、チャットが 10 分を超えて応答を停止してからエラーを返します。

原因： 診断コマンド (kubectl、cilium、hubble) の既定のタイムアウトは 600 秒 (10 分) です。大規模なクラスター内のすべてのノードから統計を収集するなど、広範なクエリがこの制限を超える可能性があります。

解決方法:

クラスター全体ではなく、特定のノード、ポッド、または名前空間にクエリのスコープを設定します。例えば次が挙げられます。
- "すべてのノードでパケットドロップを確認する代わりに"
- 質問: "ノード <specific-node-name>でのパケットドロップの確認"
クエリの種類でタイムアウトが一貫して発生する場合、クラスターのパフォーマンスまたは接続の問題が発生し、コマンドの応答が個別に遅くなる可能性があります。

ポッドログでタイムアウト関連のエントリを確認します。

kubectl logs -n kube-system -l app=container-networking-agent | grep -i "timeout\|timed out"

ポッドの再起動後にセッションデータが失われる

症状： ポッドの再起動後、すべてのチャット履歴とアクティブなセッションが消えます。

原因： セッションデータはメモリ内にのみ格納されます。ポッドが再起動すると、すべてのデータが失われます。

解像度： これは、現在のアーキテクチャで想定される動作です。ポッドの再起動後に新しいセッションを開始します。

セッションが予期せず期限切れになる

症状： アクティブなセッション中に警告なしでログアウトするか、拡張機能を使用していたにもかかわらず、非アクティブな期間が経過するとセッションが終了します。

原因： Container Network Insights エージェントは、セキュリティのためにセッションタイムアウトを強制します。 2 つの独立した制限が適用されます。

タイムアウトの種類	デフォルト	行動
無操作タイムアウト	30 分	30 分間アクティビティがない場合、セッションは終了します
絶対タイムアウト	8 時間	8 時間後のアクティビティに関係なくセッションが終了する

解像度： もう一度ログインして、新しいセッションを開始します。期限切れのセッションからのチャット履歴は回復できません。

注

セッションデータはメモリ内にのみ格納されます。アクティブなセッション内であっても、ポッドの再起動によってすべてのセッション履歴がクリアされます。

多くの交換の後にチャットコンテキストが失われる

症状： 約 15 回の交換の後、エージェントは会話の以前の部分を忘れたか、セッションの前の部分からのコンテキストを参照していないようです。

Cause: Container Network Insights エージェントは、Azure OpenAI トークンの制限内に留まるように会話履歴を要約します。コンテキストウィンドウが約 15 メッセージに達すると、古いメッセージは自動的に生成された概要に置き換えられます。最新のメッセージと概要は保持され、モデルに渡されます。

解像度： これは予期される動作です。要約プロセスでは、Azure OpenAI トークンの制限を管理しながら、主要な診断コンテキストが保持されます。会話のはるかに早い段階から何かを参照する必要がある場合:

関連するコンテキストを繰り返します。"以前に X が見つかりました。さらに調査できますか?
既知の結果を簡潔に要約して、新しい会話を開始します。

会話の制限に達しました

症状： インターフェイスには、新しい会話を作成できない、または最も古い会話が明示的に削除されずに消えるというエラーが表示されます。

原因： 各ユーザーアカウントは、アクティブな会話が 20 個に制限されています。この制限に達すると、最も古い 2 つの会話が自動的に削除され、カウントが 18 (20 会話の制限の 90%) に達した時点から開始されます。

解像度： この自動クリーンアップは想定される動作です。新しい会話を作成できない場合は、バックグラウンドクリーンアップが実行されるまで少し待ってから、もう一度やり直してください。最も最近使用されていない 2 つの会話が自動的に削除されます。

注

会話はポッドごとにメモリ内に格納されます。ポッドが再起動すると、存在する数に関係なく、すべての会話が失われます。

クラッシュ後も DaemonSet のデバッグが継続する

症状：rx-troubleshooting-debug DaemonSet は、診断セッションの後も kube-system 名前空間に残ります。

原因： Container Network Insights エージェントは、パケットドロップ診断中に軽量デバッグ DaemonSet をデプロイします。この診断中にエージェントポッドが予期せずクラッシュした場合、クリーンアップ手順は実行されません。

解像度： DaemonSet を手動で削除します。

kubectl delete ds rx-troubleshooting-debug -n kube-system

パケットドロップ診断に失敗する

症状： エージェントにパケットドロップの調査を依頼すると、診断ポッドのデプロイエラーが報告されるか、ノードレベルの統計情報を収集できません。

原因： パケットドロップ診断では、軽量の DaemonSet (rx-troubleshooting-debug) を各ノードにデプロイして、ホストレベルのネットワーク統計 (ethtool 統計、ソフトネットカウンター、リングバッファーの状態) を収集します。エージェントのサービスアカウントに、 kube-systemで DaemonSet を作成するアクセス許可がない場合、またはノードがホストネットワーク統計情報を収集するために必要な特権アクセスをブロックしている場合、エラーが発生します。

解決方法:

DaemonSet が作成されたかどうかを確認します。

kubectl get daemonset -n kube-system rx-troubleshooting-debug

存在しない場合、デプロイ手順は失敗しました。ポッドログを確認します。

kubectl logs -n kube-system -l app=container-networking-agent | grep -i "daemonset\|rx\|packet\|error"

DaemonSet が作成されたが、そのポッドが起動していない場合は、原因を見つけるためにそれらを記述します。
```
kubectl describe pods -n kube-system -l app=cna-diagnostic
```
エージェントに割り当てられている ClusterRole に DaemonSet 作成アクセス許可が含まれていることを確認します。
```
kubectl get clusterrole -l app=container-networking-agent -o yaml | grep -A2 daemonset
```
DaemonSet が失敗した実行から残っている場合は、手動で削除し、エージェントに再試行を依頼します。
```
kubectl delete daemonset -n kube-system -l app=cna-diagnostic
```

DNS 診断で不完全または結果が返されない

症状： DNS の問題のトラブルシューティングを行うとき、エージェントは部分的な診断データを返し、DNS チェックを実行しているエラーを報告するか、結果なしで調査を終了します。

原因： エージェントの DNS 診断ツールは、解決テストを実行し、クラスター内から CoreDNS を検査します。エージェントのサービスアカウントにクラスターレベルの読み取りアクセス権がない場合、CoreDNS ポッドにアクセスできない場合、または個々のコマンドがコマンドごとの 30 秒のタイムアウトに達した場合、不完全な結果が発生する可能性があります。

解決方法:

CoreDNS が実行されていることを確認します。
```
kubectl get pods -n kube-system -l k8s-app=kube-dns
```
CoreDNS ポッドが実行されていない場合は、それが根本原因です。詳細を説明してください。
```
kubectl describe pods -n kube-system -l k8s-app=kube-dns
```
クラスターにマネージド ID がAzure Kubernetes Service Cluster User Roleの割り当てられていることを確認します。このロールにより、エージェントは kubeconfig を取得し、kubectl コマンドを実行できます。
```
az role assignment list --assignee <identity-principal-id> --all -o table
```
DNS チェック中にエージェントがコマンドタイムアウトを報告する場合は、質問の範囲を絞り込みます。たとえば、"すべての DNS の問題を診断する" の代わりに、"名前空間の<pod-name>でポッド<namespace>の DNS 解決を確認してください" というメッセージを表示します。

エージェントが調査途中で停止する

症状： エージェントは診断調査を開始しますが、根本原因分析や最終レポートを提供せずに、診断調査を完了する前に停止します。

原因： 複数の要因によって、複数ステップの調査が中断される可能性があります。

診断コマンドがタイムアウトしました。
Azure OpenAI のレート制限またはトークン制限に調査の途中で達しました。
会話履歴コンテキストウィンドウが集計しきい値に達したため、エージェントは現在のプランのスレッドを失いました。

解決方法:

エージェントに同じ会話で続行するように依頼します。 "Please continue the investigation" または "What other checks can you run?" エージェントは現在の状態から再開できます。
タイムアウトが原因である場合は、次のクエリの範囲をより狭くします。たとえば、完全なクラスターではなく、"特定の名前空間 <name>を確認する" などです。
レート制限のために調査が停止した場合は、少し待ってからエージェントに続行するように依頼します。
新たに開始するには、新しい会話を開き、既に見つかった内容の簡潔な概要を提供します。"名前空間 X で DNS 解決が失敗したことを確認しました。その名前空間の NetworkPolicy を調査できますか?

クラスターでワークロード ID が有効になっていない

Symptom: フェデレーション資格情報のセットアップが失敗するか、エージェントポッドがAzureに対して認証できません。ポッドログには、 "Failed to acquire token" または "AADSTS..." エラーが表示されます。

原因： AKS クラスターは、OIDC 発行者またはワークロード ID が有効になっていない状態で作成されました。

解像度：az aks update コマンドを使用して、既存のクラスターで両方の機能を有効にします。

az aks update \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --enable-oidc-issuer \
  --enable-workload-identity

有効にした後、デプロイガイドのフェデレーション資格情報のセットアップ手順を再実行して、マネージド ID を Kubernetes サービスアカウントにリンクします。

Azure OpenAI モデルは、選択したリージョンでは使用できません

Symptom: Azure OpenAI デプロイの作成が失敗するか、デプロイ直後にエンドポイントまたはモデルエラーで Container Network Insights エージェントの起動が失敗します。

Cause: 選択したAzure OpenAI モデルは、選択したAzureリージョンでは使用できません。

解決方法:

リージョンで使用可能なモデルを確認します。

az cognitiveservices model list -l <your-region> --output table

ターゲットモデルが使用可能なリージョンを使用します。現在の可用性については、Azure OpenAI モデルリージョンのサポートリファレンスを参照してください。
あなたのサブスクリプションに、モデル用のトークン毎分 (TPM) クォータが十分にあることを確認してください。クォータエラーが発生してモデルのデプロイが失敗した場合は、Azure ポータルの Cognitive Services > Quotas でクォータの引き上げを要求します。

クイック診断コマンド

一般的な問題をすばやく診断するには、次のコマンドを使用します。

# ──── Pod Status ────
kubectl get pods -n kube-system -l app=container-networking-agent
kubectl describe pod -n kube-system -l app=container-networking-agent
kubectl top pod -n kube-system -l app=container-networking-agent

# ──── Application Logs ────
kubectl logs -n kube-system -l app=container-networking-agent --tail=200
kubectl logs -n kube-system -l app=container-networking-agent -f              # Stream live
kubectl logs -n kube-system -l app=container-networking-agent | grep ERROR     # Errors only

# ──── Health Checks (requires port-forward) ────
kubectl port-forward svc/container-networking-agent-service -n kube-system 8080:80
curl -s http://localhost:8080/ready | jq
curl -s http://localhost:8080/live | jq
curl -s http://localhost:8080/api/status/sessions | jq

# ──── Configuration ────
kubectl get configmap -n kube-system -l app=container-networking-agent -o yaml
kubectl get serviceaccount container-networking-agent-reader -n kube-system -o yaml

# ──── Workload Identity ────
kubectl describe serviceaccount container-networking-agent-reader -n kube-system
az identity show --name $IDENTITY_NAME -g $RESOURCE_GROUP --query "{clientId:clientId, principalId:principalId}"

# ──── RBAC ────
az role assignment list --assignee <principal-id> --output table

# ──── Extension Status ────
az k8s-extension show \
  --cluster-name $CLUSTER_NAME \
  --resource-group $RESOURCE_GROUP \
  --cluster-type managedClusters \
  --name containernetworkingagent \
  --query "{state:provisioningState, version:version}" -o table

# ──── Cleanup Stuck Resources ────
kubectl delete daemonset rx-troubleshooting-debug -n kube-system    # Leftover diagnostic DaemonSet
kubectl delete pod -n kube-system -l app=container-networking-agent    # Force pod restart

次のステップ

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-04-16

AKS での Container Network Insights エージェントのトラブルシューティング

拡張機能のインストールが失敗する

ID とアクセス許可のエラー

Azure OpenAI の接続に関する問題

アプリの登録とEntra ID認証エラー

起動時に環境変数が見つからない

エージェント ポッドが実行されていないか、異常終了している

readiness probe のエラー

ウォームアップ プールが動作に失敗し続けている

Hubble コマンドが失敗する

チャットレート制限

チャット メッセージは送信されましたが、応答なし

最初の要求が遅い

複雑な診断の応答が遅い

診断コマンドのタイムアウト

ポッドの再起動後にセッション データが失われる

セッションが予期せず期限切れになる

多くの交換の後にチャット コンテキストが失われる

会話の制限に達しました

クラッシュ後も DaemonSet のデバッグが継続する

パケットドロップ診断に失敗する

DNS 診断で不完全または結果が返されない

エージェントが調査途中で停止する

クラスターでワークロード ID が有効になっていない

Azure OpenAI モデルは、選択したリージョンでは使用できません

クイック診断コマンド

次のステップ

フィードバック

その他のリソース

エージェントポッドが実行されていないか、異常終了している

ウォームアッププールが動作に失敗し続けている

チャットメッセージは送信されましたが、応答なし

ポッドの再起動後にセッションデータが失われる

多くの交換の後にチャットコンテキストが失われる