# Criar uma tarefa do Amazon ECS para o EC2 com a AWS CLI
<a name="ECS_AWSCLI_EC2"></a>

As etapas a seguir ajudarão você a configurar um cluster, registrar uma definição de tarefa, executar uma tarefa e realizar outros cenários comuns no Amazon ECS com a AWS CLI. Use a versão mais recente da AWS CLI. Para obter informações sobre como atualizar para a versão mais recente [Consulte instalar ou atualizar para a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).

**nota**  
É possível usar endpoints de serviço de pilha dupla para interagir com o Amazon ECS via AWS CLI, SDKs e API do Amazon ECS sobre IPv4 e IPv6. Para obter mais informações, consulte [Usar endpoints de pilha dupla do Amazon ECS](dual-stack-endpoint.md).

**Topics**
+ [Pré-requisitos](#AWSCLI_EC2_prereq)
+ [Criar um cluster](#AWSCLI_EC2_create_cluster)
+ [Executar uma instância de contêiner com a AMI do Amazon ECS](#AWSCLI_EC2_launch_container_instance)
+ [Listar instâncias de contêiner](#AWSCLI_EC2_list_container_instances)
+ [Descrever sua instância de contêiner](#AWSCLI_EC2_describe_container_instance)
+ [Registrar uma definição de tarefa](#AWSCLI_EC2_register_task_definition)
+ [Listar definições de tarefa](#AWSCLI_EC2_list_task_definitions)
+ [Criar um serviço](#AWSCLI_EC2_run_task)
+ [Listar serviços](#AWSCLI_EC2_list_tasks)
+ [Descrever o serviço](#AWSCLI_EC2_describe_service)
+ [Descrever a tarefa em execução](#AWSCLI_EC2_describe_task)
+ [Testar o servidor Web](#AWSCLI_EC2_test_web_server)
+ [Limpar os recursos](#AWSCLI_EC2_clean_up_resources)

## Pré-requisitos
<a name="AWSCLI_EC2_prereq"></a>

Este tutorial pressupõe que os seguintes pré-requisitos foram concluídos:
+ A versão mais recente da AWS CLI está instalada e configurada. Para obter mais informações sobre como instalar ou atualizar sua AWS CLI, consulte [Instalar ou atualizar para a versão mais recente da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
+ As etapas em [Configuração para usar o Amazon ECS](get-set-up-for-amazon-ecs.md) foram concluídas.
+ O usuário do IAM tem as permissões necessárias especificadas no exemplo de política do IAM de [AmazonECS\$1FullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonECS_FullAccess).
+ Você tem um perfil do IAM de instância de contêiner criado para uso. Para obter informações, consulte [Função do IAM de instância de contêiner do Amazon ECS](instance_IAM_role.md).
+ Você tem uma VPC criada para uso. Para obter mais informações, consulte [Criar uma nuvem privada virtual](get-set-up-for-amazon-ecs.md#create-a-vpc).
+ (Opcional) O AWS CloudShell é uma ferramenta que oferece aos clientes uma linha de comando sem precisar criar a própria instância do EC2. Para obter mais informações, consulte [O que é o AWS CloudShell?](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) no * Guia do usuário do AWS CloudShell*.

## Criar um cluster
<a name="AWSCLI_EC2_create_cluster"></a>

Por padrão, a conta recebe um cluster `default` quando você ativa a primeira instância de contêiner.

**nota**  
O benefício de usar o cluster `default` fornecido é que você não precisa especificar a opção `--cluster cluster_name` nos comandos subsequentes. Caso você crie o próprio cluster, não padrão, é necessário especificar `--cluster cluster_name` para cada comando que deseja usar com esse cluster.

Crie o próprio cluster com um nome exclusivo usando o seguinte comando:

```
aws ecs create-cluster --cluster-name MyCluster
```

Resultado:

```
{
    "cluster": {
        "clusterName": "MyCluster",
        "status": "ACTIVE",
        "clusterArn": "arn:aws:ecs:region:aws_account_id:cluster/MyCluster"
    }
}
```

## Executar uma instância de contêiner com a AMI do Amazon ECS
<a name="AWSCLI_EC2_launch_container_instance"></a>

Instâncias de contêiner são instâncias do EC2 que executam o agente de contêiner do Amazon ECS e foram registradas em um cluster. Nesta seção, você executará uma instância do EC2 usando a AMI otimizada para ECS.

**Para executar uma instância de contêiner com o AWS CLI**

1. Recupere o ID da mais recente AMI do Amazon Linux 2 otimizada para ECS para sua Região da AWS usando o seguinte comando. Esse comando usa o AWS Systems Manager Parameter Store para obter o ID da mais recente AMI otimizada para ECS. A AMI inclui o agente de contêiner do Amazon ECS e o runtime do Docker pré-instalados.

   ```
   aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/recommended --query 'Parameters[0].Value' --output text | jq -r '.image_id'
   ```

   Resultado:

   ```
   ami-abcd1234
   ```

1. Crie um grupo de segurança que permita acesso SSH para gerenciar sua instância de contêiner e acesso HTTP para o servidor Web.

   ```
   aws ec2 create-security-group --group-name ecs-tutorial-sg --description "ECS tutorial security group"
   ```

   Resultado:

   ```
   {
       "GroupId": "sg-abcd1234"
   }
   ```

1. Adicione uma regra de entrada ao grupo de segurança executando o seguinte comando.

   ```
   aws ec2 authorize-security-group-ingress --group-id sg-abcd1234 --protocol tcp --port 80 --cidr 0.0.0.0/0
   ```

   Resultado:

   ```
   {
       "Return": true,
       "SecurityGroupRules": [
           {
               "SecurityGroupRuleId": "sgr-efgh5678",
               "GroupId": "sg-abcd1234",
               "GroupOwnerId": "123456789012",
               "IsEgress": false,
               "IpProtocol": "tcp",
               "FromPort": 80,
               "ToPort": 80,
               "CidrIpv4": "0.0.0.0/0"
           }
       ]
   }
   ```

   Agora, o grupo de segurança permite o acesso SSH do intervalo de IP especificado e acesso HTTP de qualquer lugar. Em um ambiente de produção, você deve restringir o acesso SSH ao seu endereço IP específico e considerar limitar o acesso HTTP conforme necessário.

1. Crie um par de chaves do EC2 para acesso SSH à sua instância de contêiner.

   ```
   aws ec2 create-key-pair --key-name ecs-tutorial-key --query 'KeyMaterial' --output text > ecs-tutorial-key.pem
   chmod 400 ecs-tutorial-key.pem
   ```

   A chave privada fica salva em sua máquina local com as permissões apropriadas para acesso SSH.

1. Inicie uma instância do EC2 usando a AMI otimizada para ECS e configure-a para se juntar ao seu cluster.

   ```
   aws ec2 run-instances --image-id ami-abcd1234 --instance-type t3.micro --key-name ecs-tutorial-key --security-group-ids sg-abcd1234 --iam-instance-profile Name=ecsInstanceRole --user-data '#!/bin/bash
   echo ECS_CLUSTER=MyCluster >> /etc/ecs/ecs.config'
   {
       "Instances": [
           {
               "InstanceId": "i-abcd1234",
               "ImageId": "ami-abcd1234",
               "State": {
                   "Code": 0,
                   "Name": "pending"
               },
               "PrivateDnsName": "",
               "PublicDnsName": "",
               "StateReason": {
                   "Code": "pending",
                   "Message": "pending"
               },
               "InstanceType": "t3.micro",
               "KeyName": "ecs-tutorial-key",
               "LaunchTime": "2025-01-13T10:30:00.000Z"
           }
       ]
   }
   ```

   O script de dados do usuário configura o agente do Amazon ECS para registrar a instância com o seu `MyCluster`. A instância usa a o perfil do IAM `ecsInstanceRole`, que fornece as permissões necessárias para o agente.

## Listar instâncias de contêiner
<a name="AWSCLI_EC2_list_container_instances"></a>

Após alguns minutos do início de sua instância de contêiner, o agente do Amazon ECS registra a instância junto ao cluster MyCluster. É possível listar as instâncias de contêiner em um cluster executando o comando a seguir:

```
aws ecs list-container-instances --cluster MyCluster
```

Resultado:

```
{
    "containerInstanceArns": [
        "arn:aws:ecs:us-east-1:aws_account_id:container-instance/container_instance_ID"
    ]
}
```

## Descrever sua instância de contêiner
<a name="AWSCLI_EC2_describe_container_instance"></a>

Depois que tiver o ARN ou o ID de uma instância de contêiner, será possível usar o comando **describe-container-instances** para obter informações úteis sobre a instância, como recursos de memória e CPU restantes e registrados.

```
aws ecs describe-container-instances --cluster MyCluster --container-instances container_instance_ID
```

Resultado:

```
{
    "failures": [],
    "containerInstances": [
        {
            "status": "ACTIVE",
            "registeredResources": [
                {
                    "integerValue": 1024,
                    "longValue": 0,
                    "type": "INTEGER",
                    "name": "CPU",
                    "doubleValue": 0.0
                },
                {
                    "integerValue": 995,
                    "longValue": 0,
                    "type": "INTEGER",
                    "name": "MEMORY",
                    "doubleValue": 0.0
                },
                {
                    "name": "PORTS",
                    "longValue": 0,
                    "doubleValue": 0.0,
                    "stringSetValue": [
                        "22",
                        "2376",
                        "2375",
                        "51678"
                    ],
                    "type": "STRINGSET",
                    "integerValue": 0
                },
                {
                    "name": "PORTS_UDP",
                    "longValue": 0,
                    "doubleValue": 0.0,
                    "stringSetValue": [],
                    "type": "STRINGSET",
                    "integerValue": 0
                }
            ],
            "ec2InstanceId": "instance_id",
            "agentConnected": true,
            "containerInstanceArn": "arn:aws:ecs:us-west-2:aws_account_id:container-instance/container_instance_ID",
            "pendingTasksCount": 0,
            "remainingResources": [
                {
                    "integerValue": 1024,
                    "longValue": 0,
                    "type": "INTEGER",
                    "name": "CPU",
                    "doubleValue": 0.0
                },
                {
                    "integerValue": 995,
                    "longValue": 0,
                    "type": "INTEGER",
                    "name": "MEMORY",
                    "doubleValue": 0.0
                },
                {
                    "name": "PORTS",
                    "longValue": 0,
                    "doubleValue": 0.0,
                    "stringSetValue": [
                        "22",
                        "2376",
                        "2375",
                        "51678"
                    ],
                    "type": "STRINGSET",
                    "integerValue": 0
                },
                {
                    "name": "PORTS_UDP",
                    "longValue": 0,
                    "doubleValue": 0.0,
                    "stringSetValue": [],
                    "type": "STRINGSET",
                    "integerValue": 0
                }
            ],
            "runningTasksCount": 0,
            "attributes": [
                {
                    "name": "com.amazonaws.ecs.capability.privileged-container"
                },
                {
                    "name": "com.amazonaws.ecs.capability.docker-remote-api.1.17"
                },
                {
                    "name": "com.amazonaws.ecs.capability.docker-remote-api.1.18"
                },
                {
                    "name": "com.amazonaws.ecs.capability.docker-remote-api.1.19"
                },
                {
                    "name": "com.amazonaws.ecs.capability.logging-driver.json-file"
                },
                {
                    "name": "com.amazonaws.ecs.capability.logging-driver.syslog"
                }
            ],
            "versionInfo": {
                "agentVersion": "1.5.0",
                "agentHash": "b197edd",
                "dockerVersion": "DockerVersion: 1.7.1"
            }
        }
    ]
}
```

Também é possível encontrar o ID da instância do Amazon EC2 que é possível usar para monitorar a instância no console do Amazon EC2 ou com o comando **aws ec2 describe-instances --instance-id *instance\$1id***.

## Registrar uma definição de tarefa
<a name="AWSCLI_EC2_register_task_definition"></a>

Para executar uma tarefa em seu cluster do Amazon ECS, você precisa registrar uma definição de tarefa. As definições de tarefa são listas de contêineres agrupados. O exemplo a seguir é uma definição de tarefa simples que usa uma imagem do `nginx`. Para obter mais informações sobre os parâmetros de definição de tarefa disponíveis, consulte [Definições de tarefa do Amazon ECS](task_definitions.md).

```
{
    "family": "nginx-task",
    "containerDefinitions": [
        {
            "name": "nginx",
            "image": "public.ecr.aws/ecs-sample-image/amazon-ecs-sample:latest",
            "cpu": 256,
            "memory": 512,
            "essential": true,
            "portMappings": [
                {
                    "containerPort": 80,
                    "hostPort": 80,
                    "protocol": "tcp"
                }
            ]
        }
    ],
    "requiresCompatibilities": ["EC2"],
    "networkMode": "bridge"
}
```

O exemplo de JSON acima pode ser passado para a AWS CLI de duas maneiras: é possível salvar o JSON de definição de tarefa como um arquivo e passá-lo com a opção `--cli-input-json file://path_to_file.json`. Como alternativa, você pode ignorar as aspas no JSON e passar as definições do contêiner do JSON na linha de comando. Caso você opte por passar as definições de contêiner na linha de comando, o comando ainda exige um parâmetro `--family` usado para manter várias versões da definição de tarefa associadas entre si.

Para usar um arquivo JSON para definições de contêiner:

```
aws ecs register-task-definition --cli-input-json file://$HOME/tasks/nginx.json
```

O **register-task-definition** retornará uma descrição da definição de tarefa depois de concluir o registro.

```
{
    "taskDefinition": {
        "taskDefinitionArn": "arn:aws:ecs:us-east-1:123456789012:task-definition/nginx-task:1",
        "family": "nginx-task",
        "revision": 1,
        "status": "ACTIVE",
        "containerDefinitions": [
            {
                "name": "nginx",
                "image": "public.ecr.aws/docker/library/nginx:latest",
                "cpu": 256,
                "memory": 512,
                "essential": true,
                "portMappings": [
                    {
                        "containerPort": 80,
                        "hostPort": 80,
                        "protocol": "tcp"
                    }
                ],
                "environment": [],
                "mountPoints": [],
                "volumesFrom": []
            }
        ],
        "volumes": [],
        "networkMode": "bridge",
        "compatibilities": [
            "EC2"
        ],
        "requiresCompatibilities": [
            "EC2"
        ]
    }
}
```

## Listar definições de tarefa
<a name="AWSCLI_EC2_list_task_definitions"></a>

É possível listar as definições de tarefa para a conta a qualquer momento com o comando **list-task-definitions**. A saída desse comando mostra os valores `family` e `revision` que você pode usar juntos ao chamar **create-service**.

```
aws ecs list-task-definitions
```

Resultado:

```
{
    "taskDefinitionArns": [
        "arn:aws:ec2:us-east-1:aws_account_id:task-definition/sleep360:1",
        "arn:aws:ec2:us-east-1:aws_account_id:task-definition/sleep360:2",
        "arn:aws:ec2:us-east-1:aws_account_id:task-definition/nginx-task:1",
        "arn:aws:ec2:us-east-1:aws_account_id:task-definition/wordpress:3",
        "arn:aws:ec2:us-east-1:aws_account_id:task-definition/wordpress:4",
        "arn:aws:ec2:us-east-1:aws_account_id:task-definition/wordpress:5",
        "arn:aws:ec2:us-east-1:aws_account_id:task-definition/wordpress:6"
    ]
}
```

## Criar um serviço
<a name="AWSCLI_EC2_run_task"></a>

Depois de ter registrado uma tarefa para sua conta e iniciado uma instância de contêiner que está registrada no seu cluster, você pode criar um serviço do Amazon ECS que executa e mantém um número desejado de tarefas simultaneamente usando a definição de tarefa que você registrou. Neste exemplo, você coloca uma única instância da definição de tarefa `nginx:1` no cluster MyCluster.

```
aws ecs create-service --cluster MyCluster --service-name nginx-service --task-definition nginx-task:1 --desired-count 1
```

Resultado:

```
{
    "service": {
        "serviceArn": "arn:aws:ecs:us-east-1:aws_account_id:service/MyCluster/nginx-service",
        "serviceName": "nginx-service",
        "clusterArn": "arn:aws:ecs:us-east-1:aws_account_id:cluster/MyCluster",
        "taskDefinition": "arn:aws:ecs:us-east-1:aws_account_id:task-definition/nginx-task:1",
        "desiredCount": 1,
        "runningCount": 0,
        "pendingCount": 0,
        "launchType": "EC2",
        "status": "ACTIVE",
        "createdAt": "2025-01-13T10:45:00.000Z"
    }
}
```

## Listar serviços
<a name="AWSCLI_EC2_list_tasks"></a>

Liste os serviços para o seu cluster. Você deve ver o serviço que criou na seção anterior. É possível anotar o ID do serviço ou o ARN completo retornado por esse comando e usá-lo para descrever o serviço depois.

```
aws ecs list-services --cluster MyCluster
```

Resultado:

```
{
    "taskArns": [
        "arn:aws:ecs:us-east-1:aws_account_id:task/task_ID"
    ]
}
```

## Descrever o serviço
<a name="AWSCLI_EC2_describe_service"></a>

Descreva o serviço usando o seguinte comando para obter mais informações sobre o serviço.

```
aws ecs describe-services --cluster MyCluster --services nginx-service
```

Resultado:

```
{
    "services": [
        {
            "serviceArn": "arn:aws:ecs:us-east-1:aws_account_id:service/MyCluster/nginx-service",
            "serviceName": "nginx-service",
            "clusterArn": "arn:aws:ecs:us-east-1:aws_account_id:cluster/MyCluster",
            "taskDefinition": "arn:aws:ecs:us-east-1:aws_account_id:task-definition/nginx-task:1",
            "desiredCount": 1,
            "runningCount": 1,
            "pendingCount": 0,
            "launchType": "EC2",
            "status": "ACTIVE",
            "createdAt": "2025-01-13T10:45:00.000Z",
            "events": [
                {
                    "id": "abcd1234-5678-90ab-cdef-1234567890ab",
                    "createdAt": "2025-01-13T10:45:30.000Z",
                    "message": "(service nginx-service) has started 1 tasks: (task abcd1234-5678-90ab-cdef-1234567890ab)."
                }
            ]
        }
    ]
}
```

## Descrever a tarefa em execução
<a name="AWSCLI_EC2_describe_task"></a>

Após descrever o serviço, execute o seguinte comando para obter mais informações sobre a tarefa que está sendo executada como parte do seu serviço.

```
aws ecs list-tasks --cluster MyCluster --service-name nginx-service
```

 Resultado: 

```
{
    "tasks": [
        {
            "taskArn": "arn:aws:ecs:us-east-1:aws_account_id:task/MyCluster/abcd1234-5678-90ab-cdef-1234567890ab",
            "clusterArn": "arn:aws:ecs:us-east-1:aws_account_id:cluster/MyCluster",
            "taskDefinitionArn": "arn:aws:ecs:us-east-1:aws_account_id:task-definition/nginx-task:1",
            "containerInstanceArn": "arn:aws:ecs:us-east-1:aws_account_id:container-instance/MyCluster/abcd1234-5678-90ab-cdef-1234567890ab",
            "lastStatus": "RUNNING",
            "desiredStatus": "RUNNING",
            "containers": [
                {
                    "containerArn": "arn:aws:ecs:us-east-1:aws_account_id:container/MyCluster/abcd1234-5678-90ab-cdef-1234567890ab/abcd1234-5678-90ab-cdef-1234567890ab",
                    "taskArn": "arn:aws:ecs:us-east-1:aws_account_id:task/MyCluster/abcd1234-5678-90ab-cdef-1234567890ab",
                    "name": "nginx",
                    "lastStatus": "RUNNING",
                    "networkBindings": [
                        {
                            "bindIP": "0.0.0.0",
                            "containerPort": 80,
                            "hostPort": 80,
                            "protocol": "tcp"
                        }
                    ]
                }
            ],
            "createdAt": "2025-01-13T10:45:00.000Z",
            "startedAt": "2025-01-13T10:45:30.000Z"
        }
    ]
}
```

## Testar o servidor Web
<a name="AWSCLI_EC2_test_web_server"></a>

**Para testar o servidor Web**

1. Recupere o endereço IP público da sua instância de contêiner executando o seguinte comando.

   ```
   aws ec2 describe-instances --instance-ids i-abcd1234 --query 'Reservations[0].Instances[0].PublicIpAddress' --output text
   ```

   Resultado:

   ```
   203.0.113.25
   ```

1. Após recuperar o endereço IP, execute o seguinte comando `curl` com o endereço IP.

   ```
   curl http://203.0.113.25
   ```

   Resultado:

   ```
   <!DOCTYPE html>
   <html>
   <head>
   <title>Welcome to nginx!</title>
   ...
   </head>
   <body>
   <h1>Welcome to nginx!</h1>
   <p>If you can see this page, the nginx web server is successfully installed and working.</p>
   ...
   </body>
   </html>
   ```

   A página de boas-vindas do nginx confirmará que seu serviço está funcionando com sucesso e pode ser acessado pela Internet.

## Limpar os recursos
<a name="AWSCLI_EC2_clean_up_resources"></a>

Para evitar a geração de cobranças, limpe os recursos que foram criados neste tutorial.

**Para limpar os recursos**

1. Atualize o serviço para ter zero tarefas desejadas e, em seguida, exclua o serviço.

   ```
   aws ecs update-service --cluster MyCluster --service nginx-service --desired-count 0
   {
       "service": {
           "serviceArn": "arn:aws:ecs:us-east-1:123456789012:service/MyCluster/nginx-service",
           "serviceName": "nginx-service",
           "desiredCount": 0,
           "runningCount": 1,
           "pendingCount": 0,
           "status": "ACTIVE"
       }
   }
   ```

1. Aguarde até que as tarefas em execução parem e, em seguida, exclua o serviço.

   ```
   aws ecs delete-service --cluster MyCluster --service nginx-service
   {
       "service": {
           "serviceArn": "arn:aws:ecs:us-east-1:123456789012:service/MyCluster/nginx-service",
           "serviceName": "nginx-service",
           "status": "DRAINING"
       }
   }
   ```

1. Encerre a instância de contêiner que você criou.

   ```
   aws ec2 terminate-instances --instance-ids i-abcd1234
   {
       "TerminatingInstances": [
           {
               "InstanceId": "i-abcd1234",
               "CurrentState": {
                   "Code": 32,
                   "Name": "shutting-down"
               },
               "PreviousState": {
                   "Code": 16,
                   "Name": "running"
               }
           }
       ]
   }
   ```

1. Limpe o grupo de segurança e o par de chaves que você criou.

   ```
   aws ec2 delete-security-group --group-id sg-abcd1234
   aws ec2 delete-key-pair --key-name ecs-tutorial-key
   rm ecs-tutorial-key.pem
   ```

1. Exclua o cluster do Amazon ECS.

   ```
   aws ecs delete-cluster --cluster MyCluster
   {
       "cluster": {
           "clusterArn": "arn:aws:ecs:us-east-1:123456789012:cluster/MyCluster",
           "clusterName": "MyCluster",
           "status": "INACTIVE"
       }
   }
   ```