# Implantar o atendente do CloudWatch para coletar métricas no nível de instância do EC2 no Amazon ECS
<a name="deploy-container-insights-ECS-instancelevel"></a>

Para implantar o atendente do CloudWatch para coletar métricas no nível de instância de clusters do Amazon ECS hospedados em uma instância do EC2, use uma configuração de início rápido com uma configuração padrão ou instale o atendente manualmente para poder personalizá-lo.

Ambos os métodos exigem que você já tenha, pelo menos, um cluster do Amazon ECS implantado com um tipo de inicialização do EC2 e que o contêiner do agente do CloudWatch tenha acesso ao Instance Metadata Service (IMDS) do EC2. Para obter mais informações sobre o IMDS, consulte [Metadados da instância e dados de usuário](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html).

Esses métodos também presumem que a AWS CLI esteja instalada. Além disso, para executar os comandos nos procedimentos a seguir, é necessário estar conectado em uma conta ou em uma função que tenha as políticas **IAMFullAccess** e **AmazonECS\$1FullAccess**.

**Importante**  
Ao definir o contêiner do agente do CloudWatch em sua definição de tarefa, configure `essential: false`. Isso evita que todo o serviço do Amazon ECS seja interrompido se o contêiner do agente do CloudWatch falhar. Outros contêineres de aplicações críticas continuarão em execução mesmo se o agente estiver temporariamente indisponível.

