Amazon EKS での Container Insights のトラブルシューティング
このセクションでは、Amazon EKS で Container Insights を設定または運用する際に発生する可能性がある一般的な問題について説明します。次の表と診断コマンドを使用して、OTel アプローチと Classic アプローチのどちらを使用するかにかかわらず、問題を特定して解決します。
アプローチ固有のセットアップガイダンスについては、「クイックスタート: Amazon EKS での OTel Container Insights」または「セットアップガイド (AWS CLI)」を参照してください。アプローチを比較するには、「Container Insights のアプローチを比較する」を参照してください。
メトリクスが CloudWatch に表示されない
ContainerInsights 名前空間にメトリクスが表示されない場合は、次の表を使用して原因を特定します。
| 症状 | 原因 | 解像度 |
|---|---|---|
ContainerInsights 名前空間にメトリクスがない |
IAM ロールに cloudwatch:PutMetricData アクセス許可がない |
CloudWatchAgentServerPolicy 管理ポリシーをエージェント IAM ロールにアタッチします。 |
| メトリクスが一部のノードには表示されるが、他のノードには表示されない | テイントのため、エージェント DaemonSet がすべてのノードでスケジュールされていない | エージェント DaemonSet に許容範囲を追加して、テイントノードでスケジューリングできるようにします。 |
| メトリクスの表示が停止する | エージェントポッドが OOMKilled または再起動中 | エージェントポッドリソースの仕様でメモリ制限を引き上げます。 |
| メトリクスが古いかゼロである | ネットワーク接続がブロックされている | VPC セキュリティグループをチェックし、CloudWatch VPC エンドポイントが存在することを確認します。 |
| 拡張メトリクスがない | エージェントが拡張オブザーバビリティ用に設定されていない | エージェント設定で enhancedObservability: true を設定します。 |
エージェントポッドが起動しない
エージェントポッドが起動に失敗するか、実行されていない状態のままである場合は、次の表を使用して問題を診断します。
| 症状 | 原因 | 解像度 |
|---|---|---|
ImagePullBackOff |
Amazon ECR に到達できないか、イメージタグが正しくない | イメージ URI を確認し、ノードが Amazon ECR にアクセスできることを確認します。 |
Pending |
ノードの CPU またはメモリが不十分 | エージェントポッドの仕様でノードグループをスケールするか、リソースリクエストを減らします。 |
CrashLoopBackOff |
無効な設定またはボリュームマウントの欠落 | 影響を受けるポッドで kubectl logs を実行して、ポッドログの設定エラーを確認します。 |
FailedScheduling |
ノードのアフィニティまたはテイントがスケジューリングを妨げる | DaemonSet 仕様で nodeSelector と許容範囲を確認します。 |
| 終了コード 1 | サービスアカウントに IRSA 注釈がない | サービスアカウントに eks.amazonaws.com/role-arn 注釈があることを確認します。 |
アドオンのインストール失敗
amazon-cloudwatch-observability アドオンのインストールに失敗した場合、または異常なステータスが報告された場合は、次の表を使用してトラブルシューティングを行います。
| 症状 | 原因 | 解像度 |
|---|---|---|
CREATE_FAILED |
リソースが以前のインストールと競合する | アドオンを作成するときに、競合するリソースを削除し、--resolve-conflicts OVERWRITE を使用します。 |
| OIDC プロバイダーが見つかりません | クラスターに IAM OIDC ID プロバイダーが存在しない | eksctl utils
associate-iam-oidc-provider を実行してプロバイダーを作成します。 |
| Version conflict | アドオンバージョンに Kubernetes バージョンと互換性がない | aws eks
describe-addon-versions を実行して、互換性のあるバージョンを一覧表示します。 |
DEGRADED のステータス |
アクセス許可がないため、ヘルスチェックに失敗する | ポッドログをチェックし、IRSA ロールに必要なポリシーがアタッチされていることを確認します。 |
ログ配信の問題
コンテナログが Amazon CloudWatch Logs に表示されない場合は、次の表を使用して原因を特定します。
| 症状 | 原因 | 解像度 |
|---|---|---|
| ロググループが存在しない | logs:CreateLogGroup アクセス許可がない |
Amazon CloudWatch Logs のアクセス許可をエージェントの IAM ロールに追加します。 |
| ロググループは存在するが、中身がない | エージェントはログ用に設定されていないか、リージョンが一致しない | エージェント設定にログ収集が含まれ、リージョンがクラスターリージョンと一致することを確認します。 |
| ログが 5 分以上遅れている | フラッシュ間隔が長すぎるか、ノードに負荷がかかっている | エージェント設定で force_flush_interval の値を減らします。 |
| パフォーマンスログがない | エージェントがアプリケーションログ専用に設定されている | Container Insights のパフォーマンスログセクションがエージェント設定に存在することを確認します。 |
移行固有の問題
Container Insights アプローチ間の移行中に問題が発生した場合は、次の表を使用します。完全な移行ワークフローについては、「移行ガイド」を参照してください。
| 症状 | 原因 | 解像度 |
|---|---|---|
| 並列実行中にメトリクスが重複する | 両方のアプローチがメトリクスを同時に発行している | これは、並列実行中に想定される動作です。新しいアプローチを検証した後、レガシーアプローチを無効にします。 |
| アプローチ間でメトリクス値が異なる | 計算方法が異なる | 小さな違い (5% 未満) は想定されます。大きな違いは、アプローチ間の設定の不一致を示します。 |
| ロールバックが失敗する | カスタム設定が再適用されなかった | ロールバックするときに、完全な設定値を再適用するようにします。 |
| 移行中にアラームが発生する | スイッチオーバー期間中のメトリクスにギャップがある | 影響を受けるアラームで、欠落しているデータ処理を一時的に notBreaching に設定します。 |
OTel Container Insights の問題
以下の問題は、OTel Container Insights アプローチに固有のものです。一般的な設定ガイダンスについては、「クイックスタート: Amazon EKS での OTel Container Insights」を参照してください。
| 症状 | 原因 | 解像度 |
|---|---|---|
| 403 Forbidden exporter エラー | IAM ロールに CloudWatch アクセス許可が付与されていない | CloudWatchAgentServerPolicy がエージェントロールにアタッチされていることを確認します。 |
| メトリクスエンドポイントで接続が拒否される | コレクターが kubelet に到達できない | ポッド仕様で hostNetwork: true が設定されていることを確認するか、サービスアカウントに必要なアクセス許可があることを確認します。 |
| メモリ使用量が多い | バッチプロセッサキューが大きすぎる | コレクター設定で batch/timeout と batch/send_batch_size の値を減らします。 |
| カスタムメトリクスが表示されない | 受信者がアプリケーションエンドポイント用に設定されていない | コレクター設定でアプリケーションメトリクスポートをターゲットとする Prometheus レシーバーを追加します。 |
一般的な診断コマンド
次のコマンドを使用して、Container Insights のデプロイに関する情報を収集します。
エージェントポッドのステータスを確認するには、次のコマンドを実行します。
kubectl get pods -n amazon-cloudwatch
エージェントポッドのログを表示するには、次のコマンドを実行します。
kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=50
エージェント DaemonSet のステータスを確認するには、次のコマンドを実行します。
kubectl get daemonset -n amazon-cloudwatch
サービスアカウントで IAM ロールを確認するには、次のコマンドを実行します。
kubectl get serviceaccount -n amazon-cloudwatch -o yaml
クラスターアドオンのステータスを確認するには、次のコマンドを実行します。cluster-name は、自分の Amazon EKS クラスターに置き換えます。
aws eks describe-addon --cluster-namecluster-name--addon-name amazon-cloudwatch-observability
Container Insights ロググループを一覧表示するには、次のコマンドを実行します。cluster-name は、自分の Amazon EKS クラスターに置き換えます。
aws logs describe-log-groups --log-group-name-prefix "/aws/containerinsights/cluster-name"
関連リソース
Amazon EKS での Container Insights の設定と運用の詳細については、以下のトピックを参照してください。
-
クイックスタート: Amazon EKS での OTel Container Insights – OTel Container Insights の設定
-
セットアップガイド (AWS CLI) – Classic Container Insights の設定
-
移行ガイド – アプローチ間の移行
-
Container Insights のアプローチを比較する – Container Insights のアプローチを比較する
