前提条件 OTel Container Insights を有効にする (コンソール)OTel Container Insights を有効にする (AWS CLI)CloudWatch でデータを確認するトラブルシューティング

クイックスタート: Amazon EKS での OTel Container Insights

このガイドでは、既存の Amazon EKS クラスターで OTel Container Insights を有効にする方法について説明します。この手順が終了するまでに、クラスターは拡張オブザーバビリティを有効にしてインフラストラクチャメトリクスとコンテナログを Amazon CloudWatch に送信します。

OTel Container Insights を有効にするには、AWS Management Console を使用する (最速) か、AWS CLI を使用するかの 2 つの方法があります。どちらのアプローチも、OTel Container Insights 設定で同じ amazon-cloudwatch-observability EKS アドオンをインストールします。手動エージェントのデプロイ、Helm チャート、カスタムコレクターパイプラインは必要ありません。プロセス全体の所要時間は 5 分未満です。

前提条件

OTel Container Insights を有効にする前に、次の要件を満たしていることを確認します。

Kubernetes バージョン 1.28 以降を実行している既存の Amazon EKS クラスター
プラットフォームバージョン eks.1 以降
amazon-cloudwatch-observability アドオンのバージョン 6.2.0 以降
AWS CLI バージョン 2.15.0 以降 (CLI ベースのセットアップの場合)
kubectl がターゲットクラスターと通信できるように設定されていること
IAM アクセス許可: eks:CreateAddon、eks:DescribeAddon、および iam:CreateServiceLinkedRole
クラスターにインストールされた EKS Pod Identity Agent アドオン、または設定済みのサービスアカウントの IAM ロール (IRSA)
クラスターから CloudWatch エンドポイントへのアウトバウンドインターネットアクセス

OTel Container Insights を有効にする (コンソール)

AWS Management Console は、OTel Container Insights を有効にする最速のパスを提供します。

コンソールを使用して OTel Container Insights を有効にするには

https://console.aws.amazon.com/eks/ で Amazon EKS コンソールを開きます。
[クラスター] を選択し、クラスター名を選択します。
[オブザーバビリティ] タブを選択します。
[Container Insights を有効にする] を選択し、画面の指示に従います。

詳細なコンソールチュートリアルについては、「コンソールから OTel Container Insights を有効にする」を参照してください。

OTel Container Insights を有効にする (AWS CLI)

AWS CLI を使用して OTel Container Insights を有効にするには、次の手順に従います。

ステップ 1: IAM ロールを作成する

CloudWatch Observability アドオンが CloudWatch にデータを送信できるようにする IAM ロールを作成します。

CloudWatch Observability アドオン IAM ロールを作成するには

EKS Pod Identity 用の信頼ポリシーを持つロールを作成するには、次のコマンドを実行します。


aws iam create-role \
  --role-name EKS-CloudWatch-Observability-Role \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": { "Service": "pods.eks.amazonaws.com" },
      "Action": ["sts:AssumeRole", "sts:TagSession"]
    }]
  }'

CloudWatchAgentServerPolicy 管理ポリシーをロールにアタッチします。


aws iam attach-role-policy \
  --role-name EKS-CloudWatch-Observability-Role \
  --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy

ステップ 2: Pod Identity の関連付けを作成する

IAM ロールをクラスター内の CloudWatch エージェントサービスアカウントに関連付けます。

Pod Identity の関連付けを作成するには

以下のコマンドを実行してください。cluster-name を Amazon EKS クラスターの名前に、account-id を AWS アカウント ID に置き換えます。


aws eks create-pod-identity-association \
  --cluster-name cluster-name \
  --namespace amazon-cloudwatch \
  --service-account cloudwatch-agent \
  --role-arn arn:aws:iam::account-id:role/EKS-CloudWatch-Observability-Role

ステップ 3: Amazon CloudWatch Observability アドオンをインストールする

OTel Container Insights を有効にして amazon-cloudwatch-observability アドオンをインストールします。

アドオンをインストールするには

以下のコマンドを実行してください。cluster-name は、自分の Amazon EKS クラスターに置き換えます。
```
aws eks create-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --configuration-values '{"otelContainerInsights":{"enabled":true}}'
```
重要
otelContainerInsights.enabled 設定が必要です。OTel Container Insights はデフォルトでは有効になっていません。

ステップ 4: アドオンのステータスを確認する

アドオンが正常にインストールされたことを確認します。

アドオンのステータスを確認するには

以下のコマンドを実行してください。cluster-name は、自分の Amazon EKS クラスターに置き換えます。
```
aws eks describe-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --query "addon.status" \
  --output text
```
期待される出力は ACTIVE です。

ステップ 5: エージェントポッドが実行されていることを確認する

CloudWatch エージェントポッドが amazon-cloudwatch 名前空間で実行されていることを確認します。

エージェントポッドが実行されていることを確認するには

以下のコマンドを実行してください。
```
kubectl get pods -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent
```
すべてのエージェントポッドが Running ステータスになっている必要があります。

CloudWatch でデータを確認する

セットアップを完了すると、3～5 分以内に Container Insights データが CloudWatch に表示されます。

メトリクスを確認する

CloudWatch でメトリクスを確認するには