**Topics**
+ [Configuração rápida usando o CloudFormation](#deploy-container-insights-ECS-instancelevel-quickstart)
+ [Configuração manual e personalizada](#deploy-container-insights-ECS-instancelevel-manual)

## Configuração rápida usando o CloudFormation
<a name="deploy-container-insights-ECS-instancelevel-quickstart"></a>

Para usar a configuração rápida, insira o comando a seguir a fim de usar o CloudFormation para instalar o atendente. Substitua *cluster-name* e *cluster-region* pelo nome e pela região de seu cluster do Amazon ECS.

Esse comando cria as funções do IAM **CWAgentECSTaskRole** e **CWAgentECSExecutionRole**. Se essas funções já existirem em sua conta, use `ParameterKey=CreateIAMRoles,ParameterValue=False` em vez de `ParameterKey=CreateIAMRoles,ParameterValue=True` ao inserir o comando. Caso contrário, o comando falhará.

```
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}
```

**(Alternativa) Usar suas próprias funções do IAM**

Se quiser usar suas próprias função de tarefa do ECS e função de execução de tarefa do ECS em vez das funções **CWAgentECSTaskRole** e **CWAgentECSExecutionRole**, primeiro verifique se a função que deve ser usada como a função de tarefa do ECS tem a **CloudWatchAgentServerPolicy** anexada. Além disso, verifique se a função a ser usada como função de execução de tarefa do ECS tem as políticas **CloudWatchAgentServerPolicy** e **AmazonECSTaskExecutionRolePolicy** anexadas. Depois, insira o comando a seguir. No comando, substitua *task-role-arn* pelo ARN da função de tarefa do ECS e substitua *execution-role-arn* pelo ARN da função de execução de tarefa do ECS personalizada.

```
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}
```

**Solucionar problemas da configuração rápida**

Para verificar o status da pilha do CloudFormation, insira o comando a seguir.

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

Se o `StackStatus` for diferente de `CREATE_COMPLETE` ou de `CREATE_IN_PROGRESS`, verifique os eventos da pilha para localizar o erro. Insira o comando a seguir.

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

Para conferir o status do serviço daemon `cwagent`, insira o comando a seguir. Na saída, `runningCount` deve ser igual a `desiredCount` na seção `deployment`. Se não for igual, verifique a seção `failures` na saída.

```
ClusterName=cluster-name
Region=cluster-region
aws ecs describe-services --services cwagent-daemon-service --cluster $ClusterName --region $Region
```

Também é possível usar o console do CloudWatch Logs para conferir o log do atendente. Procure o grupo de logs **/ecs/ecs-cwagent-daemon-service**.

**Excluir a pilha do CloudFormation do atendente do CloudWatch**

Se for necessário excluir a pilha do CloudFormation, insira o comando a seguir.

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

## Configuração manual e personalizada
<a name="deploy-container-insights-ECS-instancelevel-manual"></a>

Siga as etapas desta seção para implantar manualmente o atendente do CloudWatch a fim de coletar métricas no nível de instância dos clusters do Amazon ECS hospedados em instâncias do EC2.

### Funções e políticas do IAM necessárias
<a name="deploy-container-insights-ECS-instancelevel-IAMRoles"></a>

São necessárias duas funções do IAM. É necessário criá-las, caso ainda não existam. Para obter mais informações sobre essas funções, consulte [Funções do IAM para tarefas](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) e [Função de execução de tarefa do Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html).
+ Uma *função de tarefa do ECS*, que é usada pelo atendente do CloudWatch para publicar métricas. Se essa função já existir, será necessário verificar se ela tem a política `CloudWatchAgentServerPolicy` anexada.
+ Uma *função de execução de tarefa do ECS*, que é usada pelo atendente do Amazon ECS para executar o atendente do CloudWatch. Se essa função já existir, será necessário verificar se ela tem as políticas `AmazonECSTaskExecutionRolePolicy` e `CloudWatchAgentServerPolicy` anexadas.

Se ainda não tiver essas funções, você poderá usar os comandos a seguir para criá-las e anexar as políticas necessárias. Este primeiro comando cria a função de tarefa do 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\"}]}"
```

Após inserir o comando anterior, anote o valor de `Arn` da saída do comando como "TaskRoleArn". Você precisará usá-lo posteriormente ao criar a definição de tarefa. Depois, insira o comando a seguir para anexar as políticas necessárias.

```
aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
    --role-name CWAgentECSTaskRole
```

Este próximo comando cria a função de execução de tarefa do 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\"}]}"
```

Após inserir o comando anterior, anote o valor de `Arn` da saída do comando como "ExecutionRoleArn". Você precisará usá-lo posteriormente ao criar a definição de tarefa. Depois, insira os comandos a seguir para anexar as políticas necessárias.

```
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
```

### Criar a definição de tarefa e iniciar o serviço daemon
<a name="deploy-container-insights-ECS-instancelevel-taskdefinition"></a>

Crie uma definição de tarefa e use-a para executar o atendente do CloudWatch como um serviço daemon. Para criar a definição de tarefa, insira o comando a seguir. Nas primeiras linhas, substitua os espaços reservados pelos valores reais da implantação. *logs-region* é a região onde o CloudWatch Logs está localizado e *cluster-region* é a região onde o cluster está localizado. *task-role-arn* é o ARN do perfil da tarefa do ECS que você está usando e *execution-role-arn* é o ARN do perfil de execução de tarefa do ECS.

```
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
```

Depois, execute o comando a seguir para executar o serviço daemon. Substitua *cluster-name* e *cluster-region* pelo nome e pela região de seu cluster do Amazon ECS.

**Importante**  
Remova todas as estratégias do provedor de capacidade antes de executar o comando. Caso contrário, o comando não funcionará.

```
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}
```

Se esta mensagem de erro for exibida, `An error occurred (InvalidParameterException) when calling the CreateService operation: Creation of service was not idempotent`, é porque você já criou um serviço daemon chamado `cwagent-daemon-service`. Será necessário excluir esse serviço primeiro, usando o comando a seguir como exemplo.

```
ClusterName=cluster-name
Region=cluster-region
aws ecs delete-service \
    --cluster ${ClusterName} \
    --service cwagent-daemon-service \
    --region ${Region} \
    --force
```

### (Opcional) Configuração avançada
<a name="deploy-container-insights-ECS-instancelevel-advanced"></a>

Se preferir, você poderá usar o SSM para especificar outras opções de configuração para o atendente do CloudWatch nos clusters do Amazon ECS hospedados nas instâncias do EC2. Essas opções são as seguintes:
+ `metrics_collection_interval`? a frequência, em segundos, com a qual o atendente do CloudWatch coleta as métricas. O padrão é 60. O intervalo é de 1 a 172.000.
+ `endpoint_override`: (opcional) especifica um endpoint diferente para o qual enviar logs. Você pode querer fazer isso se estiver publicando de um cluster em uma VPC e quiser que os dados de logs vão para um VPC endpoint.

  O valor de `endpoint_override` deve ser uma string que seja um URL.
+ `force_flush_interval`: especifica em segundos a quantidade máxima de tempo em que os logs permanecem no buffer da memória antes de serem enviados ao servidor. Não importa a configuração para esse campo, se o tamanho dos logs no buffer alcançar 1 MB, os logs serão enviados imediatamente para o servidor. O valor de padrão é 5 segundos.
+ `region`: por padrão, o atendente publica métricas na mesma região onde a instância de contêiner do Amazon ECS está localizada. Para substituir isso, é possível especificar uma região diferente aqui. Por exemplo, `"region" : "us-east-1"`

Veja a seguir um exemplo de uma configuração personalizada:

```
{
    "agent": {
        "region": "us-east-1"
    },
    "logs": {
        "metrics_collected": {
            "ecs": {
                "metrics_collection_interval": 30
            }
        },
        "force_flush_interval": 5
    }
}
```

**Para personalizar a configuração do atendente do CloudWatch nos contêineres do Amazon ECS**

1. Verifique se a política **AmazonSSMReadOnlyAccess** está anexada à função de execução de tarefa do Amazon ECS. É possível inserir o comando a seguir para fazer isso. Esse exemplo pressupõe que a função de execução de tarefa do Amazon ECS seja CWAgentECSExecutionRole. Se você estiver usando uma função diferente, substitua esse nome da função no comando a seguir.

   ```
   aws iam attach-role-policy --policy-arn arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess \
           --role-name CWAgentECSExecutionRole
   ```

1. Crie o arquivo de configuração personalizada semelhante ao exemplo anterior. Nomeie esse arquivo como `/tmp/ecs-cwagent-daemon-config.json`.

1. Execute o comando a seguir para colocar essa configuração no Parameter Store. Substitua *cluster-region* pela região do cluster do Amazon ECS. Para executar esse comando, é necessário estar conectado a um usuário ou a uma função que tenha a política **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. Faça download do arquivo de definição de tarefa em um arquivo local, como . `/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. Modifique o arquivo de definição de tarefa. Remova a seguinte seção:

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

   Substitua essa seção pela seguinte:

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

1. Reinicie o atendente como um serviço daemon seguindo estas etapas:

   1. Execute o comando a seguir.

      ```
      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. Execute o comando a seguir para executar o serviço daemon. Substitua *cluster-name* e *cluster-region* pelo nome e pela região de seu cluster do 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}
      ```

      Se esta mensagem de erro for exibida, `An error occurred (InvalidParameterException) when calling the CreateService operation: Creation of service was not idempotent`, é porque você já criou um serviço daemon chamado `cwagent-daemon-service`. Será necessário excluir esse serviço primeiro, usando o comando a seguir como exemplo.

      ```
      ClusterName=cluster-name
      Region=Region
      aws ecs delete-service \
          --cluster ${ClusterName} \
          --service cwagent-daemon-service \
          --region ${Region} \
          --force
      ```