# Amazon ECS で EC2 インスタンスレベルのメトリクスを収集するための CloudWatch エージェントのデプロイ
EC2 インスタンスでホストされている Amazon ECS クラスターからインスタンスレベルのメトリクスを収集するために CloudWatch エージェントをデプロイするには、デフォルト設定でクイックスタート設定を使用するか、エージェントを手動でインストールしてカスタマイズできるようにします。
どちらの方法でも、EC2 起動タイプでデプロイされた Amazon EC2 クラスターが既に少なくとも 1 つあることと、CloudWatch エージェントコンテナが Amazon EC2 インスタンスメタデータサービス (IMDS) にアクセスできることが必要になります。IMDS の詳細については、「[インスタンスメタデータとユーザーデータ](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)」を参照してください。
また、これらの方法では、AWS CLI がインストールされていることを前提としています。また、次の手順でコマンドを実行するには、[**IAMFullAccess**] ポリシーと [**AmazonECS\$1FullAccess**] ポリシーを持つアカウントまたはロールにログオンする必要があります。
**重要**
タスク定義で CloudWatch エージェントコンテナを定義するときは、`essential: false` を設定します。これにより、CloudWatch エージェントコンテナに障害が発生した場合に Amazon ECS サービス全体が停止するのを防ぐことができます。エージェントが一時的に使用できない場合でも、他の重要なアプリケーションコンテナは引き続き実行されます。
**Topics**
+ [CloudFormation を使用した高速セットアップ](#deploy-container-insights-ECS-instancelevel-quickstart)
+ [手動およびカスタムセットアップ](#deploy-container-insights-ECS-instancelevel-manual)
## CloudFormation を使用した高速セットアップ
高速セットアップを使用するには、次のコマンドを入力して、エージェントをインストールする CloudFormation を使用します。*cluster-name* と *cluster-regions* を Amazon ECS クラスターの名前とリージョンに置き換えます。
このコマンドは、IAM ロールの [**CWAgentECSTaskRole**] と [**CWAgentECSExecutionRole**] を作成します。これらのロールがアカウントにすでに存在する場合は、コマンドを入力ときに、`ParameterKey=CreateIAMRoles,ParameterValue=False` ではなく、`ParameterKey=CreateIAMRoles,ParameterValue=True` を使用します。そうしないと、コマンドは失敗します。
```
ClusterName=cluster-name
Region=cluster-region
curl -O https://raw.githubusercontent.com/aws-samples/amazon-cloudwatch-container-insights/latest/ecs-task-definition-templates/deployment-mode/daemon-service/cwagent-ecs-instance-metric/cloudformation-quickstart/cwagent-ecs-instance-metric-cfn.json
aws cloudformation create-stack --stack-name CWAgentECS-${ClusterName}-${Region} \
--template-body file://cwagent-ecs-instance-metric-cfn.json \
--parameters ParameterKey=ClusterName,ParameterValue=${ClusterName} \
ParameterKey=CreateIAMRoles,ParameterValue=True \
--capabilities CAPABILITY_NAMED_IAM \
--region ${Region}
```
**(代替) 独自の IAM ロールの使用**
[**CWAgentECSTaskRole**] および [**CWAgentECSExecutionRole**] ロールの代わりに、独自のカスタム ECS タスクロールと ECS タスク実行ロールを使用する場合は、最初に ECS タスクロールとして使用するロールに アタッチされている [**CloudWatchAgentServerPolicy**] が含まれていることを確認します。また、ECS タスク実行ロールとして使用するロールに、[**CloudWatchAgentServerPolicy**] ポリシー と [**AmazonECSTaskExecutionRolePolicy**] ポリシーの 両方がアタッチされていることを確認してください。次に、以下のコマンドを入力します。コマンドで、*task-role-arn* をカスタム ECS タスクロールの ARN に置き換え、*execution-role-arn* をカスタム ECS タスク実行ロールの ARN に置き換えます。
```
ClusterName=cluster-name
Region=cluster-region
TaskRoleArn=task-role-arn
ExecutionRoleArn=execution-role-arn
curl -O https://raw.githubusercontent.com/aws-samples/amazon-cloudwatch-container-insights/latest/ecs-task-definition-templates/deployment-mode/daemon-service/cwagent-ecs-instance-metric/cloudformation-quickstart/cwagent-ecs-instance-metric-cfn.json
aws cloudformation create-stack --stack-name CWAgentECS-${ClusterName}-${Region} \
--template-body file://cwagent-ecs-instance-metric-cfn.json \
--parameters ParameterKey=ClusterName,ParameterValue=${ClusterName} \
ParameterKey=TaskRoleArn,ParameterValue=${TaskRoleArn} \
ParameterKey=ExecutionRoleArn,ParameterValue=${ExecutionRoleArn} \
--capabilities CAPABILITY_NAMED_IAM \
--region ${Region}
```
**高速セットアップのトラブルシューティング**
CloudFormation スタックのステータスを確認するには、次のコマンドを入力します。
```
ClusterName=cluster-name
Region=cluster-region
aws cloudformation describe-stacks --stack-name CWAgentECS-$ClusterName-$Region --region $Region
```
`StackStatus` が `CREATE_COMPLETE`または `CREATE_IN_PROGRESS` 以外の場合、スタックイベントをチェックしてエラーを検出します。以下のコマンドを入力します。
```
ClusterName=cluster-name
Region=cluster-region
aws cloudformation describe-stack-events --stack-name CWAgentECS-$ClusterName-$Region --region $Region
```
`cwagent` デーモンサービスの状態を確認するには、次のコマンドを入力します。出力では、`runningCount` セクション の`desiredCount` が `deployment` と等しいことがわかります。等しくない場合は、出力の `failures` セクションを確認してください。
```
ClusterName=cluster-name
Region=cluster-region
aws ecs describe-services --services cwagent-daemon-service --cluster $ClusterName --region $Region
```
CloudWatch Logs コンソールを使用してエージェントログを確認することもできます。[**/ecs/ecs-cwagent-daemon-service**] ロググループを探します。
**CloudWatch エージェントの CloudFormation スタックの削除**
CloudFormation スタックを削除する必要がある場合は、次のコマンドを入力します。
```
ClusterName=cluster-name
Region=cluster-region
aws cloudformation delete-stack --stack-name CWAgentECS-${ClusterName}-${Region} --region ${Region}
```
## 手動およびカスタムセットアップ
このセクションのステップに従って、CloudWatch エージェントを手動でデプロイして、EC2 インスタンスでホストされている Amazon ECS クラスターからインスタンスレベルのメトリクスを収集します。
### 必要な IAM ロールとポリシー
2 つの IAM ロールが必要です。まだ存在しない場合は、作成する必要があります。これらのロールの詳細については、「[タスク用の IAM ロール](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)」および「[Amazon ECS タスク実行ロール](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html)」を参照してください。
+ メトリクスを公開するために CloudWatch エージェントによって使用される、*ECS タスクロール*。このロールがすでに存在する場合は、`CloudWatchAgentServerPolicy` ポリシーがアタッチされていることを確認する必要があります。
+ CloudWatch エージェントを起動するために Amazon ECS エージェントが使用する、*EC2 タスク実行ロール*。このロールがすでに存在する場合は、`AmazonECSTaskExecutionRolePolicy` ポリシー `CloudWatchAgentServerPolicy` とポリシーがアタッチされていることを確認する必要があります。
これらのロールがまだない場合は、次のコマンドを使用してロールを作成し、必要なポリシーをアタッチできます。この最初のコマンドは、ECS タスクロールを作成します。
```
aws iam create-role --role-name CWAgentECSTaskRole \
--assume-role-policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Sid\": \"\",\"Effect\": \"Allow\",\"Principal\": {\"Service\": \"ecs-tasks.amazonaws.com\"},\"Action\": \"sts:AssumeRole\"}]}"
```
前のコマンドを入力したら、コマンド出力の `Arn` の値を「TaskRoleArn」と書き留めます。このタスクは、後でタスク定義を作成するときに使用する必要があります。次に、以下のコマンドを入力して、必要なポリシーをアタッチします。
```
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
--role-name CWAgentECSTaskRole
```
次のコマンドは、ECS タスク実行ロールを作成します。
```
aws iam create-role --role-name CWAgentECSExecutionRole \
--assume-role-policy-document "{\"Version\": \"2012-10-17\", \"Statement\": [{\"Sid\": \"\",\"Effect\": \"Allow\",\"Principal\": {\"Service\": \"ecs-tasks.amazonaws.com\"},\"Action\": \"sts:AssumeRole\"}]}"
```
前のコマンドを入力したら、コマンド出力の `Arn` の値を「ExecutionRoleArn」と書き留めます。このタスクは、後でタスク定義を作成するときに使用する必要があります。次に、以下のコマンドを入力して、必要なポリシーをアタッチします。
```
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
--role-name CWAgentECSExecutionRole
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy \
--role-name CWAgentECSExecutionRole
```
### タスク定義を作成し、デーモンサービスを起動する
タスク定義を作成し、それを使用して CloudWatch エージェントをデーモンサービスとして起動します。タスク定義を作成するには、次のコマンドを入力します。最初の行で、プレースホルダーをデプロイの実際の値に置き換えます。*logs-region* は、CloudWatch Logs が 配置されているリージョンで、*cluster-region* はクラスターが配置されているリージョンです。*task-role-arn* は、使用している ECS タスクロールの ARN で、*execution-role-arn* は ECS タスク実行ロールの ARN です。
```
TaskRoleArn=task-role-arn
ExecutionRoleArn=execution-role-arn
AWSLogsRegion=logs-region
Region=cluster-region
curl https://raw.githubusercontent.com/aws-samples/amazon-cloudwatch-container-insights/latest/ecs-task-definition-templates/deployment-mode/daemon-service/cwagent-ecs-instance-metric/cwagent-ecs-instance-metric.json \
| sed "s|{{task-role-arn}}|${TaskRoleArn}|;s|{{execution-role-arn}}|${ExecutionRoleArn}|;s|{{awslogs-region}}|${AWSLogsRegion}|" \
| xargs -0 aws ecs register-task-definition --region ${Region} --cli-input-json
```
次に、以下のコマンドを実行してデーモンサービスを起動します。*cluster-name* と *cluster-regions* を Amazon ECS クラスターの名前とリージョンに置き換えます。
**重要**
このコマンドを実行する前に、すべてのキャパシティプロバイダー戦略を削除します。削除しない場合、コマンドは機能しません。
```
ClusterName=cluster-name
Region=cluster-region
aws ecs create-service \
--cluster ${ClusterName} \
--service-name cwagent-daemon-service \
--task-definition ecs-cwagent-daemon-service \
--scheduling-strategy DAEMON \
--region ${Region}
```
次のエラーメッセージ、`An error occurred (InvalidParameterException) when calling the CreateService operation: Creation of service was not idempotent` が表示された場合は、`cwagent-daemon-service` という名前のデーモンサービスは既に作成されています。まず、次のコマンドを例として使用して、そのサービスを削除する必要があります。
```
ClusterName=cluster-name
Region=cluster-region
aws ecs delete-service \
--cluster ${ClusterName} \
--service cwagent-daemon-service \
--region ${Region} \
--force
```
### (オプション) 詳細設定
オプションで、SSM を使用して、EC2 インスタンスでホストされている Amazon ECS クラスター内の CloudWatch エージェントの他の設定オプションを指定できます。オプションは以下のとおりです。
+ `metrics_collection_interval` – CloudWatch エージェントがメトリクスを収集する頻度 (秒) 。デフォルトは 60 です。範囲は 1～172,000 です。
+ `endpoint_override` – (オプション) ログの送信先となる別のエンドポイントを指定します。VPC のクラスターからデータを発行し、ログデータの送信先を VPC エンドポイントとする場合は、この操作を行うことをお勧めします。
`endpoint_override` の値は URL 文字列であることが必要です。
+ `force_flush_interval` – ログがサーバーに送信されるまでにメモリバッファ内に残留する最大時間を秒単位で指定します。このフィールドの設定にかかわらず、バッファ内のログのサイズが 1 MB に達すると、ログは即座にサーバーに送信されます。デフォルト値は 5 秒です。
+ `region` – デフォルトでは、エージェントは Amazon ECS コンテナインスタンスがあるのと同じリージョンにメトリクスを発行します。これを上書きするには、ここで別のリージョンを指定します。例: `"region" : "us-east-1"`
次に、カスタマイズした設定の例を示します。
```
{
"agent": {
"region": "us-east-1"
},
"logs": {
"metrics_collected": {
"ecs": {
"metrics_collection_interval": 30
}
},
"force_flush_interval": 5
}
}
```
**Amazon ECS コンテナで CloudWatch エージェントの設定をカスタマイズするには**
1. [**AmazonSSMReadOnlyAccess**] ポリシーが Amazon ECS タスク実行ロールにアタッチされていることを確認します。これを行うには、次のコマンドを入力します。この例では、Amazon ECS タスク実行ロールが CWAgentECSExecutionRole であることを前提としています。別のロールを使用している場合は、次のコマンドでそのロール名を置き換えます。
```
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess \
--role-name CWAgentECSExecutionRole
```
1. 前の例と同様のカスタマイズした設定ファイルを作成します。このファイル `/tmp/ecs-cwagent-daemon-config.json` の名前を変更します。
1. 次のコマンドを実行して、この設定を Parameter Store に配置します。*cluster-region* をお使いの Amazon ECS クラスターのリージョンに置き換えます。このコマンドを実行するには、**AmazonSSMFullAccess** ポリシーを持つユーザーまたはロールにログオンする必要があります。
```
Region=cluster-region
aws ssm put-parameter \
--name "ecs-cwagent-daemon-service" \
--type "String" \
--value "`cat /tmp/ecs-cwagent-daemon-config.json`" \
--region $Region
```
1. `/tmp/cwagent-ecs-instance-metric.json` などのタスク定義ファイルをローカルファイルにダウインロードします
```
curl https://raw.githubusercontent.com/aws-samples/amazon-cloudwatch-container-insights/latest/ecs-task-definition-templates/deployment-mode/daemon-service/cwagent-ecs-instance-metric/cwagent-ecs-instance-metric.json -o /tmp/cwagent-ecs-instance-metric.json
```
1. タスク定義ファイルを変更します。次のセクションを削除します。
```
"environment": [
{
"name": "USE_DEFAULT_CONFIG",
"value": "True"
}
],
```
そのセクションを次のように置き換えます。
```
"secrets": [
{
"name": "CW_CONFIG_CONTENT",
"valueFrom": "ecs-cwagent-daemon-service"
}
],
```
1. 次のステップに従って、エージェントをデーモンサービスとして再起動します。
1. 次のコマンドを実行します。
```
TaskRoleArn=task-role-arn
ExecutionRoleArn=execution-role-arn
AWSLogsRegion=logs-region
Region=cluster-region
cat /tmp/cwagent-ecs-instance-metric.json \
| sed "s|{{task-role-arn}}|${TaskRoleArn}|;s|{{execution-role-arn}}|${ExecutionRoleArn}|;s|{{awslogs-region}}|${AWSLogsRegion}|" \
| xargs -0 aws ecs register-task-definition --region ${Region} --cli-input-json
```
1. 次のコマンドを実行して、デーモンサービスを起動します。*cluster-name* と *cluster-regions* を Amazon ECS クラスターの名前とリージョンに置き換えます。
```
ClusterName=cluster-name
Region=cluster-region
aws ecs create-service \
--cluster ${ClusterName} \
--service-name cwagent-daemon-service \
--task-definition ecs-cwagent-daemon-service \
--scheduling-strategy DAEMON \
--region ${Region}
```
次のエラーメッセージ、`An error occurred (InvalidParameterException) when calling the CreateService operation: Creation of service was not idempotent` が表示された場合は、`cwagent-daemon-service` という名前のデーモンサービスは既に作成されています。まず、次のコマンドを例として使用して、そのサービスを削除する必要があります。
```
ClusterName=cluster-name
Region=Region
aws ecs delete-service \
--cluster ${ClusterName} \
--service cwagent-daemon-service \
--region ${Region} \
--force
```