AKS クラスター拡張機能をデプロイするときのエラーのトラブルシューティング
この記事では、Microsoft Azure Kubernetes Service (AKS) のクラスター拡張機能をデプロイするときに発生するエラーのトラブルシューティング方法について説明します。
拡張機能の作成エラー
エラー: エージェントから時間内に応答を取得できません
このエラーは、Azure サービスがクラスター拡張機能エージェントから応答を受け取らない場合に発生します。 この状況は、AKS クラスターが Azure との接続を確立できないために発生する可能性があります。
原因 1: クラスター拡張エージェントとマネージャー ポッドが初期化されていない
クラスター拡張エージェントとマネージャーは、Kubernetes アプリケーションのライフサイクルを管理する重要なシステム コンポーネントです。 クラスター拡張エージェントとマネージャー ポッドの初期化は、次の問題のために失敗する可能性があります。
- リソースの制限事項
- ポリシーの制限
- ノードテイント(例:
NoSchedule
解決策 1: クラスター拡張機能エージェントとマネージャー ポッドが正しく動作することを確認する
この問題を解決するには、クラスター拡張機能エージェントとマネージャー ポッドが正しくスケジュールされ、開始できることを確認します。 ポッドが読み取り不能な状態でスタックしている場合は、次kubectl describe pod
のコマンドを実行してポッドの説明をチェックして、基になる問題の詳細を取得します (たとえば、スケジューリングを妨げるテイント、メモリ不足、ポリシー制限)。
kubectl describe pod -n kube-system extension-operator-{id}
コマンド出力サンプルを次に示します。
kube-system extension-agent-55d4f4795f-sqx7q 2/2 Running 0 2d19h
kube-system extension-operator-56c8d5f96c-nvt7x 2/2 Running 0 2d19h
ARC 接続クラスターの場合は、次のコマンドを実行してポッドの説明をチェックします。
kubectl describe pod -n azure-arc extension-manager-{id}
コマンド出力サンプルを次に示します。
NAMESPACE NAME READY STATUS RESTARTS AGE
azure-arc cluster-metadata-operator-744f8bfbd4-7pssr 0/2 ImagePullBackOff 0 6d19h
azure-arc clusterconnect-agent-7557d99d5c-rtgqh 0/3 ImagePullBackOff 0 6d19h
azure-arc clusteridentityoperator-9b8b88f97-nr8hf 0/2 ImagePullBackOff 0 6d19h
azure-arc config-agent-6d5fd59b8b-khw2d 0/2 ImagePullBackOff 0 6d19h
azure-arc controller-manager-5bc97f7db6-rt2zs 0/2 ImagePullBackOff 0 6d19h
azure-arc extension-events-collector-7596688867-sqzv2 0/2 ImagePullBackOff 0 6d19h
azure-arc extension-manager-86bbb949-6s59q 0/3 ImagePullBackOff 0 6d19h
azure-arc flux-logs-agent-5f55888db9-wnr4c 0/1 ImagePullBackOff 0 6d19h
azure-arc kube-aad-proxy-646c475dcc-92b86 0/2 ImagePullBackOff 0 6d19h
azure-arc logcollector-5cbc659bfb-9v96d 0/1 ImagePullBackOff 0 6d19h
azure-arc metrics-agent-5794866b46-j9949 0/2 ImagePullBackOff 0 6d19h
azure-arc resource-sync-agent-6cf4cf7486-flgwc 0/2 ImagePullBackOff 0 6d19h
クラスター拡張エージェントとマネージャー ポッドが運用可能で正常な場合、Kubernetes アプリケーションをインストールして管理するための Azure サービスとの通信を確立します。
原因 2: 問題がエグレス ブロックまたはファイアウォールに影響する
クラスター拡張エージェントとマネージャー ポッドが正常で、"エージェントから時間内に応答を取得できません" というエラーが引き続き発生する場合は、エグレス ブロックまたはファイアウォールの問題が存在する可能性があります。 この問題により、クラスター拡張機能エージェントとマネージャー ポッドが Azure と通信できなくなる可能性があります。
解決策 2: ネットワークの前提条件が満たされていることを確認する
この問題を解決するには、「Azure Kubernetes Service (AKS) クラスターの送信ネットワークと FQDN 規則」で説明されているネットワークの前提条件に従っていることを確認します。
原因 3: トラフィックが承認されていません
拡張エージェントは、データ プレーン サービス エンドポイントへの呼び出しを <region>.dp.kubernetesconfiguration.azure.com
失敗しました。 このエラーにより、拡張機能エージェント ポッド ログに "Errorcode: 403、Message This traffic is not authorized" エントリが生成されます。
kubectl logs -n kube-system extension-agent-<pod-guid>
{ "Message": "2024/02/07 06:04:43 \"Errorcode: 403, Message This traffic is not authorized., Target /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/provider/managedclusters/clusters/<cluster-name>/configurations/getPendingConfigs\"", "LogType": "ConfigAgentTrace", "LogLevel": "Information", "Environment": "prod", "Role": "ClusterConfigAgent", "Location": "<region>, "ArmId": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerService/managedclusters/<cluster-name>", "CorrelationId": "", "AgentName": "ConfigAgent", "AgentVersion": "1.14.5", "AgentTimestamp": "2024/02/07 06:04:43.672" }
{ "Message": "2024/02/07 06:04:43 Failed to GET configurations with err : {\u003cnil\u003e}", "LogType": "ConfigAgentTrace", "LogLevel": "Information", "Environment": "prod", "Role": "ClusterConfigAgent", "Location": "<region>", "ArmId": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerService/managedclusters/<cluster-name>", "CorrelationId": "", "AgentName": "ConfigAgent", "AgentVersion": "1.14.5", "AgentTimestamp": "2024/02/07 06:04:43.672" }
このエラーは、Azure Arc 対応 Kubernetes の拡張機能のデータ プレーンに既存の PrivateLinkScope が存在し、仮想ネットワーク (またはプライベート DNS サーバー) が Azure Arc 対応 Kubernetes と AKS マネージド クラスターの間で共有されている場合に発生します。 このネットワーク構成により、拡張データ プレーンからの AKS 送信トラフィックも、パブリック IP アドレスではなく同じプライベート IP アドレスを経由してルーティングされます。
AKS クラスターで次の nslookup コマンドを実行して、データ プレーン エンドポイントが解決する特定のプライベート IP アドレスを取得します。
PS D:\> kubectl exec -it -n kube-system extension-agent-<pod-guid> -- nslookup <region>.dp.kubernetesconfiguration.azure.com
Non-authoritative answer:
<region>.dp.kubernetesconfiguration.azure.com canonical name = <region>.privatelink.dp.kubernetesconfiguration.azure.com
Name: <region>.privatelink.dp.kubernetesconfiguration.azure.com
Address: 10.224.1.184
Azure portalでプライベート IP アドレスを検索すると、検索結果は、仮想ネットワーク、プライベート DNS ゾーン、プライベート DNS サーバーなどの正確なリソースを指します。 このリソースには、Azure Arc 対応 Kubernetes の拡張データ プレーン用に構成されたプライベート エンドポイントがあります。
解決策 3.1: (推奨) 個別の仮想ネットワークを作成する
この問題を解決するには、Azure Arc 対応 Kubernetes と AKS コンピューティング用に個別の仮想ネットワークを作成することをお勧めします。
解決策 3.2: CoreDNS オーバーライドを作成する
お客様の状況で推奨される解決策が不可能な場合は、拡張データ プレーン エンドポイントの CoreDNS オーバーライドを作成して、パブリック ネットワークを経由します。 CoreDNS をカスタマイズする方法の詳細については、「Azure Kubernetes Serviceを使用して CoreDNS をカスタマイズする」の「ホスト プラグイン」セクションを参照してください。
CoreDNS オーバーライドを作成するには、次の手順に従います。
コマンドを実行して、拡張データ プレーン エンドポイントのパブリック IP アドレスを
nslookup
見つけます。 AKS クラスターの場所に基づいてリージョン (例:eastus2euap
) を変更してください。nslookup <region>.dp.kubernetesconfiguration.azure.com Non-authoritative answer: Name: clusterconfig<region>.<region>.cloudapp.azure.com Address: 20.39.12.229 Aliases: <region>.dp.kubernetesconfiguration.azure.com <region>.privatelink.dp.kubernetesconfiguration.azure.com <region>.dp.kubernetesconfiguration.trafficmanager.net
既存の coreDNS 構成のバックアップを作成します。
kubectl get configmap -n kube-system coredns-custom -o yaml > coredns.backup.yaml
リージョン (たとえば
eastus2euap
) データ プレーン エンドポイントのパブリック IP アドレスへのマッピングをオーバーライドします。 これを行うには、 corednsms.yaml という名前の YAML ファイルを作成し、次の構成例を新しいファイルにコピーします。 (ご利用の環境の値を使用して、アドレスとホスト名を必ず更新してください)。apiVersion: v1 kind: ConfigMap metadata: name: coredns-custom # This is the name of the configuration map that you can overwrite with your changes. namespace: kube-system data: extensionsdp.override: | # You can select any name here, but it must have the .override file name extension. hosts { 20.39.12.229 <region>.dp.kubernetesconfiguration.azure.com fallthrough }
ConfigMap を作成するには、 コマンドを実行し
kubectl apply
、YAML マニフェスト ファイルの名前を指定します。kubectl apply -f corednsms.yaml
ConfigMap を再読み込みし、Kubernetes Scheduler がダウンタイムなしで CoreDNS を再起動できるようにするには、 kubectl ロールアウト再起動 コマンドを実行します。
kubectl -n kube-system rollout restart deployment coredns
コマンドをもう
nslookup
一度実行して、データ プレーン エンドポイントが指定されたパブリック IP アドレスに解決されることを確認します。kubectl exec -it -n kube-system extension-agent-55d4f4795f-nld9q -- nslookup [region].dp.kubernetesconfiguration.azure.com Name: <region>.dp.kubernetesconfiguration.azure.com Address: 20.39.12.229
拡張機能エージェント ポッド ログは、"Errorcode: 403、メッセージ このトラフィックは承認されていません" というエラー エントリをログに記録しなくなりました。 代わりに、ログに "200" 応答コードが含まれている必要があります。
kubectl logs -n kube-system extension-agent-{id}
{ "Message": "GET configurations returned response code {200}", "LogType": "ConfigAgentTrace", "LogLevel": "Information", "Environment": "prod", "Role": "ClusterConfigAgent", "Location": "<region>", "ArmId": "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerService/managedclusters/<cluster-name>", "CorrelationId": "", "AgentName": "ConfigAgent", "AgentVersion": "1.14.5" }
エラー: クラスター内のすべてのノード プールが "CriticalAddonsOnly" に汚染されている場合、拡張ポッドをスケジュールできません
このエラーが発生すると、次のエントリが拡張機能エージェント ログに記録されます。
拡張ポッド エラー: 0/2 ノードを使用できます。2 ノードが、必要なテイント {CriticalAddonsOnly: true} でした。 preemption: 0/2 ノードを使用できます。2 プリエンプションはスケジューリングには役立ちません。
原因
このエラーは、ノード プールが汚染された AKS クラスター CriticalAddonsOnly
で拡張機能 (分散アプリケーション ランタイム (DAPR) など) を有効にしようとすると発生します。 この状況では、これらのテイントに対する容認が存在しないため、拡張ポッドはどのノードにもスケジュールされません。
エラー状況を表示するには、拡張機能ポッドを調べて、保留中の状態でスタックしていることを確認します。
kubectl get po -n {namespace-name} -l app.kubernetes.io/name={name}
NAME READY STATUS RESTARTS AGE
{podname} 0/2 Pending 0 2d6h
ポッドについて説明し、サポートされていないテイントが原因でスケジュールできないことを確認します。
kubectl describe po -n {namespace-name} {podname}
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Warning FailedScheduling 18s default-scheduler 0/2 nodes are available: 2 node(s) had untolerated taint {CriticalAddonsOnly: true}. preemption: 0/2 nodes are available: 2 Preemption is not helpful for scheduling.
注:
アプリケーション ワークロードに必要な場合を除き、テイント ノード プールに
CriticalAddOnsOnly
拡張機能をインストールしないことをお勧めします。単一ノード プール クラスターではテイントを
CriticalAddOnsOnly
使用しないことをお勧めします。 ノード プールが 1 つだけのクラスターでそのテイントを使用する場合、クラスター内のアプリケーション ポッドをスケジュールすることはできません。 クラスター内の少なくとも 1 つのノード プールにこのテイントがないことを確認します。 注釈を使用するタイミングのCriticalAddonsOnly
詳細については、「Azure Kubernetes Serviceのシステム ノード プールの管理 (AKS)」を参照してください。
解決策 1: ノード プールをクラスターに追加する
この問題を解決するには、テイントのない CriticalAddonsOnly
ノード プールをもう 1 つ追加します。 このアクションにより、拡張ポッドが新しいノード プールにスケジュールされます。
解決策 2: "CriticalAddonsOnly" テイントを削除する
可能で実用的な場合は、クラスターに拡張機能を CriticalAddonsOnly
インストールするためにテイントを削除できます。
Helm エラー
次のいずれかの Helm 関連のエラーが発生する可能性があります。
- リソースの準備を待機しているタイムアウト
- リポジトリ URL から Helm グラフをダウンロードできない
- 指定された値で Helm グラフのレンダリングに失敗しました
- クラスターにリソースが既に存在する
- Helm の操作は既に進行中です
エラー: リソースの準備を待機中にタイムアウトしました
Kubernetes アプリケーションのインストールが失敗し、次のエラー メッセージが表示されます。
ジョブが失敗しました: BackoffLimitExceeded
リソースが準備完了状態になるのを待ってタイムアウトしました。
原因
この問題には、次の一般的な原因があります。
リソースの制約: クラスター内のメモリまたは CPU リソースが不十分な場合、ポッド、ジョブ、またはその他の Kubernetes リソースの初期化が正常に行えなくなる可能性があります。 最終的には、この状況によりインストールがタイムアウトします。ポリシー制約やノードテイント (など
NoSchedule
) は、リソースの初期化をブロックすることもできます。アーキテクチャの不一致: Windows ベースのノード (またはその逆) で Linux ベースのアプリケーションをスケジュールしようとすると、Kubernetes リソースの初期化でエラーが発生する可能性があります。
構成設定が正しくない: 構成設定が正しくないと、ポッドの起動が妨げられます。
ソリューション
この問題を解決するには、次の手順を実行します。
リソースの確認: Kubernetes クラスターに十分なリソースがあることを確認し、ノードでポッドのスケジュール設定が許可されていることを確認します (テイントを考慮する必要があります)。 メモリと CPU リソースが要件を満たしていることを確認します。
イベントを検査する: Kubernetes 名前空間内のイベントを調べて、ポッド、ジョブ、またはその他の Kubernetes リソースが準備完了状態に達しない可能性がある潜在的な問題を特定します。
Helm のグラフと構成を確認する: 多くの Kubernetes アプリケーションでは、Helm チャートを使用してクラスターにリソースをデプロイします。 一部のアプリケーションでは、構成設定によるユーザー入力が必要な場合があります。 指定されたすべての構成値が正確であり、インストール要件を満たしていることを確認します。
エラー: リポジトリ URL から Helm グラフをダウンロードできません
このエラーは、エグレス ブロッキングの問題に加えて、クラスターとファイアウォールの間で発生する接続の問題によって発生します。 この問題を解決するには、「Azure Kubernetes Service (AKS) クラスターの送信ネットワークと FQDN 規則」を参照してください。
エラー: 指定された値で Helm グラフのレンダリングに失敗しました
このエラーは、Kubernetes アプリケーションが Helm チャートに依存して Kubernetes クラスター内にリソースをデプロイする場合に発生します。 これらのアプリケーションでは、インストール時に Helm 値として渡される構成設定を通じて提供されるユーザー入力が必要になる場合があります。 これらの重要な構成設定のいずれかが見つからないか正しくない場合、Helm グラフがレンダリングされない可能性があります。
この問題を解決するには、拡張機能またはアプリケーションのドキュメントをチェックして、アプリケーションのインストール中に必須の値を省略したか、正しくない値を指定したかを判断します。 これらのガイドラインは、構成値が見つからないか不正確なことが原因で発生する Helm グラフのレンダリングの問題を修正するのに役立ちます。
エラー: リソースはクラスターに既に存在します
このエラーは、クラスター内の Kubernetes リソースと、アプリケーションがインストールしようとしている Kubernetes リソースの間に競合が存在する場合に発生します。 エラー メッセージは通常、競合するリソースの名前を指定します。
競合するリソースが不可欠であり、置き換えることができない場合は、アプリケーションをインストールできない可能性があります。 リソースが重要ではなく、削除できる場合は、競合するリソースを削除してから、インストールを再試行してください。
エラー: Helm の操作は既に進行中です
このエラーは、特定のリリースに対して既に進行中の操作がある場合に発生します。 この問題を解決するには、10 分待ってから操作を再試行します。
お問い合わせはこちらから
質問がある場合やヘルプが必要な場合は、サポート要求を作成するか、Azure コミュニティ サポートにお問い合わせください。 Azure フィードバック コミュニティに製品フィードバックを送信することもできます。