# クイックスタート: Amazon EKS での OTel Container Insights
このガイドでは、既存の Amazon EKS クラスターで OTel Container Insights を有効にする方法について説明します。この手順が終了するまでに、クラスターは拡張オブザーバビリティを有効にしてインフラストラクチャメトリクスとコンテナログを Amazon CloudWatch に送信します。
OTel Container Insights を有効にするには、AWS マネジメントコンソール を使用する (最速) か、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 マネジメントコンソール は、OTel Container Insights を有効にする最速のパスを提供します。
**コンソールを使用して OTel Container Insights を有効にするには**
1. [https://console.aws.amazon.com/eks/](https://console.aws.amazon.com/eks/) で Amazon EKS コンソール を開きます。
1. **[クラスター]** を選択し、クラスター名を選択します。
1. **[オブザーバビリティ]** タブを選択します。
1. **[Container Insights を有効にする]** を選択し、画面の指示に従います。
詳細なコンソールチュートリアルについては、「[コンソールから OTel Container Insights を有効にする](container-insights-eks-otel-console.md)」を参照してください。
## OTel Container Insights を有効にする (AWS CLI)
AWS CLI を使用して OTel Container Insights を有効にするには、次の手順に従います。
### ステップ 1: IAM ロールを作成する
CloudWatch Observability アドオンが CloudWatch にデータを送信できるようにする IAM ロールを作成します。
**CloudWatch Observability アドオン IAM ロールを作成するには**
1. 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"]
}]
}'
```
1. `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 でメトリクスを確認するには**
1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。
1. ナビゲーションペインで、**[Query Studio]** を選択します。
1. 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 の関連付けがないためです。
**解決策:** この問題を解決するには、次の手順に従います。
1. 次のコマンドを実行して、詳細なエラー情報を確認します。{{cluster-name}} をクラスターの名前に置き換えます。
```
aws eks describe-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability \
--query "addon.health"
```
1. IAM ロールが存在し、`CloudWatchAgentServerPolicy` がアタッチされていることを確認します。
1. Pod Identity の関連付けが正しい名前空間 (`amazon-cloudwatch`) とサービスアカウント (`cloudwatch-agent`) を対象としていることを確認します。
1. 障害が発生したアドオンを削除し、問題を解決した後に再インストールします。
```
aws eks delete-addon \
--cluster-name {{cluster-name}} \
--addon-name amazon-cloudwatch-observability
```
### エージェントポッドが CrashLoopBackOff または保留状態
**症状:** `kubectl get pods -n amazon-cloudwatch` を実行すると、1 つまたは複数のポッドに `CrashLoopBackOff` または `Pending` ステータスが表示されます。
**原因:** ノードリソースの不足、アクセス許可の欠落、ネットワーク接続の問題により、エージェントポッドを起動できないためです。
**解決策:** この問題を解決するには、次の手順に従います。
1. ポッドイベントで詳細なエラーメッセージを確認します。
```
kubectl describe pod -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent
```
1. エージェントコンテナログで起動エラーを確認します。
```
kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=50
```
1. エージェントポッドで使用できる十分な CPU とメモリがノードにあることを確認します。
1. 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 アクセス許可が正しくないためです。
**解決策:** この問題を解決するには、次の手順に従います。
1. エージェントポッドが CloudWatch エンドポイントに到達できることを確認します。VPC セキュリティグループとネットワーク ACL が CloudWatch エンドポイントへのアウトバウンド HTTPS トラフィック (ポート 443) を許可していることを確認します。
1. アクセス許可エラーまたは接続タイムアウトがないか、エージェントログで確認します。
```
kubectl logs -n amazon-cloudwatch -l app.kubernetes.io/name=cloudwatch-agent --tail=100 | grep -i "error\|timeout\|denied"
```
1. IAM ロールに `CloudWatchAgentServerPolicy` ポリシーがアタッチされており、信頼ポリシーで `pods.eks.amazonaws.com` が許可されていることを確認します。
1. CloudWatch に VPC エンドポイントを使用する場合は、エンドポイントポリシーで必要なアクションが許可されていることを確認します。