# Como criar uma tarefa para instâncias gerenciadas do Amazon ECS com a AWS CLI
<a name="getting-started-managed-instances-cli"></a>

 As etapas a seguir ajudarão você a configurar um cluster, criar um provedor de capacidade, registrar uma definição de tarefa, executar uma tarefa do Linux e realizar outros cenários comuns no Amazon ECS com instâncias gerenciadas do Amazon ECS usando 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 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). 

**Tópicos**
+ [Pré-requisitos](#managed-instances-cli-prereq)
+ [Etapa 1: criar um cluster](#managed-instances-cli-create-cluster)
+ [Etapa 2: criar um provedor de capacidade de instâncias gerenciadas do Amazon ECS](#managed-instances-cli-create-capacity-provider)
+ [Etapa 3: configurar a estratégia padrão do provedor de capacidade do cluster](#managed-instances-cli-configure-cluster)
+ [Etapa 4: registrar uma definição de tarefa do Linux](#managed-instances-cli-register-task-definition)
+ [Etapa 5: listar definições de tarefa](#managed-instances-cli-list-task-definitions)
+ [Etapa 6: criar um serviço](#managed-instances-cli-create-service)
+ [Etapa 7: listar serviços](#managed-instances-cli-list-services)
+ [Etapa 8: descrever o serviço em execução](#managed-instances-cli-describe-service)
+ [Etapa 9: testar](#managed-instances-cli-test)
+ [Etapa 10: limpar](#managed-instances-cli-clean-up)

## Pré-requisitos
<a name="managed-instances-cli-prereq"></a>

 Antes de começar o tutorial, conclua as seguintes etapas: 
+ Você concluiu as etapas em [Configurar o uso do Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/get-set-up-for-amazon-ecs.html).
+ A versão mais recente da AWS CLI está instalada e configurada. Para obter mais informações sobre instalação ou atualização da AWS CLI, consulte [Instalar ou atualizar para a última versão da AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) no *Guia do usuário da AWS Command Line Interface*.
+ As etapas em [Configuração para usar o Amazon ECS](get-set-up-for-amazon-ecs.md) foram concluídas.
+ Você tem os perfis do IAM necessários para instâncias gerenciadas do Amazon ECS. Isso inclui:
  + Perfil de infraestrutura: permite que o Amazon ECS faça chamadas para serviços da AWS em seu nome para gerenciar a infraestrutura de instâncias gerenciadas do Amazon ECS.

    Para obter mais informações, consulte [Perfil do IAM de infraestrutura do Amazon ECS](infrastructure_IAM_role.md).
  + Perfil de instância: fornece permissões para o agente de contêiner do Amazon ECS e para o daemon do Docker em execução nas instâncias gerenciadas.

    O nome do perfil de instância deve incluir `ecsInstanceRole` como prefixo para corresponder à ação `iam:PassRole` no perfil de infraestrutura.

    Para obter mais informações, consulte [Perfil de instância de instâncias gerenciadas do Amazon ECS](managed-instances-instance-profile.md).
+ 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, de modo que suas instâncias devem ter acesso à internet. Para fornecer às suas instâncias uma rota para a internet, use uma das seguintes opções:
  + 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 às instâncias.

  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*.
+ (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 é 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="managed-instances-cli-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 managed-instances-cluster
```

Resultado:

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

## Etapa 2: criar um provedor de capacidade de instâncias gerenciadas do Amazon ECS
<a name="managed-instances-cli-create-capacity-provider"></a>

 Para poder executar tarefas usando as instâncias gerenciadas do Amazon ECS, crie um provedor de capacidade que defina a configuração da infraestrutura. O provedor de capacidade especifica os perfis do IAM, a configuração de rede e outras definições para suas instâncias gerenciadas. 

 Crie um arquivo JSON com a configuração do provedor de capacidade. Substitua os valores dos espaços reservados por seus identificadores de recursos reais: 

```
{
    "name": "managed-instances-cp",
    "cluster": "managed-instances-cluster",
    "managedInstancesProvider": {
        "infrastructureRoleArn": "arn:aws:iam::aws_account_id:role/ecsInfrastructureRole",
        "instanceLaunchTemplate": {
            "ec2InstanceProfileArn": "arn:aws:iam::aws_account_id:instance-profile/ecsInstanceRole",
            "networkConfiguration": {
                "subnets": [
                    "subnet-abcdef01234567890",
                    "subnet-1234567890abcdef0"
                ],
                "securityGroups": [
                    "sg-0123456789abcdef0"
                ]
            },
            "storageConfiguration": {
                "storageSizeGiB": 100
            },
            "monitoring": "basic"
        }
    }
}
```

 Salve essa configuração como `managed-instances-cp.json` e crie o provedor de capacidade: 

```
aws ecs create-capacity-provider --cli-input-json file://managed-instances-cp.json
```

 O comando retorna uma descrição do provedor de capacidade após concluir sua criação. 

## Etapa 3: configurar a estratégia padrão do provedor de capacidade do cluster
<a name="managed-instances-cli-configure-cluster"></a>

 Atualize o cluster para usar o provedor de capacidade de instâncias gerenciadas do Amazon ECS como estratégia padrão do provedor de capacidade. Isso permite que tarefas e serviços usem automaticamente as instâncias gerenciadas do Amazon ECS sem especificar explicitamente o provedor de capacidade. 

 Crie um arquivo JSON com a configuração do provedor de capacidade do cluster: 

```
{
    "cluster": "managed-instances-cluster",
    "capacityProviders": [
        "managed-instances-cp"
    ],
    "defaultCapacityProviderStrategy": [
        {
            "capacityProvider": "managed-instances-cp",
            "weight": 1
        }
    ]
}
```

 Salve essa configuração como `cluster-cp-strategy.json` e atualize o cluster: 

```
aws ecs put-cluster-capacity-providers --cli-input-json file://cluster-cp-strategy.json
```

## Etapa 4: registrar uma definição de tarefa do Linux
<a name="managed-instances-cli-register-task-definition"></a>

 Para executar uma tarefa no seu cluster, 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 [Parâmetros de definição de tarefa do Amazon ECS para o Fargate](task_definition_parameters.md). 

```
{
    "family": "sample-managed-instances",
    "networkMode": "awsvpc",
    "containerDefinitions": [
        {
            "name": "managed-instances-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 using Amazon ECS Managed Instances.</p></div></body></html>' >  /usr/local/apache2/htdocs/index.html && httpd-foreground\""
            ]
        }
    ],
    "requiresCompatibilities": [
        "MANAGED_INSTANCES"
    ],
    "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/managed-instances-task.json
```

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

## Etapa 5: listar definições de tarefa
<a name="managed-instances-cli-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-managed-instances:1"
    ]
}
```

## Etapa 6: criar um serviço
<a name="managed-instances-cli-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-managed-instances: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: 

```
aws ecs create-service --cluster managed-instances-cluster --service-name managed-instances-service --task-definition sample-managed-instances:1 --desired-count 1 --network-configuration "awsvpcConfiguration={subnets=[subnet-abcd1234],securityGroups=[sg-abcd1234]}"
```

 Exemplo usando uma sub-rede pública: 

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

 O comando **create-service** retorna uma descrição do serviço depois de concluir sua criação. 

## Etapa 7: listar serviços
<a name="managed-instances-cli-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 managed-instances-cluster
```

Resultado:

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

## Etapa 8: descrever o serviço em execução
<a name="managed-instances-cli-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 managed-instances-cluster --services managed-instances-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. 

 O resultado mostrará que o serviço está usando o provedor de capacidade de instâncias gerenciadas do Amazon ECS: 

```
{
    "services": [
        {
            "capacityProviderStrategy": [
                {
                    "capacityProvider": "managed-instances-cp",
                    "weight": 1,
                    "base": 0
                }
            ],
            "networkConfiguration": {
                "awsvpcConfiguration": {
                    "subnets": [
                        "subnet-abcd1234"
                    ], 
                    "securityGroups": [
                        "sg-abcd1234"
                    ], 
                    "assignPublicIp": "ENABLED"
                }
            }, 
            "enableECSManagedTags": false, 
            "loadBalancers": [], 
            "deploymentController": {
                "type": "ECS"
            }, 
            "desiredCount": 1, 
            "clusterArn": "arn:aws:ecs:region:aws_account_id:cluster/managed-instances-cluster", 
            "serviceArn": "arn:aws:ecs:region:aws_account_id:service/managed-instances-service", 
            "serviceName": "managed-instances-service",
            "taskDefinition": "arn:aws:ecs:region:aws_account_id:task-definition/sample-managed-instances:1"
        }
    ], 
    "failures": []
}
```

## Etapa 9: testar
<a name="managed-instances-cli-test"></a>

 Para testar sua implantação, você precisa encontrar o endereço IP público da instância gerenciada que executa sua tarefa. 

### Tarefa de teste implantada usando sub-rede pública
<a name="managed-instances-cli-test-public-subnet"></a>

 Primeiramente, obtenha o ARN da tarefa do seu serviço: 

```
aws ecs list-tasks --cluster managed-instances-cluster --service managed-instances-service
```

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

```
{
    "taskArns": [
        "arn:aws:ecs:region:aws_account_id:task/managed-instances-cluster/EXAMPLE"
    ]
}
```

 Descreva a tarefa para obter o ARN da instância de contêiner. Use o ARN da tarefa para o parâmetro `tasks`: 

```
aws ecs describe-tasks --cluster managed-instances-cluster --tasks arn:aws:ecs:region:aws_account_id:task/managed-instances-cluster/EXAMPLE
```

 A saída mostra que a tarefa está sendo executada nas instâncias gerenciadas do Amazon ECS e inclui o ARN da instância de contêiner: 

```
{
    "tasks": [
        {
            "launchType": "MANAGED_INSTANCES",
            "capacityProviderName": "managed-instances-cp",
            "containerInstanceArn": "arn:aws:ecs:region:aws_account_id:container-instance/managed-instances-cluster/CONTAINER_INSTANCE_ID",
            "taskArn": "arn:aws:ecs:region:aws_account_id:task/managed-instances-cluster/EXAMPLE",
            "taskDefinitionArn": "arn:aws:ecs:region:aws_account_id:task-definition/sample-managed-instances:1"
        }
    ]
}
```

 Descreva a instância de contêiner para obter o ID da instância do EC2: 

```
aws ecs describe-container-instances --cluster managed-instances-cluster --container-instances CONTAINER_INSTANCE_ID
```

 A saída inclui o ID da instância do EC2: 

```
{
    "containerInstances": [
        {
            "ec2InstanceId": "i-1234567890abcdef0",
            "capacityProviderName": "managed-instances-cp",
            "containerInstanceArn": "arn:aws:ecs:region:aws_account_id:container-instance/managed-instances-cluster/CONTAINER_INSTANCE_ID"
        }
    ]
}
```

 Descreva a instância do EC2 para obter o endereço IP público: 

```
aws ec2 describe-instances --instance-ids i-1234567890abcdef0
```

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

```
{
    "Reservations": [
        {
            "Instances": [
                {
                    "PublicIpAddress": "198.51.100.2",
                    "InstanceId": "i-1234567890abcdef0"
                }
            ]
        }
    ]
}
```

 Insira o endereço IP público no seu navegador da web e verá uma página que exibe a aplicação de exemplo **Amazon ECS** em execução nas instâncias gerenciadas do Amazon ECS.. 

### Tarefa de teste implantada usando sub-rede privada
<a name="managed-instances-cli-test-private-subnet"></a>

 Para tarefas implantadas em sub-redes privadas, você pode usar o Amazon ECS Exec para se conectar ao contêiner e testar a implantação de dentro da instância. Siga as mesmas etapas acima para obter o ARN da tarefa e, em seguida, use o ECS Exec: 

```
aws ecs execute-command --cluster managed-instances-cluster \
    --task arn:aws:ecs:region:aws_account_id:task/managed-instances-cluster/EXAMPLE \
    --container managed-instances-app \
    --interactive \
    --command "/bin/sh"
```

 Depois que o shell interativo estiver em execução, você poderá testar o servidor web: 

```
curl localhost
```

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

## Etapa 10: limpar
<a name="managed-instances-cli-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 de : 

```
aws ecs delete-service --cluster managed-instances-cluster --service managed-instances-service --force
```

 Aguarde até que o serviço seja excluído e todas as tarefas interrompidas; em seguida, exclua o provedor de capacidade: 

```
aws ecs delete-capacity-provider --capacity-provider managed-instances-cp
```

 Exclua o cluster: 

```
aws ecs delete-cluster --cluster managed-instances-cluster
```

**nota**  
 As instâncias gerenciadas são automaticamente encerradas quando o provedor de capacidade é excluído. Não é necessário encerrar manualmente as instâncias do EC2.