Configuração rápida usando o CloudFormation Configuração manual e personalizada

Implantar o atendente do CloudWatch para coletar métricas no nível de instância do EC2 no Amazon ECS

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.

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_FullAccess.

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.

Tópicos

Configuração rápida usando o CloudFormation
Configuração manual e personalizada

Configuração rápida usando o CloudFormation

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

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

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 e Função de execução de tarefa do Amazon ECS.

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

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 da função de execução de tarefa do ECS que você está usando, e execution-role-arn é o ARN da função 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

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 é de 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

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
```
Crie o arquivo de configuração personalizada semelhante ao exemplo anterior. Nomeie esse arquivo como /tmp/ecs-cwagent-daemon-config.json.
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
```

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

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"
                }
            ],

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

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

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

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Configurar o Container Insights no Amazon ECS usando o AWS Distro for OpenTelemetry

Implantar o AWS Distro for OpenTelemetry para coletar métricas no nível de instância do EC2 em clusters do Amazon ECS