CloudWatch 에이전트를 배포하여 Amazon ECS의 EC2 인스턴스 수준 지표 수집 - Amazon CloudWatch
AWS CloudFormation을 사용한 빠른 설정수동 설치 및 사용자 지정

CloudWatch 에이전트를 배포하여 Amazon ECS의 EC2 인스턴스 수준 지표 수집

CloudWatch 에이전트를 배포하여 EC2 인스턴스에서 호스트되는 Amazon ECS 클러스터에서 인스턴스 수준 지표를 수집하려면 기본 구성으로 빠른 시작 설정을 사용하거나 에이전트를 수동으로 설치해 사용자 지정하면 됩니다.

두 방법 모두 EC2 시작 유형으로 배포된 Amazon ECS 클러스터가 하나 이상 있고 CloudWatch 에이전트 컨테이너가 Amazon EC2 인스턴스 메타데이터 서비스(IMDS)에 액세스할 수 있어야 합니다. IMDS에 대한 자세한 내용은 인스턴스 메타데이터 및 사용자 데이터를 참조하세요.

이러한 방법은 AWS CLI도 설치되어 있다고 가정합니다. 또한 다음 절차에서 명령을 실행하려면 IAMFullAccess 및 AmazonECS_FullAccess 정책이 있는 계정 또는 역할에 로그인해야 합니다.

AWS CloudFormation을 사용한 빠른 설정

빠른 설정을 사용하려면 다음 명령을 입력하여 AWS CloudFormation을 사용해 에이전트를 설치합니다. cluster-name 및 cluster-region을 Amazon ECS 클러스터의 이름 및 리전으로 바꿉니다.

이 명령은 IAM 역할인 CWAgentECSTaskRole 및 CWAgentECSExecutionRole을 생성합니다. 이러한 역할이 계정에 이미 있는 경우 명령을 입력할 때 ParameterKey=CreateIAMRoles,ParameterValue=True 대신 ParameterKey=CreateIAMRoles,ParameterValue=False를 사용합니다. 그렇지 않으면 명령이 실패합니다.

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

CREATE_COMPLETE 또는 CREATE_IN_PROGRESS 이외의 StackStatus가 표시되면 스택 이벤트를 확인하여 오류를 찾습니다. 다음 명령을 입력합니다.

ClusterName=cluster-name
Region=cluster-region
aws cloudformation describe-stack-events --stack-name CWAgentECS-$ClusterName-$Region --region $Region

cwagent 데몬 서비스의 상태를 확인하려면 다음 명령을 입력합니다. 출력에서 runningCount가 deployment 섹션의 desiredCount와 같은 것을 볼 수 있습니다. 같지 않은 경우 출력에서 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 역할 및 정책

두 가지 IAM 역할이 필요합니다. 아직 존재하지 않는 경우 생성해야 합니다. 이러한 역할에 대한 자세한 내용은 IAM roles for Tasks(태스크에 대한 IAM 역할)와 Amazon ECS Task Execution Role(Amazon ECS 태스크 실행 역할)을 참조하세요.

  • CloudWatch 에이전트가 지표를 게시하는 데 사용하는 ‘ECS 태스크 역할’. 이 역할이 이미 있는 경우 CloudWatchAgentServerPolicy 정책이 연결되어 있는지 확인해야 합니다.

  • Amazon ECS 에이전트가 CloudWatch 에이전트를 시작하는 데 사용하는 ‘ECS 태스크 실행 역할’. 이 역할이 이미 있는 경우 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-region을 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 – 로그가 서버로 전송되기 전에 메모리 버퍼에 남아 있는 최대 시간(초)을 지정합니다. 이 필드에 대한 설정과 상관없이 버퍼 내 로그의 크기가 1MB에 도달하면 로그가 즉시 서버로 전송됩니다. 기본 값은 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. 다음 명령을 실행하여 이 구성을 파라미터 스토어에 넣습니다. 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-region을 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