# CloudWatch 에이전트를 배포하여 Amazon ECS의 EC2 인스턴스 수준 지표 수집
<a name="deploy-container-insights-ECS-instancelevel"></a>

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

두 방법 모두 EC2 시작 유형으로 배포된 Amazon ECS 클러스터가 하나 이상 있고 CloudWatch 에이전트 컨테이너가 Amazon EC2 인스턴스 메타데이터 서비스(IMDS)에 액세스할 수 있어야 합니다. IMDS에 대한 자세한 내용은 [인스턴스 메타데이터 및 사용자 데이터](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)를 참조하세요.

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

**중요**  
작업 정의에서 CloudWatch Agent 컨테이너를 정의하는 경우 `essential: false`를 설정합니다. 이렇게 하면 CloudWatch Agent 컨테이너에서 장애가 발생할 경우 전체 Amazon ECS 서비스가 중지되지 않습니다. 에이전트를 일시적으로 사용할 수 없는 경우에도 다른 중요한 애플리케이션 컨테이너는 계속 실행됩니다.

**Topics**
+ [CloudFormation을 사용한 빠른 설정](#deploy-container-insights-ECS-instancelevel-quickstart)
+ [수동 설치 및 사용자 지정](#deploy-container-insights-ECS-instancelevel-manual)

## CloudFormation을 사용한 빠른 설정
<a name="deploy-container-insights-ECS-instancelevel-quickstart"></a>

빠른 설정을 사용하려면 다음 명령을 입력하여 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}
```

**빠른 설정 문제 해결**

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 에이전트의 CloudFormation 스택 삭제**

CloudFormation 스택을 삭제해야 하는 경우 다음 명령을 입력합니다.

```
ClusterName=cluster-name
Region=cluster-region
aws cloudformation delete-stack --stack-name CWAgentECS-${ClusterName}-${Region} --region ${Region}
```

## 수동 설치 및 사용자 지정
<a name="deploy-container-insights-ECS-instancelevel-manual"></a>

이 단원의 단계에 따라 CloudWatch 에이전트를 수동으로 배포하여 EC2 인스턴스에서 호스트되는 Amazon ECS 클러스터에서 인스턴스 수준 지표를 수집합니다.

### 필요한 IAM 역할 및 정책
<a name="deploy-container-insights-ECS-instancelevel-IAMRoles"></a>

두 가지 IAM 역할이 필요합니다. 아직 존재하지 않는 경우 생성해야 합니다. 이러한 역할에 대한 자세한 내용은 [IAM roles for Tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)(태스크에 대한 IAM 역할)와 [Amazon ECS Task Execution Role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html)(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
```

### 태스크 정의 생성 및 데몬 서비스 시작
<a name="deploy-container-insights-ECS-instancelevel-taskdefinition"></a>

태스크 정의를 생성하고 이를 사용하여 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
```

### (선택 사항) 고급 구성
<a name="deploy-container-insights-ECS-instancelevel-advanced"></a>

선택적으로 SSM을 사용하여 EC2 인스턴스에서 호스트되는 Amazon ECS 클러스터의 CloudWatch 에이전트에 대한 다른 구성 옵션을 지정할 수 있습니다. 이러한 옵션은 다음과 같습니다.
+ `metrics_collection_interval` – CloudWatch 에이전트가 지표를 수집하는 빈도(초)입니다. 기본값은 60입니다. 범위는 1\$1172,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
   ```

1. 앞의 예제와 비슷한 사용자 지정된 구성 파일을 생성합니다. 이 파일의 이름을 `/tmp/ecs-cwagent-daemon-config.json`으로 지정합니다.

1. 다음 명령을 실행하여 이 구성을 파라미터 스토어에 넣습니다. *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-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
      ```