# Implementación del agente de CloudWatch para recopilar métricas de nivel de instancia EC2 en Amazon ECS
<a name="deploy-container-insights-ECS-instancelevel"></a>

Para implementar el agente de CloudWatch a fin de recopilar métricas de nivel de instancia de los clústeres de Amazon ECS alojados en instancias EC2, utilice una configuración de inicio rápido con una configuración predeterminada o instale el agente manualmente para poder personalizarlo.

Ambos métodos requieren que tenga al menos un clúster de Amazon ECS implementado con un tipo de lanzamiento de EC2 y que el contenedor del agente de CloudWatch tenga acceso al servicio de metadatos de instancias de Amazon EC2 (IMDS). Para más información, consulte [Metadatos de instancia y datos de usuario](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html).

Estos métodos también suponen que tiene instalada la AWS CLI. Además, para ejecutar los comandos en los procedimientos siguientes, debe iniciar sesión en una cuenta o rol que tenga las políticas **IAMFullAccess** y **AmazonECS\$1FullAccess**.

**importante**  
Al definir el contenedor del agente de CloudWatch en la definición de la tarea, configure `essential: false`. Esto evita que todo el servicio de Amazon ECS se detenga si el contenedor del agente de CloudWatch falla. Otros contenedores de aplicaciones críticas continuarán ejecutándose incluso si el agente no está disponible temporalmente.

