Amazon ECS で EC2 インスタンスレベルのメトリクスを収集するための CloudWatch エージェントのデプロイ - Amazon CloudWatch
AWS CloudFormation を使用した高速セットアップ手動およびカスタムセットアップ

Amazon ECS で EC2 インスタンスレベルのメトリクスを収集するための CloudWatch エージェントのデプロイ

EC2 インスタンスでホストされている Amazon ECS クラスターからインスタンスレベルのメトリクスを収集するために CloudWatch エージェントをデプロイするには、デフォルト設定でクイックスタート設定を使用するか、エージェントを手動でインストールしてカスタマイズできるようにします。

どちらの方法でも、EC2 起動タイプでデプロイされた Amazon EC2 クラスターが既に少なくとも 1 つあることと、CloudWatch エージェントコンテナが Amazon EC2 インスタンスメタデータサービス (IMDS) にアクセスできることが必要になります。IMDS の詳細については、「インスタンスメタデータとユーザーデータ」を参照してください。

また、これらの方法では、AWS CLI がインストールされていることを前提としています。また、次の手順でコマンドを実行するには、[IAMFullAccess] ポリシーと [AmazonECS_FullAccess] ポリシーを持つアカウントまたはロールにログオンする必要があります。

AWS CloudFormation を使用した高速セットアップ

高速セットアップを使用するには、次のコマンドを入力して、エージェントをインストールする AWS 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}

高速セットアップのトラブルシューティング

AWS 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 エージェントの AWS CloudFormation スタックの削除

AWS 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 ロール」および「Amazon ECS タスク実行ロール」を参照してください。

  • メトリクスを公開するために 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

  2. 前の例と同様のカスタマイズした設定ファイルを作成します。このファイル /tmp/ecs-cwagent-daemon-config.json の名前を変更します。

  3. 次のコマンドを実行して、この設定を 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

  4. /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

  5. タスク定義ファイルを変更します。次のセクションを削除します。

    "environment": [
                {
                    "name": "USE_DEFAULT_CONFIG",
                    "value": "True"
                }
            ],

    そのセクションを次のように置き換えます。

    "secrets": [
                {
                    "name": "CW_CONFIG_CONTENT",
                    "valueFrom": "ecs-cwagent-daemon-service"
                }
            ],

  6. 次のステップに従って、エージェントをデーモンサービスとして再起動します。

    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

    2. 次のコマンドを実行して、デーモンサービスを起動します。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