CloudWatch コンソールの https://console.aws.amazon.com/cloudwatch/ を開いてください。
ナビゲーションペインで、[Query Studio] を選択します。
PromQL を使用して container_cpu_usage_seconds_total などのメトリクスを検索します。

ログを確認する

クラスターにロググループが存在することを確認するには、次のコマンドを実行します。cluster-name は、自分の Amazon EKS クラスターに置き換えます。


aws logs describe-log-groups \
  --log-group-name-prefix "/aws/containerinsights/cluster-name" \
  --query "logGroups[].logGroupName" \
  --output table

データが得られるまでの予想される時間

次の表は、OTel Container Insights を有効にした後の各シグナルタイプの予想されるレイテンシーを示しています。

シグナル	予想されるレイテンシー
インフラストラクチャメトリクス	2～3 分
コンテナログ	2～3 分
パフォーマンスログイベント	3～5 分

トラブルシューティング

Amazon EKS で OTel Container Insights を有効にするときに発生する一般的な問題を解決するには、次のガイダンスを使用します。

アドオンのステータスが CREATE_FAILED または DEGRADED と表示される

症状: aws eks describe-addon を実行すると、ステータスに CREATE_FAILED または DEGRADED が表示されます。

原因: アドオンのインストールに失敗しました。通常、IAM アクセス許可が不十分であるか、Pod Identity の関連付けがないためです。

解決策: この問題を解決するには、次の手順に従います。

次のコマンドを実行して、詳細なエラー情報を確認します。cluster-name をクラスターの名前に置き換えます。
```
aws eks describe-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability \
  --query "addon.health"
```
IAM ロールが存在し、CloudWatchAgentServerPolicy がアタッチされていることを確認します。
Pod Identity の関連付けが正しい名前空間 (amazon-cloudwatch) とサービスアカウント (cloudwatch-agent) を対象としていることを確認します。
障害が発生したアドオンを削除し、問題を解決した後に再インストールします。
```
aws eks delete-addon \
  --cluster-name cluster-name \
  --addon-name amazon-cloudwatch-observability
```

エージェントポッドが CrashLoopBackOff または保留状態

症状: kubectl get pods -n amazon-cloudwatch を実行すると、1 つまたは複数のポッドに CrashLoopBackOff または Pending ステータスが表示されます。

原因: ノードリソースの不足、アクセス許可の欠落、ネットワーク接続の問題により、エージェントポッドを起動できないためです。

解決策: この問題を解決するには、次の手順に従います。

ポッドイベントで詳細なエラーメッセージを確認します。


kubectl describe pod -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent

エージェントコンテナログで起動エラーを確認します。


kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=50

エージェントポッドで使用できる十分な CPU とメモリがノードにあることを確認します。
EKS Pod Identity Agent アドオンがインストールされ、実行されていることを確認します。
```
kubectl get pods -n kube-system -l app.kubernetes.io/name=eks-pod-identity-agent
```

5 分経過しても CloudWatch にメトリクスが表示されない

症状: エージェントポッドは Running ステータスを表示しますが、5 分後に CloudWatch にメトリクスが表示されません。

原因: エージェントが CloudWatch にデータを送信できません。通常、ネットワークの制限や IAM アクセス許可が正しくないためです。

解決策: この問題を解決するには、次の手順に従います。

エージェントポッドが CloudWatch エンドポイントに到達できることを確認します。VPC セキュリティグループとネットワーク ACL が CloudWatch エンドポイントへのアウトバウンド HTTPS トラフィック (ポート 443) を許可していることを確認します。

アクセス許可エラーまたは接続タイムアウトがないか、エージェントログで確認します。


kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=100 | grep -i "error\|timeout\|denied"

IAM ロールに CloudWatchAgentServerPolicy ポリシーがアタッチされており、信頼ポリシーで pods.eks.amazonaws.com が許可されていることを確認します。
CloudWatch に VPC エンドポイントを使用する場合は、エンドポイントポリシーで必要なアクションが許可されていることを確認します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

OTel Container Insights (推奨)

コンソールから OTel Container Insights を有効にする

クイックスタート: Amazon EKS での OTel Container Insights

前提条件

OTel Container Insights を有効にする (コンソール)

コンソールを使用して OTel Container Insights を有効にするには

OTel Container Insights を有効にする (AWS CLI)

ステップ 1: IAM ロールを作成する

CloudWatch Observability アドオン IAM ロールを作成するには

ステップ 2: Pod Identity の関連付けを作成する

Pod Identity の関連付けを作成するには

ステップ 3: Amazon CloudWatch Observability アドオンをインストールする

アドオンをインストールするには

重要

ステップ 4: アドオンのステータスを確認する

アドオンのステータスを確認するには

ステップ 5: エージェントポッドが実行されていることを確認する

エージェントポッドが実行されていることを確認するには

CloudWatch でデータを確認する

メトリクスを確認する

CloudWatch でメトリクスを確認するには

ログを確認する

データが得られるまでの予想される時間

トラブルシューティング

アドオンのステータスが CREATE_FAILED または DEGRADED と表示される

エージェントポッドが CrashLoopBackOff または保留状態

5 分経過しても CloudWatch にメトリクスが表示されない