**Topics**
+ [Configuración rápida mediante CloudFormation](#deploy-container-insights-ECS-instancelevel-quickstart)
+ [Configuración manual y personalizada](#deploy-container-insights-ECS-instancelevel-manual)

## Configuración rápida mediante CloudFormation
<a name="deploy-container-insights-ECS-instancelevel-quickstart"></a>

Para utilizar la configuración rápida, escriba el siguiente comando para usar CloudFormation a fin de instalar el agente. Sustituya *cluster-name* (cluster-nombre) y *cluster-region* (clúster-región) por el nombre y la región del clúster de Amazon ECS.

Este comando crea los roles de IAM **CWAgentECSTaskRole** y **CWAgentECSExecutionRole**. Si estos roles ya existen en su cuenta, utilice `ParameterKey=CreateIAMRoles,ParameterValue=False` en lugar de `ParameterKey=CreateIAMRoles,ParameterValue=True` cuando escriba el comando. De lo contrario, el comando fallará.

```
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) Uso de sus propios roles de IAM**

Si desea utilizar su propio rol de tarea de ECS personalizado y el rol de ejecución de tareas de ECS en lugar de los roles **CWAgentECSTaskRole** y **CWAgentECSExecutionRole**, asegúrese primero de que el rol que se va a usar como rol de tarea de ECS tiene **CloudWatchAgentServerPolicy** asociada. Además, asegúrese de que el rol que se va a utilizar como rol de ejecución de tareas de ECS tiene asociadas las políticas **CloudWatchAgentServerPolicy** y **AmazonECSTaskExecutionRolePolicy**. A continuación, escriba el siguiente comando. En el comando, sustituya *task-role-arn* por el ARN de su rol de tarea de ECS personalizado y *execution-role-arn* por el ARN de su rol de ejecución de tareas de ECS personalizado.

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

**Solución de problemas de la configuración rápida**

Para comprobar el estado de la pila de CloudFormation, escriba el siguiente comando.

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

Si ve que el `StackStatus` es distinto de `CREATE_COMPLETE` o `CREATE_IN_PROGRESS`, compruebe los eventos de pila para encontrar el error. Escriba el siguiente comando.

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

Para verificar el estado del servicio del servicio del daemon `cwagent`, ingrese el siguiente comando. En la salida, debería ver que el `runningCount` es igual al `desiredCount` en la sección `deployment`. Si no es igual, compruebe la sección `failures` en la salida.

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

También puede utilizar la consola de CloudWatch Logs para verificar el registro del agente. Busque el grupo de registro **/ecs/ecs-cwagent-daemon-service**.

**Eliminación de la pila de CloudFormation del agente de CloudWatch**

Si necesita eliminar la pila de CloudFormation, escriba el siguiente comando.

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

## Configuración manual y personalizada
<a name="deploy-container-insights-ECS-instancelevel-manual"></a>

Siga los pasos de esta sección para implementar manualmente el agente de CloudWatch para recopilar métricas de nivel de instancia de los clústeres de Amazon ECS alojados en instancias EC2.

### Políticas y roles de IAM necesarios
<a name="deploy-container-insights-ECS-instancelevel-IAMRoles"></a>

Se requieren dos roles de IAM. Debe crearlos si aún no existen. Para obtener más información sobre estos roles, consulte [IAM roles for Tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) (Roles IAM para tareas) y [Amazon ECS Task Execution Role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html) (Rol de ejecución de tareas de Amazon ECS).
+ Un *ECS task role* (rol de tarea de ECS), que el agente de CloudWatch utiliza para publicar métricas. Si este rol ya existe, debe asegurarse de que tiene la política `CloudWatchAgentServerPolicy` asociada.
+ Un *ECS task execution role* (rol de ejecución de tareas de ECS), que el agente de Amazon ECS utiliza para lanzar el agente de CloudWatch. Si este rol ya existe, debe asegurarse de que tiene las políticas `AmazonECSTaskExecutionRolePolicy` y `CloudWatchAgentServerPolicy` asociadas.

Si aún no dispone de estos roles, puede utilizar los siguientes comandos para crearlos y asociar las políticas necesarias. Este primer comando crea el rol de tarea de 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\"}]}"
```

Después de escribir el comando anterior, anote el valor de `Arn` de la salida de los comandos como “TaskRoleArn”. Tendrá que usarse más tarde cuando se cree la definición de tarea. A continuación, escriba el siguiente comando para asociar las políticas necesarias.

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

Este siguiente comando crea el rol de ejecución de tareas de 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\"}]}"
```

Después de escribir el comando anterior, anote el valor de `Arn` de la salida de los comandos como “ExecutionRoleArn”. Tendrá que usarse más tarde cuando se cree la definición de tarea. A continuación, escriba los siguientes comandos para asociar las políticas necesarias.

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

### Cree la definición de tarea y lance el servicio del daemon
<a name="deploy-container-insights-ECS-instancelevel-taskdefinition"></a>

Cree una definición de tarea y úsela para lanzar el agente de CloudWatch como servicio del daemon. Para crear la definición de tarea, escriba el siguiente comando. En las primeras líneas, sustituya los marcadores de posición con los valores reales de la implementación. *logs-region* es la región de la ubicación de Registros de CloudWatch, mientras que *cluster-region* es la región en la se encuentra el clúster. *task-role-arn* es el Arn del rol de tarea de ECS que utiliza, mientras que *execution-role-arn* es el Arn del rol de puesta en marcha de tareas de 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
```

A continuación, ejecute el siguiente comando para lanzar el servicio de daemon. Sustituya *cluster-name* y *cluster-region* por el nombre y la Región del clúster de Amazon ECS.

**importante**  
Elimine todas las estrategias del proveedor de capacidad antes de ejecutar este comando. De lo contrario, el comando no 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}
```

Si aparece este mensaje de error, `An error occurred (InvalidParameterException) when calling the CreateService operation: Creation of service was not idempotent`, ya ha creado un servicio de daemon llamado `cwagent-daemon-service`. Debe eliminar ese servicio primero, utilizando el siguiente comando como ejemplo.

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

### (Opcional) Configuración avanzada
<a name="deploy-container-insights-ECS-instancelevel-advanced"></a>

Opcionalmente, puede utilizar SSM para especificar otras opciones de configuración para el agente de CloudWatch en los clústeres de Amazon ECS alojados en instancias EC2. Estas opciones son las siguientes:
+ `metrics_collection_interval`: la frecuencia en segundos con la que el agente de CloudWatch recopila métricas. El valor predeterminado es 60. El rango va de 1 a 172 000.
+ `endpoint_override`: (opcional) especifica un punto de enlace diferente al que enviar los registros. Es posible que desee hacerlo si realiza la publicación desde un clúster de una VPC y desea que los datos de registro vayan a un punto de enlace de la VPC.

  El valor de `endpoint_override` debe ser una cadena que sea una URL.
+ `force_flush_interval`: especifica en segundos la cantidad máxima de tiempo que los registros permanecen en el búfer de memoria antes de enviarse al servidor. Independientemente del valor de este campo, si el tamaño de los registros en el búfer alcanza 1 MB, los registros se envían inmediatamente al servidor. El valor predeterminado es 5 segundos.
+ `region`: de forma predeterminada, el agente publica métricas en la misma Región en la que se encuentra la instancia de contenedor de Amazon ECS. Para anular esto, puede especificar una región diferente aquí. Por ejemplo: ., `"region" : "us-east-1"`

A continuación, se muestra un ejemplo de una configuración personalizada:

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

**Para personalizar la configuración del agente de CloudWatch en los contenedores de Amazon ECS**

1. Asegúrese de que la política **AmazonSSMReadOnlyAccess** esté asociada al rol de ejecución de tarea de Amazon ECS. Para ello, puede escribir el siguiente comando. Este ejemplo presupone que el rol de ejecución de tarea de Amazon ECS es CWAgentECSExecutionRole. Si utiliza otro rol, sustituya el nombre de ese rol en el siguiente comando.

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

1. Cree el archivo de configuración personalizado de forma similar al ejemplo anterior. Asigne a este archivo el nombre `/tmp/ecs-cwagent-daemon-config.json`.

1. Ejecute el siguiente comando para colocar esta configuración en el almacén de parámetros. Sustituya *cluster-region* por la Región del clúster de Amazon ECS. Para ejecutar este comando, debe iniciar sesión en un usuario o rol que tenga la 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. Descargue el archivo de definición de tarea en un archivo 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 el archivo de definición de tarea. Elimine la siguiente sección:

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

   Sustituya esa sección por la siguiente:

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

1. Reinicie el agente como servicio de daemon siguiendo estos pasos:

   1. Ejecute el siguiente comando.

      ```
      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. Ejecute el siguiente comando para lanzar el servicio de daemon. Sustituya *cluster-name* y *cluster-region* por el nombre y la Región del clúster de 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}
      ```

      Si aparece este mensaje de error, `An error occurred (InvalidParameterException) when calling the CreateService operation: Creation of service was not idempotent`, ya ha creado un servicio de daemon llamado `cwagent-daemon-service`. Debe eliminar ese servicio primero, utilizando el siguiente comando como ejemplo.

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