# Criar uma tarefa do Linux do Amazon ECS para o Fargate com a AWS CLI
<a name="ECS_AWSCLI_Fargate"></a>

As etapas a seguir ajudarão você a configurar um cluster, registrar uma definição de tarefa, executar uma tarefa do Linux 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](#ECS_AWSCLI_Fargate_prereq)
+ [Etapa 1: criar um cluster](#ECS_AWSCLI_Fargate_create_cluster)
+ [Etapa 2: registrar uma definição de tarefa do Linux](#ECS_AWSCLI_Fargate_register_task_definition)
+ [Etapa 3: listar definições de tarefa](#ECS_AWSCLI_Fargate_list_task_definitions)
+ [Etapa 4: criar um serviço](#ECS_AWSCLI_Fargate_create_service)
+ [Etapa 5: listar serviços](#ECS_AWSCLI_Fargate_list_services)
+ [Etapa 6: descrever o serviço em execução](#ECS_AWSCLI_Fargate_describe_service)
+ [Etapa 7: testar](#ECS_AWSCLI_Fargate_test)
+ [Etapa 8: limpar](#ECS_AWSCLI_Fargate_clean_up)

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

Este tutorial pressupõe que os pré-requisitos a seguir 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 uma VPC e um grupo de segurança criados para uso. Este tutorial usa uma imagem de contêiner hospedada no Amazon ECR Public, portanto, sua tarefa deve ter acesso à Internet. Para fornecer à sua tarefa uma rota para a Internet, use uma das opções a seguir.
  + Use uma sub-rede privada com um gateway NAT que tenha um endereço IP elástico.
  + Use uma sub-rede pública e atribua um endereço IP público à tarefa.

  Para obter mais informações, consulte [Criar uma nuvem privada virtual](get-set-up-for-amazon-ecs.md#create-a-vpc).

  Para obter informações sobre grupos de segurança e regras, consulte [Grupos de segurança padrão para VPCs](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#DefaultSecurityGroup) e [Exemplo de regras](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html#security-group-rule-examples) no *Guia do usuário da Amazon Virtual Private Cloud*.
+  Se você seguir este tutorial usando uma sub-rede privada, poderá usar o Amazon ECS Exec para interagir diretamente com seu contêiner e testar a implantação. Você precisará criar um perfil do IAM de tarefa para usar o ECS Exec. Para obter mais informações sobre o perfil do IAM da tarefa e outros pré-requisitos, consulte [Monitorar contêineres do Amazon ECS com o Amazon ECS Exec](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html).
+ (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*.

## Etapa 1: criar um cluster
<a name="ECS_AWSCLI_Fargate_create_cluster"></a>

Por padrão, sua conta recebe um cluster `default`.

**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 fargate-cluster
```

Resultado:

```
{
    "cluster": {
        "status": "ACTIVE", 
        "defaultCapacityProviderStrategy": [], 
        "statistics": [], 
        "capacityProviders": [], 
        "tags": [], 
        "clusterName": "fargate-cluster", 
        "settings": [
            {
                "name": "containerInsights", 
                "value": "disabled"
            }
        ], 
        "registeredContainerInstancesCount": 0, 
        "pendingTasksCount": 0, 
        "runningTasksCount": 0, 
        "activeServicesCount": 0, 
        "clusterArn": "arn:aws:ecs:region:aws_account_id:cluster/fargate-cluster"
    }
}
```

## Etapa 2: registrar uma definição de tarefa do Linux
<a name="ECS_AWSCLI_Fargate_register_task_definition"></a>

Para executar uma tarefa no cluster do ECS, você deve 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 cria um aplicativo web em PHP usando a imagem de contêiner httpd hospedada no Docker Hub. 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). Para este tutorial, o `taskRoleArn` só será necessário se você estiver implantando a tarefa em uma sub-rede privada e quiser testar a implantação. Substitua o `taskRoleArn` pelo perfil da tarefa do IAM que você criou para usar o ECS Exec, conforme mencionado em [Pré-requisitos](#ECS_AWSCLI_Fargate_prereq).

```
 {
        "family": "sample-fargate",
        "networkMode": "awsvpc",
        "taskRoleArn": "arn:aws:iam::aws_account_id:role/execCommandRole", 
        "containerDefinitions": [
            {
                "name": "fargate-app",
                "image": "public.ecr.aws/docker/library/httpd:latest",
                "portMappings": [
                    {
                        "containerPort": 80,
                        "hostPort": 80,
                        "protocol": "tcp"
                    }
                ],
                "essential": true,
                "entryPoint": [
                    "sh",
                    "-c"
                ],
                "command": [
                    "/bin/sh -c \"echo '<html> <head> <title>Amazon ECS Sample App</title> <style>body {margin-top: 40px; background-color: #333;} </style> </head><body> <div style=color:white;text-align:center> <h1>Amazon ECS Sample App</h1> <h2>Congratulations!</h2> <p>Your application is now running on a container in Amazon ECS.</p> </div></body></html>' >  /usr/local/apache2/htdocs/index.html && httpd-foreground\""
                ]
            }
        ],
        "requiresCompatibilities": [
            "FARGATE"
        ],
        "cpu": "256",
        "memory": "512"
}
```

Salve a definição da tarefa JSON como um arquivo e passe-a com a opção `--cli-input-json file://path_to_file.json`. 

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

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

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

## Etapa 3: listar definições de tarefa
<a name="ECS_AWSCLI_Fargate_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` valores que você pode usar juntos ao chamar **run-task** ou **start-task**.

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

Resultado:

```
{
    "taskDefinitionArns": [
        "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate:1"
    ]
}
```

## Etapa 4: criar um serviço
<a name="ECS_AWSCLI_Fargate_create_service"></a>

Depois de você registrar uma tarefa para sua conta, poderá criar um serviço para a tarefa registrada no seu cluster. Para este exemplo, crie um serviço com uma instância da definição de tarefa `sample-fargate:1` em execução no cluster. A tarefa requer uma rota para a internet, então há duas maneiras de conseguir isso. Uma maneira é usar uma sub-rede privada configurada com um gateway NAT com um endereço IP elástico em uma sub-rede pública. Outra maneira é usar uma sub-rede pública e atribuir um endereço IP público à tarefa. Fornecemos os dois exemplos abaixo. 

Exemplo usando uma sub-rede privada. A ` enable-execute-command ` opção é necessária para usar o Amazon ECS Exec.

```
aws ecs create-service --cluster fargate-cluster --service-name fargate-service --task-definition sample-fargate:1 --desired-count 1 --launch-type "FARGATE" --network-configuration "awsvpcConfiguration={subnets=[subnet-abcd1234],securityGroups=[sg-abcd1234]}" --enable-execute-command
```

Exemplo usando uma sub-rede pública.

```
aws ecs create-service --cluster fargate-cluster --service-name fargate-service --task-definition sample-fargate:1 --desired-count 1 --launch-type "FARGATE" --network-configuration "awsvpcConfiguration={subnets=[subnet-abcd1234],securityGroups=[sg-abcd1234],assignPublicIp=ENABLED}"
```

O comando **create-service** retorna uma descrição da definição de tarefa depois de concluir o registro.

## Etapa 5: listar serviços
<a name="ECS_AWSCLI_Fargate_list_services"></a>

Liste os serviços para o seu cluster. Você deve ver o serviço que criou na seção anterior. É possível utilizar o nome 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 fargate-cluster
```

Resultado:

```
{
    "serviceArns": [
        "arn:aws:ecs:region:aws_account_id:service/fargate-cluster/fargate-service"
    ]
}
```

## Etapa 6: descrever o serviço em execução
<a name="ECS_AWSCLI_Fargate_describe_service"></a>

Descreva o serviço usando o nome do serviço recuperado anteriormente para obter mais informações sobre a tarefa.

```
aws ecs describe-services --cluster fargate-cluster --services fargate-service
```

Se for bem-sucedido, isso retornará uma descrição das falhas de serviço e os serviços. Por exemplo, na seção ` services `, você encontrará informações sobre implantações, como o status das tarefas como pendentes ou em execução. Também é possível encontrar informações sobre a definição da tarefa, a configuração da rede e os eventos com time stamp. Na seção de falhas, você encontrará informações sobre falhas, se houver, associadas à chamada. Para solução de problemas, consulte [Mensagens de eventos de serviço](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/service-event-messages.html). Para obter mais informações sobre a descrição do serviço, consulte [Descrever serviços](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeServices).

```
{
    "services": [
        {
            "networkConfiguration": {
                "awsvpcConfiguration": {
                    "subnets": [
                        "subnet-abcd1234"
                    ], 
                    "securityGroups": [
                        "sg-abcd1234"
                    ], 
                    "assignPublicIp": "ENABLED"
                }
            }, 
            "launchType": "FARGATE", 
            "enableECSManagedTags": false, 
            "loadBalancers": [], 
            "deploymentController": {
                "type": "ECS"
            }, 
            "desiredCount": 1, 
            "clusterArn": "arn:aws:ecs:region:aws_account_id:cluster/fargate-cluster", 
            "serviceArn": "arn:aws:ecs:region:aws_account_id:service/fargate-service", 
            "deploymentConfiguration": {
                "maximumPercent": 200, 
                "minimumHealthyPercent": 100
            }, 
            "createdAt": 1692283199.771, 
            "schedulingStrategy": "REPLICA", 
            "placementConstraints": [], 
            "deployments": [
                {
                    "status": "PRIMARY", 
                    "networkConfiguration": {
                        "awsvpcConfiguration": {
                            "subnets": [
                                "subnet-abcd1234"
                            ], 
                            "securityGroups": [
                                "sg-abcd1234"
                            ], 
                            "assignPublicIp": "ENABLED"
                        }
                    }, 
                    "pendingCount": 0, 
                    "launchType": "FARGATE", 
                    "createdAt": 1692283199.771, 
                    "desiredCount": 1, 
                    "taskDefinition": "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate:1", 
                    "updatedAt": 1692283199.771, 
                    "platformVersion": "1.4.0", 
                    "id": "ecs-svc/9223370526043414679", 
                    "runningCount": 0
                }
            ], 
            "serviceName": "fargate-service", 
            "events": [
                {
                    "message": "(service fargate-service) has started 2 tasks: (task 53c0de40-ea3b-489f-a352-623bf1235f08) (task d0aec985-901b-488f-9fb4-61b991b332a3).", 
                    "id": "92b8443e-67fb-4886-880c-07e73383ea83", 
                    "createdAt": 1510811841.408
                }, 
                {
                    "message": "(service fargate-service) has started 2 tasks: (task b4911bee-7203-4113-99d4-e89ba457c626) (task cc5853e3-6e2d-4678-8312-74f8a7d76474).", 
                    "id": "d85c6ec6-a693-43b3-904a-a997e1fc844d", 
                    "createdAt": 1510811601.938
                }, 
                {
                    "message": "(service fargate-service) has started 2 tasks: (task cba86182-52bf-42d7-9df8-b744699e6cfc) (task f4c1ad74-a5c6-4620-90cf-2aff118df5fc).", 
                    "id": "095703e1-0ca3-4379-a7c8-c0f1b8b95ace", 
                    "createdAt": 1510811364.691
                }
            ], 
            "runningCount": 0, 
            "status": "ACTIVE", 
            "serviceRegistries": [], 
            "pendingCount": 0, 
            "createdBy": "arn:aws:iam::aws_account_id:user/user_name", 
            "platformVersion": "LATEST", 
            "placementStrategy": [], 
            "propagateTags": "NONE", 
            "roleArn": "arn:aws:iam::aws_account_id:role/aws-service-role/ecs.amazonaws.com/AWSServiceRoleForECS", 
            "taskDefinition": "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate:1"
        }
    ], 
    "failures": []
}
```

## Etapa 7: testar
<a name="ECS_AWSCLI_Fargate_test"></a>

### Tarefa de teste implantada usando sub-rede pública
<a name="ECS_AWSCLI_Fargate_test_public"></a>

Descreva a tarefa no serviço para que você possa obter a Elastic Network Interface (ENI) para a tarefa. 

Primeiramente, obtenha o ARN da tarefa.

```
aws ecs list-tasks --cluster fargate-cluster --service fargate-service
```

A saída contém o ARN da tarefa.

```
{
    "taskArns": [
        "arn:aws:ecs:us-east-1:123456789012:task/fargate-service/EXAMPLE
    ]
}
```

Descreva a tarefa e localize o ID da ENI. Use o ARN da tarefa para o parâmetro `tasks`.

```
aws ecs describe-tasks --cluster fargate-cluster --tasks arn:aws:ecs:us-east-1:123456789012:task/service/EXAMPLE
```

As informações do anexo estão listadas na saída. 

```
{
    "tasks": [
        {
            "attachments": [
                {
                    "id": "d9e7735a-16aa-4128-bc7a-b2d5115029e9",
                    "type": "ElasticNetworkInterface",
                    "status": "ATTACHED",
                    "details": [
                        {
                            "name": "subnetId",
                            "value": "subnetabcd1234"
                        },
                        {
                            "name": "networkInterfaceId",
                            "value": "eni-0fa40520aeEXAMPLE"
                        },
                    ]
                }
…
}
```

Descreva o ENI para obter o endereço IP público.

```
aws ec2 describe-network-interfaces --network-interface-id  eni-0fa40520aeEXAMPLE
```

O endereço IP público está na saída. 

```
{
    "NetworkInterfaces": [
        {
            "Association": {
                "IpOwnerId": "amazon",
                "PublicDnsName": "ec2-34-229-42-222.compute-1.amazonaws.com",
                "PublicIp": "198.51.100.2"
            },
…
}
```

Insira o endereço IP público no seu navegador da Web, e você deverá ver uma página da Web que exibe a aplicação de exemplo **Amazon ECS**.

### Tarefa de teste implantada usando sub-rede privada
<a name="ECS_AWSCLI_Fargate_test_private.title"></a>

 Descreva a tarefa e localize `managedAgents` para verificar se o `ExecuteCommandAgent` está em execução. Anote o `privateIPv4Address` para uso posterior.

```
aws ecs describe-tasks --cluster fargate-cluster --tasks arn:aws:ecs:us-east-1:123456789012:task/fargate-service/EXAMPLE
```

 As informações do agente gerenciado estão listadas na saída. 

```
{
     "tasks": [
        {
            "attachments": [
                {
                    "id": "d9e7735a-16aa-4128-bc7a-b2d5115029e9",
                    "type": "ElasticNetworkInterface",
                    "status": "ATTACHED",
                    "details": [
                        {
                            "name": "subnetId",
                            "value": "subnetabcd1234"
                        },
                        {
                            "name": "networkInterfaceId",
                            "value": "eni-0fa40520aeEXAMPLE"
                        },
                        {
                            "name": "privateIPv4Address",
                            "value": "10.0.143.156"
                        }
                    ]
                }
            ],
     ...  
     "containers": [
         {
         ...
        "managedAgents": [
                        {
                            "lastStartedAt": "2023-08-01T16:10:13.002000+00:00",
                            "name": "ExecuteCommandAgent",
                            "lastStatus": "RUNNING"
                        } 
                ],
        ...
    }
```

 Depois de verificar se o ` ExecuteCommandAgent` está em execução, execute o comando a seguir para executar um shell interativo no contêiner da tarefa. 

```
  aws ecs execute-command --cluster fargate-cluster \
      --task  arn:aws:ecs:us-east-1:123456789012:task/fargate-service/EXAMPLE  \
      --container  fargate-app \
      --interactive \
      --command "/bin/sh"
```

 Depois que o shell interativo estiver em execução, execute os comandos a seguir para instalar o cURL. 

```
apt update 
```

```
apt install curl 
```

 Depois de instalar o cURL, execute o comando a seguir usando o endereço IP privado que você obteve anteriormente.

```
 curl 10.0.143.156 
```

 Você deve ver o equivalente em HTML da página da Web da aplicação de amostra do **Amazon ECS**.

```
<html>
    <head> 
     <title>Amazon ECS Sample App</title> 
     <style>body {margin-top: 40px; background-color: #333;} </style>
    </head>
      <body> 
      <div style=color:white;text-align:center> 
      <h1>Amazon ECS Sample App</h1> 
      <h2>Congratulations!</h2> <p>Your application is now running on a container in Amazon ECS.</p> 
      </div>
      </body>
</html>
```

## Etapa 8: limpar
<a name="ECS_AWSCLI_Fargate_clean_up"></a>

Ao concluir este tutorial, você deve limpar os recursos associados para evitar cobranças por recursos não utilizados.

Exclua o serviço.

```
aws ecs delete-service --cluster fargate-cluster --service fargate-service --force
```

Excluir o cluster.

```
aws ecs delete-cluster --cluster fargate-cluster
```