# Tutoriais para o Amazon ECS
<a name="ecs-tutorials"></a>

Os seguintes tutoriais mostram como executar tarefas comuns ao usar o Amazon ECS.

Você pode usar os tutoriais a seguir para saber mais sobre como começar a usar o Amazon ECS.


| Visão geral do tutorial | Saiba mais | 
| --- | --- | 
|  Conceitos básicos do Amazon ECS no Fargate.  |  [Como criar uma tarefa do Linux no Amazon ECS para o Fargate](getting-started-fargate.md)  | 
|  Conceitos básicos de contêineres do Windows no Fargate.  |  [Como criar uma tarefa do Amazon ECS Windows para o Fargate](Windows_fargate-getting_started.md)  | 
|  Conceitos básicos de contêineres do Windows para o EC2.  |  [Como criar uma tarefa do Amazon ECS Windows para o EC2](getting-started-ecs-ec2-v2.md)  | 

Você pode usar qualquer um dos seguintes tutoriais para implantar tarefas no Amazon ECS usando a AWS CLI


| Visão geral do tutorial | Saiba mais | 
| --- | --- | 
|  Criar uma tarefa do Linux para o Fargate.  |  [Criar uma tarefa do Linux do Amazon ECS para o Fargate com a AWS CLI](ECS_AWSCLI_Fargate.md)  | 
|  Criar uma tarefa do Windows para o Fargate.  |  [Criar uma tarefa do Windows do Amazon ECS para o Fargate com a AWS CLI](ECS_AWSCLI_Fargate_windows.md)  | 
|  Criar uma tarefa do Linux para o EC2.  |  [Criar uma tarefa do Amazon ECS para o EC2 com a AWS CLI](ECS_AWSCLI_EC2.md)  | 

Você pode usar qualquer um dos tutoriais a seguir para saber mais sobre monitoramento e registro em log.


| Visão geral do tutorial | Saiba mais | 
| --- | --- | 
|  Configurar uma função do Lambda simples que atua como receptor de eventos de tarefa e os grava em um fluxo de logs do CloudWatch Logs.  |  [Configurar o Amazon ECS para atuar como receptor de eventos do CloudWatch Events](ecs_cwet.md)  | 
|  Configurar uma regra de evento do Amazon EventBridge que só capture eventos de tarefa em que a execução da tarefa foi interrompida porque um de seus contêineres essenciais foi encerrado.   |  [Enviar alertas do Amazon Simple Notification Service de eventos de tarefa interrompida do Amazon ECS](ecs_cwet2.md)  | 
|  Concatenar mensagens de log que pertenciam originalmente a um contexto, mas foram divididas em vários registros ou linhas de log.  |  [Concatenar mensagens de log de várias linhas ou de rastreamento de pilha do Amazon ECS](firelens-concatanate-multiline.md)  | 
|  Implantar contêineres do Fluent Bit nas respectivas instâncias do Windows sendo executadas no Amazon ECS para transmitir logs gerados pelas tarefas do Windows para o Amazon CloudWatch para registro em um log centralizado.  |  [Implantar o Fluent Bit em contêineres do Windows no Amazon ECS](tutorial-deploy-fluentbit-on-windows.md)  | 

Você pode usar qualquer um dos tutoriais a seguir para saber mais sobre como usar a autenticação do Active Directory com uma conta de serviço gerenciado em grupo no Amazon ECS.


| Visão geral do tutorial | Saiba mais | 
| --- | --- | 
|  Usar uma conta de serviço gerenciado em grupo com contêineres do Linux no EC2.  |  [Usar gMSA para contêineres do Linux do EC2 no Amazon ECS](linux-gmsa.md)  | 
|  Usar uma conta de serviço gerenciada em grupo com contêineres do Windows no EC2.  |  [Saiba como usar gMSAs para contêineres do Windows do Amazon EC2 para o Amazon ECS](windows-gmsa.md)  | 
|  Usar a conta de serviço gerenciado em grupo com contêineres do Linux no Fargate.  |  [Uso de gMSA em contêineres do Linux no Fargate](fargate-linux-gmsa.md)  | 
|  Criar uma tarefa que executa um contêiner do Windows que tem credenciais para acessar o Active Directory com uma conta de serviço gerenciado em grupo sem domínio.  |  [Usar contêineres do Windows no Amazon ECS com gMSA sem domínio usando a AWS CLI](tutorial-gmsa-windows.md)  | 

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

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

As etapas a seguir ajudarão você a configurar um cluster, registrar uma definição de tarefa, executar uma tarefa do Windows e realizar outros cenários comuns no Amazon ECS com a AWS CLI. Você deve usar 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_windows_prereq)
+ [

## Etapa 1: criar um cluster
](#ECS_AWSCLI_Fargate_windows_create_cluster)
+ [

## Etapa 2: registrar uma definição de tarefa do Windows
](#ECS_AWSCLI_Fargate_windows_register_task_definition)
+ [

## Etapa 3: listar definições de tarefa
](#ECS_AWSCLI_Fargate_windows__list_task_definitions)
+ [

## Etapa 4: criar um serviço
](#ECS_AWSCLI_Fargate_windows_create_service)
+ [

## Etapa 5: listar serviços
](#ECS_AWSCLI_Fargate_windows_list_services)
+ [

## Etapa 6: descrever o serviço em execução
](#ECS_AWSCLI_Fargate_windows_describe_service)
+ [

## Etapa 7: limpar
](#ECS_AWSCLI_Fargate_windows_clean_up)

## Pré-requisitos
<a name="ECS_AWSCLI_Fargate_windows_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 Docker Hub, 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*.
+ (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_windows_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", 
        "statistics": [], 
        "clusterName": "fargate-cluster", 
        "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 Windows
<a name="ECS_AWSCLI_Fargate_windows_register_task_definition"></a>

Para executar uma tarefa do Windows no seu cluster do Amazon 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 uma aplicação da Web. 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).

```
{
    "containerDefinitions": [
        {
            "command": ["New-Item -Path C:\\inetpub\\wwwroot\\index.html -Type file -Value '<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>'; C:\\ServiceMonitor.exe w3svc"],
            "entryPoint": [
                "powershell",
                "-Command"
            ],
            "essential": true,
            "cpu": 2048,
            "memory": 4096,
            "image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
            "name": "sample_windows_app",
            "portMappings": [
                {
                    "hostPort": 80,
                    "containerPort": 80,
                    "protocol": "tcp"
                }
            ]
        }
    ],
    "memory": "4096",
    "cpu": "2048",
    "networkMode": "awsvpc",
    "family": "windows-simple-iis-2019-core",
    "executionRoleArn": "arn:aws:iam::012345678910:role/ecsTaskExecutionRole",
    "runtimePlatform": {"operatingSystemFamily": "WINDOWS_SERVER_2019_CORE"},
    "requiresCompatibilities": ["FARGATE"]
}
```

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

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_windows__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-windows:1"
    ]
}
```

## Etapa 4: criar um serviço
<a name="ECS_AWSCLI_Fargate_windows_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.

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

Exemplo usando uma sub-rede pública.

```
aws ecs create-service --cluster fargate-cluster --service-name fargate-service --task-definition sample-fargate-windows: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_windows_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-service"
    ]
}
```

## Etapa 6: descrever o serviço em execução
<a name="ECS_AWSCLI_Fargate_windows_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 de serviços, 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": [
        {
            "status": "ACTIVE", 
            "taskDefinition": "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate-windows:1", 
            "pendingCount": 2, 
            "launchType": "FARGATE", 
            "loadBalancers": [], 
            "roleArn": "arn:aws:iam::aws_account_id:role/aws-service-role/ecs.amazonaws.com/AWSServiceRoleForECS", 
            "placementConstraints": [], 
            "createdAt": 1510811361.128, 
            "desiredCount": 2, 
            "networkConfiguration": {
                "awsvpcConfiguration": {
                    "subnets": [
                        "subnet-abcd1234"
                    ], 
                    "securityGroups": [
                        "sg-abcd1234"
                    ], 
                    "assignPublicIp": "DISABLED"
                }
            }, 
            "platformVersion": "LATEST", 
            "serviceName": "fargate-service", 
            "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
            }, 
            "deployments": [
                {
                    "status": "PRIMARY", 
                    "networkConfiguration": {
                        "awsvpcConfiguration": {
                            "subnets": [
                                "subnet-abcd1234"
                            ], 
                            "securityGroups": [
                                "sg-abcd1234"
                            ], 
                            "assignPublicIp": "DISABLED"
                        }
                    }, 
                    "pendingCount": 2, 
                    "launchType": "FARGATE", 
                    "createdAt": 1510811361.128, 
                    "desiredCount": 2, 
                    "taskDefinition": "arn:aws:ecs:region:aws_account_id:task-definition/sample-fargate-windows:1", 
                    "updatedAt": 1510811361.128, 
                    "platformVersion": "0.0.1", 
                    "id": "ecs-svc/9223370526043414679", 
                    "runningCount": 0
                }
            ], 
            "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, 
            "placementStrategy": []
        }
    ], 
    "failures": []
}
```

## Etapa 7: limpar
<a name="ECS_AWSCLI_Fargate_windows_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
```

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

# Configurar o Amazon ECS para atuar como receptor de eventos do CloudWatch Events
<a name="ecs_cwet"></a>

Saiba como configurar uma função do Lambda simples que atua como receptor de eventos de tarefa e os grava em um fluxo de logs do CloudWatch Logs.

## Pré-requisito: configurar um cluster de teste
<a name="cwet_step_1"></a>

Caso você não tenha um cluster em execução para capturar eventos, siga as etapas em [Criar um cluster do Amazon ECS para workloads do Fargate](create-cluster-console-v2.md) para criar um. Ao final deste tutorial, você executará uma tarefa nesse cluster para testar se configurou a função Lambda corretamente. 

## Etapa 1: criar a função do Lambda
<a name="cwet_step_2"></a>

Neste procedimento, você criará uma função simples do Lambda para funcionar como um destino para mensagens da sequência de eventos do Amazon ECS. 

1. Abra o console do AWS Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/).

1. Escolha **Create function**. 

1. Na tela **Author from scratch**, faça o seguinte:

   1. Em **Name (Nome)**, insira um valor. 

   1. Para **Runtime**, escolha sua versão do Python, por exemplo, **Python 3.9**.

   1. Em **Role (Função)**, escolha **Create a new role with basic Lambda permissions (Criar uma nova função com permissões básicas do Lambda)**.

1. Escolha a opção **Criar função**.

1. Na seção **Function code**, edite o código de exemplo de acordo com o exemplo a seguir.

   ```
   import json
   
   def lambda_handler(event, context):
       if event["source"] != "aws.ecs":
          raise ValueError("Function only supports input from events with a source type of: aws.ecs")
          
       print('Here is the event:')
       print(json.dumps(event))
   ```

   Essa é uma função simples do Python 3.9 que imprime o evento enviado pelo Amazon ECS. Se tudo estiver configurado corretamente, no final deste tutorial, você verá que os detalhes do evento aparecerão no fluxo de log do CloudWatch Logs associado a essa função Lambda.

1. Escolha **Salvar**.

## Etapa 2: registrar uma regra de evento
<a name="cwet_step_3"></a>

 Em seguida, você cria uma regra de evento do CloudWatch Events que captura eventos de tarefa vindos dos clusters do Amazon ECS. Essa regra captura todos os eventos vindos de todos os clusters dentro da conta em que ela está definida. As próprias mensagens de tarefa contêm informações sobre a origem do evento, inclusive o cluster no qual reside, que você pode usar para filtrar e classificar eventos programaticamente. 

**nota**  
Quando você usa o Console de gerenciamento da AWS para criar uma regra de evento, o console adiciona automaticamente as permissões do IAM necessárias para conceder ao CloudWatch Events permissão para chamar a função Lambda. Caso esteja criando uma regra de evento usando a AWS CLI, você precisa conceder essa permissão explicitamente. Para obter mais informações, consulte [Eventos no Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) e [Padrões de eventos do Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html) no *Guia do usuário do Amazon EventBridge*.

**Para encaminhar eventos para a função Lambda**

1. Abra o console do CloudWatch, em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. No painel de navegação, escolha **Events (Eventos)**, **Rules (Regras)**, **Create rule (Criar regra)**.

1. Em **Event Source**, escolha **ECS** como origem do evento. Por padrão, a regra se aplica a todos os eventos do Amazon ECS para todos os grupos do Amazon ECS. Como alternativa, você pode selecionar eventos específicos ou um grupo específico do Amazon ECS.

1. Em **Destinos**, escolha **Adicionar destino**, para **Tipo de destino**, escolha **Função do Lambda** e, em seguida, selecione sua função do Lambda.

1. Escolha **Configure details (Configurar detalhes)**.

1. Em **Rule definition**, digite um nome e uma descrição para a regra e escolha **Create rule**.

## Etapa 3: criar uma definição de tarefa
<a name="cwet_step_task-def"></a>

Crie uma definição de tarefa.

1. Abra o console em [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).

1. No painel de navegação, selecione **Definições de tarefas**.

1. Escolha **Create new Task Definition** (Criar nova definição de tarefa), **Create new revision with JSON** (Criar nova revisão com JSON).

1. Copie e cole o exemplo de definição de tarefa a seguir na caixa e escolha **Save (Salvar)**.

   ```
   {
      "containerDefinitions": [ 
         { 
            "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\""
            ],
            "entryPoint": [
               "sh",
               "-c"
            ],
            "essential": true,
            "image": "public.ecr.aws/docker/library/httpd:2.4",
            "logConfiguration": { 
               "logDriver": "awslogs",
               "options": { 
                  "awslogs-group" : "/ecs/fargate-task-definition",
                  "awslogs-region": "us-east-1",
                  "awslogs-stream-prefix": "ecs"
               }
            },
            "name": "sample-fargate-app",
            "portMappings": [ 
               { 
                  "containerPort": 80,
                  "hostPort": 80,
                  "protocol": "tcp"
               }
            ]
         }
      ],
      "cpu": "256",
      "executionRoleArn": "arn:aws:iam::012345678910:role/ecsTaskExecutionRole",
      "family": "fargate-task-definition",
      "memory": "512",
      "networkMode": "awsvpc",
      "runtimePlatform": {
           "operatingSystemFamily": "LINUX"
       },
      "requiresCompatibilities": [ 
          "FARGATE" 
       ]
   }
   ```

1. Escolha **Criar**.

## Etapa 4: testar a regra
<a name="cwet_step_4"></a>

 Por fim, você cria uma regra de evento do CloudWatch Events que captura eventos de tarefa vindos dos clusters do Amazon ECS. Essa regra captura todos os eventos vindos de todos os clusters dentro da conta em que ela está definida. As próprias mensagens de tarefa contêm informações sobre a origem do evento, inclusive o cluster no qual reside, que você pode usar para filtrar e classificar eventos programaticamente. 

**Como testar sua regra**

1. Abra o console em [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).

1. Escolha **Task definitions** (Definições de tarefa).

1. Escolha **console-sample-app-static** e, em seguida, escolha **Deploy** (Implantar), **Run new task** (Executar nova tarefa).

1. Em **Cluster**, escolha default (padrão) e, em seguida, escolha **Deploy** (Implantar).

1. Abra o console CloudWatch em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. No painel de navegação, escolha **Logs** e selecione o grupo de logs para sua função do Lambda (por exemplo, **/aws/lambda/***my-function*).

1. Selecione um fluxo de log para visualizar os dados do evento. 

# Enviar alertas do Amazon Simple Notification Service de eventos de tarefa interrompida do Amazon ECS
<a name="ecs_cwet2"></a>

Configurar uma regra de evento do Amazon EventBridge que só capture eventos de tarefa em que a execução da tarefa foi interrompida porque um de seus contêineres essenciais foi encerrado. O evento só envia eventos de tarefa com uma propriedade `stoppedReason` específica para o tópico do Amazon SNS designado.

## Pré-requisito: configurar um cluster de teste
<a name="cwet2_step_1"></a>

 Caso você não tenha um cluster em execução para capturar eventos, siga as etapas em [Conceitos básicos do console usando contêineres de Linux no AWS Fargate](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/getting-started-fargate.html#get-started-fargate-cluster) para criar um. Ao final deste tutorial, você executará uma tarefa nesse cluster para testar se configurou o tópico do Amazon SNS e a regra do EventBridge corretamente. 

## Pré-requisito: configurar permissões para o Amazon SNS
<a name="cwet2_step_1a"></a>

Para permitir que o EventBridge publique em um tópico do Amazon SNS, use os comandos aws sns get-topic-attributes e aws sns set-topic-attributes. 

Para obter informações sobre como adicionar a permissão, consulte [Permissões do Amazon SNS](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-use-resource-based.html#eb-sns-permissions) no *Guia do desenvolvedor do Amazon Simple Notification Service*.

Adicione as seguintes permissões:

```
{
  "Sid": "PublishEventsToMyTopic",
  "Effect": "Allow",
  "Principal": {
     "Service": "events.amazonaws.com"
  },
  "Action": "sns: Publish",
  "Resource": "arn:aws:sns:region:account-id:TaskStoppedAlert",
}
```

## Etapa 1: criar e se inscrever em um tópico do Amazon SNS
<a name="cwet2_step_2"></a>

 Neste tutorial, você configura um tópico do Amazon SNS para funcionar como um destino de evento para a nova regra de evento. 

Para obter informações sobre como criar e assinar um tópico do Amazon SNS, consulte [Conceitos básicos do Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html#step-create-queue) no *Guia do desenvolvedor do Amazon Simple Notification Service* e use a tabela a seguir para determinar quais opções selecionar.


| Opção | Valor | 
| --- | --- | 
|  Tipo  | Standard | 
| Nome |  TaskStoppedAlert  | 
| Protocolo | E-mail | 
| Endpoint |  Um endereço de email ao qual você atualmente tem acesso  | 

## Etapa 2: registrar uma regra de evento
<a name="cwet2_step_3"></a>

 Em seguida, você registra uma regra de evento que captura apenas eventos de tarefa parada para tarefas com contêineres parados. 

Para obter informações sobre como criar um tópico do Amazon SNS e assiná-lo, consulte [Criar uma regra no Amazon EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-get-started.html) no *Guia do usuário do Amazon EventBridge* e use a tabela a seguir para determinar quais opções selecionar.


| Opção | Valor | 
| --- | --- | 
|  Tipo de regra  |  Regra com um padrão de evento  | 
| Origem do evento | Eventos da AWS ou eventos de parceiros do EventBridge | 
| Padrão de evento |  Padrão personalizado (editor JSON)  | 
| Padrão de evento |  <pre>{<br />   "source":[<br />      "aws.ecs"<br />   ],<br />   "detail-type":[<br />      "ECS Task State Change"<br />   ],<br />   "detail":{<br />      "lastStatus":[<br />         "STOPPED"<br />      ],<br />      "stoppedReason":[<br />         "Essential container in task exited"<br />      ]<br />   }<br />}</pre> | 
| Target type |  Serviço da AWS  | 
| Target | Tópico do SNS | 
| Tópico |  TaskStoppedAlert (O tópico que você criou na Etapa 1)  | 

## Etapa 3: testar a regra
<a name="cwet2_step_4"></a>

Verifique se a regra está funcionando ao executar uma tarefa que sai pouco depois que é iniciada. Caso a regra de evento esteja configurada corretamente, você recebe uma mensagem de e-mail em alguns minutos com o texto do evento. Se você tiver uma definição de tarefa existente que possa atender aos requisitos da regra, execute uma tarefa ao usá-la. Se você não fizer isso, as etapas a seguir vão orientá-lo no registro de uma definição de tarefa Fargate e na sua execução.

1. Abra o console em [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).

1. No painel de navegação, escolha **Task definitions** (Definições de tarefa).

1. Escolha **Create new task definition** (Criar nova definição de tarefa), **Create new task definition with JSON** (Criar nova definição de tarefa com JSON).

1. Na caixa do editor JSON, edite o arquivo JSON e copie o seguinte no editor.

   ```
   {
      "containerDefinitions":[
         {
            "command":[
               "sh",
               "-c",
               "sleep 5"
            ],
            "essential":true,
            "image":"public.ecr.aws/amazonlinux/amazonlinux:latest",
            "name":"test-sleep"
         }
      ],
      "cpu":"256",
      "executionRoleArn":"arn:aws:iam::012345678910:role/ecsTaskExecutionRole",
      "family":"fargate-task-definition",
      "memory":"512",
      "networkMode":"awsvpc",
      "requiresCompatibilities":[
         "FARGATE"
      ]
   }
   ```

1. Escolha **Criar**.

**Para executar uma tarefa no console**

1. Abra o console em [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).

1. Na página **Clusters**, escolha o cluster que você criou nos pré-requisitos.

1. Na guia **Tasks** (Tarefas), escolha **Run new task** (Executar nova tarefa).

1. Em **Application type** (Tipo de aplicação), escolha **Task** (Tarefa).

1. Em **Definição de tarefa**, selecione **fargate-task-definition**.

1. Em **Desired tasks** (Tarefas desejadas), insira o número de tarefas que serão iniciadas.

1. Selecione **Create** (Criar).

# Concatenar mensagens de log de várias linhas ou de rastreamento de pilha do Amazon ECS
<a name="firelens-concatanate-multiline"></a>

Começando com AWS para o Fluent Bit versão 2.22.0, um filtro de várias linhas está incluído. O filtro de várias linhas ajuda a concatenar mensagens de log que pertencem originalmente a um contexto, mas foram divididas em vários registros ou linhas de log. Para obter mais informações sobre o filtro multilinha, consulte a [ documentação do Fluent Bit.](https://docs.fluentbit.io/manual/pipeline/filters/multiline-stacktrace) 

Exemplos comuns de mensagens de log dividido incluem:
+ Rastreamentos de pilhas. 
+ Aplicações que imprimem logs em várias linhas. 
+ Mensagens de log que foram divididas porque eram maiores que o tamanho máximo do buffer do runtime especificado. É possível concatenar mensagens de log divididas pelo runtime do contêiner seguindo o exemplo no GitHub: [Exemplo do FireLens: Concatenar logs de contêiners parciais/divididos](https://github.com/aws-samples/amazon-ecs-firelens-examples/tree/mainline/examples/fluent-bit/filter-multiline-partial-message-mode).

## Permissões obrigatórias do IAM
<a name="iam-permissions"></a>

Você deve primeiro ter as permissões do IAM necessárias para que o agente de contêiner extraia as imagens de contêiner do Amazon ECR e para que o contêiner encaminhe logs ao CloudWatch Logs.

Para essas permissões, você precisa ter as seguintes funções: 
+ Uma função do IAM de tarefa. 
+ Um perfil do IAM de execução de tarefa. 

Você precisa das seguintes permissões:
+ `logs:CreateLogStream`
+ `logs:CreateLogGroup`
+ `logs:PutLogEvents`

## Determinar quando usar configuração de logs multilinha
<a name="determine-filter"></a>

Veja a seguir um exemplo de trechos de log exibidos no console do CloudWatch Logs com a configuração de log padrão. É possível ver a linha que começa com `log` para determinar se precisa do filtro multilinha. Quando o contexto é o mesmo, você pode usar a configuração de log de várias linhas. Neste exemplo, o contexto é "com.myproject.model.MyProject".

```
2022-09-20T15:47:56:595-05-00                           {"container_id": "82ba37cada1d44d389b03e78caf74faa-EXAMPLE", "container_name": "example-app", "source=": "stdout", "log": ": "     at com.myproject.modele.(MyProject.badMethod.java:22)",
    {
      "container_id":  "82ba37cada1d44d389b03e78caf74faa-EXAMPLE",
      "container_name: ": "example-app",
      "source": "stdout",
      "log": ": "     at com.myproject.model.MyProject.badMethod(MyProject.java:22)",
      "ecs_cluster": "default",
      "ecs_task_arn": "arn:aws:region:123456789012:task/default/b23c940d29ed4714971cba72cEXAMPLE",
      "ecs_task_definition": "firelense-example-multiline:3"
     }
```

```
2022-09-20T15:47:56:595-05-00                           {"container_id": "82ba37cada1d44d389b03e78caf74faa-EXAMPLE", "container_name": "example-app", "stdout", "log": ": "     at com.myproject.modele.(MyProject.oneMoreMethod.java:18)",
    {
      "container_id":  "82ba37cada1d44d389b03e78caf74faa-EXAMPLE",
      "container_name: ": "example-app",
      "source": "stdout",
      "log": ": "     at com.myproject.model.MyProject.oneMoreMethod(MyProject.java:18)",
      "ecs_cluster": "default",
      "ecs_task_arn": "arn:aws:region:123456789012:task/default/b23c940d29ed4714971cba72cEXAMPLE,
      "ecs_task_definition": "firelense-example-multiline:3"
     }
```

Depois de usar a configuração de log multilinha, a saída será semelhante ao exemplo abaixo. 

```
2022-09-20T15:47:56:595-05-00                           {"container_id": "82ba37cada1d44d389b03e78caf74faa-EXAMPLE", "container_name": "example-app", "stdout",...
    {
      "container_id":  "82ba37cada1d44d389b03e78caf74faa-EXAMPLE",
      "container_name: ": "example-app",
      "source": "stdout",
      "log:    "September 20, 2022 06:41:48 Exception in thread \"main\" java.lang.RuntimeException: Something has gone wrong, aborting!\n    
    at com.myproject.module.MyProject.badMethod(MyProject.java:22)\n    at   
    at com.myproject.model.MyProject.oneMoreMethod(MyProject.java:18) com.myproject.module.MyProject.main(MyProject.java:6)",
      "ecs_cluster": "default",
      "ecs_task_arn": "arn:aws:region:123456789012:task/default/b23c940d29ed4714971cba72cEXAMPLE",
      "ecs_task_definition": "firelense-example-multiline:2"
     }
```

## Opções de análise e concatenação
<a name="parse-multiline-log"></a>

Para analisar logs e concatenar linhas divididas devido a novas linhas, use qualquer uma destas duas opções.
+ Use seu próprio arquivo do analisador que contém as regras para analisar e concatenar linhas que pertencem à mesma mensagem.
+ Usar um analisador integrado do Fluent Bit. Para obter uma lista de idiomas compatíveis com os analisadores integrados Fluent Bit, consulte a [documentação do Fluent Bit.](https://docs.fluentbit.io/manual/pipeline/filters/multiline-stacktrace)

O tutorial a seguir orientará você sobre as etapas de cada caso de uso. As etapas mostram como concatenar várias linhas e enviar os logs para o Amazon CloudWatch. É possível especificar um destino diferente para os logs.

### Exemplo: use um analisador criado por você
<a name="customer-parser"></a>

Neste exemplo, você concluirá as seguintes etapas: 

1. Criar e carregar a imagem para um contêiner Fluent Bit. 

1. Criar e carregar a imagem para uma aplicação de várias linhas de demonstração que executa, falha e gera um rastreamento de pilha de várias linhas.

1. Criar a definição de tarefa e executar a tarefa. 

1. Exibir os logs para verificar se as mensagens que abrangem várias linhas aparecem concatenadas. 

**Criar e carregar a imagem para um contêiner Fluent Bit**

Essa imagem incluirá o arquivo do analisador no qual você especifica a expressão regular e um arquivo de configuração que faz referência ao arquivo do analisador. 

1. Criar uma pasta com o nome `FluentBitDockerImage`. 

1. Na pasta, crie um arquivo do analisador que contém as regras para analisar o log e concatenar linhas que pertencem à mesma mensagem.

   1. Cole o seguinte conteúdo no arquivo do analisador:

      ```
      [MULTILINE_PARSER]
          name          multiline-regex-test
          type          regex
          flush_timeout 1000
          #
          # Regex rules for multiline parsing
          # ---------------------------------
          #
          # configuration hints:
          #
          #  - first state always has the name: start_state
          #  - every field in the rule must be inside double quotes
          #
          # rules |   state name  | regex pattern                  | next state
          # ------|---------------|--------------------------------------------
          rule      "start_state"   "/(Dec \d+ \d+\:\d+\:\d+)(.*)/"  "cont"
          rule      "cont"          "/^\s+at.*/"                     "cont"
      ```

      À medida que você personaliza seu padrão de regex, recomendamos que você use um editor de expressões regulares para testar a expressão.

   1. Salve o arquivo como `parsers_multiline.conf`. 

1. Dentro da pasta `FluentBitDockerImage`, crie um arquivo de configuração personalizado que faça referência ao arquivo do analisador que você criou na etapa anterior.

   Para obter mais informações sobre o arquivo de configuração personalizado, consulte [Especificar um arquivo de configuração personalizado](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/firelens-taskdef.html#firelens-taskdef-customconfig) no *Guia do desenvolvedor do Amazon Elastic Container Service* 

   1. Cole o seguinte conteúdo no arquivo:

      ```
      [SERVICE]
          flush                 1
          log_level             info
          parsers_file          /parsers_multiline.conf
          
      [FILTER]
          name                  multiline
          match                 *
          multiline.key_content log
          multiline.parser      multiline-regex-test
      ```
**nota**  
Você deve usar o caminho absoluto do analisador. 

   1. Salve o arquivo como `extra.conf`. 

1. Dentro da pasta `FluentBitDockerImage`, crie o Dockerfile com a imagem Fluent Bit e os arquivos do analisador e de configuração que você criou.

   1. Cole o seguinte conteúdo no arquivo:

      ```
      FROM public.ecr.aws/aws-observability/aws-for-fluent-bit:latest
      
      ADD parsers_multiline.conf /parsers_multiline.conf
      ADD extra.conf /extra.conf
      ```

   1. Salve o arquivo como `Dockerfile`.

1. Usando o Dockerfile, crie uma imagem Fluent Bit personalizada com os arquivos de configuração personalizados e do analisador incluídos.
**nota**  
É possível colocar o arquivo do analisador e o arquivo de configuração em qualquer lugar da imagem do Docker, exceto em `/fluent-bit/etc/fluent-bit.conf`, pois esse caminho de arquivo é usado pelo FireLens.

   1. Crie a imagem: `docker build -t fluent-bit-multiline-image.`

      Onde: `fluent-bit-multiline-image` é o nome da imagem neste exemplo.

   1. Verifique se a imagem foi criada corretamente: `docker images —filter reference=fluent-bit-multiline-image` 

      Se tiver êxito, a saída mostrará a imagem e a etiqueta `latest`.

1. Carregue a imagem personalizada do Fluent Bit no Amazon Elastic Container Registry.

   1. Crie um repositório do Amazon ECR para armazenar a imagem: `aws ecr create-repository --repository-name fluent-bit-multiline-repo --region us-east-1`

      Onde: `fluent-bit-multiline-repo` é o nome do repositório e `us-east-1` é a região neste exemplo. 

      A saída fornece os detalhes do novo repositório. 

   1. Marque sua imagem com o valor `repositoryUri` da saída anterior: `docker tag fluent-bit-multiline-image repositoryUri` 

      Exemplo: `docker tag fluent-bit-multiline-image xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/fluent-bit-multiline-repo` 

   1. Execute a imagem do Docker para verificar se ela é executada corretamente: `docker images —filter reference=repositoryUri`

      Na saída, o nome do repositório muda de fluent-bit-multiline-repo para o `repositoryUri`.

   1. Autentique-se no Amazon ECR executando o comando `aws ecr get-login-password` e especificando o ID de registro para o qual deseja fazer a autenticação: `aws ecr get-login-password | docker login --username AWS --password-stdin registry ID.dkr.ecr.region.amazonaws.com` 

      Exemplo: `ecr get-login-password | docker login --username AWS --password-stdin xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com`

      Uma mensagem de login com êxito é exibida.

   1. Envie a imagem para o Amazon ECR: `docker push registry ID.dkr.ecr.region.amazonaws.com/repository name` 

      Exemplo: `docker push xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/fluent-bit-multiline-repo`

**Crie e carregue a imagem para uma aplicação de várias linhas de demonstração**

Essa imagem incluirá um arquivo de script Python que executa a aplicação e um arquivo de log de amostra. 

Quando você executa a tarefa, a aplicação simula execuções, depois falha e cria um rastreamento de pilha. 

1. Crie uma pasta denominada `multiline-app`: `mkdir multiline-app` 

1. Crie um arquivo de script do Python.

   1. Na pasta `multiline-app`, crie um arquivo de texto e denomine-o `main.py`.

   1. Cole o seguinte conteúdo no arquivo:

      ```
      import os
      import time
      file1 = open('/test.log', 'r')
      Lines = file1.readlines()
       
      count = 0
      
      for i in range(10):
          print("app running normally...")
          time.sleep(1)
      
      # Strips the newline character
      for line in Lines:
          count += 1
          print(line.rstrip())
      print(count)
      print("app terminated.")
      ```

   1. Salve o arquivo `main.py`.

1. Crie um arquivo de log de exemplo. 

   1. Na pasta `multiline-app`, crie um arquivo de texto e denomine-o `test.log`.

   1. Cole o seguinte conteúdo no arquivo:

      ```
      single line...
      Dec 14 06:41:08 Exception in thread "main" java.lang.RuntimeException: Something has gone wrong, aborting!
          at com.myproject.module.MyProject.badMethod(MyProject.java:22)
          at com.myproject.module.MyProject.oneMoreMethod(MyProject.java:18)
          at com.myproject.module.MyProject.anotherMethod(MyProject.java:14)
          at com.myproject.module.MyProject.someMethod(MyProject.java:10)
          at com.myproject.module.MyProject.main(MyProject.java:6)
      another line...
      ```

   1. Salve o arquivo `test.log`.

1. Dentro da pasta `multiline-app`, crie o Dockerfile.

   1. Cole o seguinte conteúdo no arquivo:

      ```
      FROM public.ecr.aws/amazonlinux/amazonlinux:latest
      ADD test.log /test.log
      
      RUN yum upgrade -y && yum install -y python3
      
      WORKDIR /usr/local/bin
      
      COPY main.py .
      
      CMD ["python3", "main.py"]
      ```

   1. Salve o arquivo `Dockerfile`.

1. Usando o Dockerfile, crie uma imagem.

   1. Crie a imagem: `docker build -t multiline-app-image `

      Onde: `multiline-app-image` é o nome da imagem neste exemplo.

   1. Verifique se a imagem foi criada corretamente: `docker images —filter reference=multiline-app-image` 

      Se tiver êxito, a saída mostrará a imagem e a etiqueta `latest`.

1. Carregue a imagem no Amazon Elastic Container Registry.

   1. Crie um repositório do Amazon ECR para armazenar a imagem: `aws ecr create-repository --repository-name multiline-app-repo --region us-east-1`

      Onde: `multiline-app-repo` é o nome do repositório e `us-east-1` é a região neste exemplo. 

      A saída fornece os detalhes do novo repositório. Anote o valor do `repositoryUri`, pois ele será necessário na próxima etapa. 

   1. Marque sua imagem com o valor `repositoryUri` da saída anterior: `docker tag multiline-app-image repositoryUri` 

      Exemplo: `docker tag multiline-app-image xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/multiline-app-repo` 

   1. Execute a imagem do Docker para verificar se ela é executada corretamente: `docker images —filter reference=repositoryUri`

      Na saída, o nome do repositório muda de `multiline-app-repo` para o valor `repositoryUri`.

   1. Envie a imagem para o Amazon ECR: `docker push aws_account_id.dkr.ecr.region.amazonaws.com/repository name` 

      Exemplo: `docker push xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/multiline-app-repo`

**Crie a definição da tarefa e execute a tarefa**

1. Crie um arquivo de definição de tarefa com o nome de arquivo `multiline-task-definition.json`. 

1. Cole o seguinte conteúdo no arquivo `multiline-task-definition.json`: 

   ```
   {
       "family": "firelens-example-multiline",
       "taskRoleArn": "task role ARN,
       "executionRoleArn": "execution role ARN",
       "containerDefinitions": [
           {
               "essential": true,
               "image": "aws_account_id.dkr.ecr.us-east-1.amazonaws.com/fluent-bit-multiline-image:latest",
               "name": "log_router",
               "firelensConfiguration": {
                   "type": "fluentbit",
                   "options": {
                       "config-file-type": "file",
                       "config-file-value": "/extra.conf"
                   }
               },
               "memoryReservation": 50
           },
           {
               "essential": true,
               "image": "aws_account_id.dkr.ecr.us-east-1.amazonaws.com/multiline-app-image:latest",
               "name": "app",
               "logConfiguration": {
                   "logDriver": "awsfirelens",
                   "options": {
                       "Name": "cloudwatch_logs",
                       "region": "us-east-1",
                       "log_group_name": "multiline-test/application",
                       "auto_create_group": "true",
                       "log_stream_prefix": "multiline-"
                   }
               },
               "memoryReservation": 100
           }
       ],
       "requiresCompatibilities": ["FARGATE"],
       "networkMode": "awsvpc",
       "cpu": "256",
       "memory": "512"
   }
   ```

   Substitua o seguinte na definição de tarefa `multiline-task-definition.json`:

   1. `task role ARN`

      Para encontrar o ARN da função de tarefa, acesse o console do IAM. Escolha **Roles** (Funções) e encontre a função de tarefa `ecs-task-role-for-firelens` que você criou. Escolha a função e copie o **ARN** que consta na seção **Summary** (Resumo).

   1. `execution role ARN`

      Para encontrar o ARN da função de execução, acesse o console do IAM. Selecione **Roles** (Funções) e localize a função `ecsTaskExecutionRole`. Escolha a função e copie o **ARN** que consta na seção **Summary** (Resumo).

   1. `aws_account_id`

      Para encontrar seu `aws_account_id`, faça login no Console de gerenciamento da AWS. Escolha seu nome de usuário no canto superior direito e copie o ID da conta.

   1. `us-east-1`

      Substitua a região, se necessário.

1. Registre o arquivo de definição de tarefa: `aws ecs register-task-definition --cli-input-json file://multiline-task-definition.json --region region` 

1. Abra o console em [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).

1. No painel de navegação, selecione **Task Definitions** (Definições de tarefa) e, em seguida, escolha a família `firelens-example-multiline`, pois registramos a definição de tarefa para essa família na primeira linha da definição de tarefa acima.

1. Escolha a versão mais recente. 

1. Escolha **Implantar**, **Executar tarefa**. 

1. Na página **Executar tarefa**, para **Cluster**, escolha o cluster e em **Rede**, para **Sub-redes**, escolha as sub-redes disponíveis para sua tarefa. 

1. Escolha **Criar**. 

**Verifique se as mensagens de log de várias linhas no Amazon CloudWatch parecem concatenadas**

1. Abra o console do CloudWatch, em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. No painel de navegação, expanda **Logs** e escolha **Log groups** (Grupos de log). 

1. Escolha o grupo de logs `multiline-test/applicatio`. 

1. Escolha o log. Vejas as mensagens. As linhas que correspondem às regras no arquivo do analisador são concatenadas e aparecem como uma única mensagem. 

   O trecho de log a seguir mostra linhas concatenadas em um único evento de rastreamento de pilha Java: 

   ```
   {
       "container_id": "xxxxxx",
       "container_name": "app",
       "source": "stdout",
       "log": "Dec 14 06:41:08 Exception in thread \"main\" java.lang.RuntimeException: Something has gone wrong, aborting!\n    at com.myproject.module.MyProject.badMethod(MyProject.java:22)\n    at com.myproject.module.MyProject.oneMoreMethod(MyProject.java:18)\n    at com.myproject.module.MyProject.anotherMethod(MyProject.java:14)\n    at com.myproject.module.MyProject.someMethod(MyProject.java:10)\n    at com.myproject.module.MyProject.main(MyProject.java:6)",
       "ecs_cluster": "default",
       "ecs_task_arn": "arn:aws:ecs:us-east-1:xxxxxxxxxxxx:task/default/xxxxxx",
       "ecs_task_definition": "firelens-example-multiline:2"
   }
   ```

   O trecho de log a seguir mostra como a mesma mensagem é exibida com apenas uma única linha se você executar um contêiner do Amazon ECS que não esteja configurado para concatenar mensagens de log multinha. 

   ```
   {
       "log": "Dec 14 06:41:08 Exception in thread \"main\" java.lang.RuntimeException: Something has gone wrong, aborting!",
       "container_id": "xxxxxx-xxxxxx",
       "container_name": "app",
       "source": "stdout",
       "ecs_cluster": "default",
       "ecs_task_arn": "arn:aws:ecs:us-east-1:xxxxxxxxxxxx:task/default/xxxxxx",
       "ecs_task_definition": "firelens-example-multiline:3"
   }
   ```

### Exemplo: use um analisador integrado Fluent Bit
<a name="fluent-bit-parser"></a>

Neste exemplo, você concluirá as seguintes etapas: 

1. Criar e carregar a imagem para um contêiner Fluent Bit. 

1. Criar e carregar a imagem para uma aplicação de várias linhas de demonstração que executa, falha e gera um rastreamento de pilha de várias linhas.

1. Criar a definição de tarefa e executar a tarefa. 

1. Exibir os logs para verificar se as mensagens que abrangem várias linhas aparecem concatenadas. 

**Criar e carregar a imagem para um contêiner Fluent Bit**

Essa imagem incluirá um arquivo de configuração que faz referência ao analisador Fluent Bit. 

1. Criar uma pasta com o nome `FluentBitDockerImage`. 

1. Dentro da pasta `FluentBitDockerImage`, crie um arquivo de configuração personalizado que faça referência ao arquivo do analisador integrado Fluent Bit.

   Para obter mais informações sobre o arquivo de configuração personalizado, consulte [Especificar um arquivo de configuração personalizado](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/firelens-taskdef.html#firelens-taskdef-customconfig) no *Guia do desenvolvedor do Amazon Elastic Container Service* 

   1. Cole o seguinte conteúdo no arquivo:

      ```
      [FILTER]
          name                  multiline
          match                 *
          multiline.key_content log
          multiline.parser      go
      ```

   1. Salve o arquivo como `extra.conf`. 

1. Dentro da pasta `FluentBitDockerImage`, crie o Dockerfile com a imagem Fluent Bit e os arquivos do analisador e de configuração que você criou.

   1. Cole o seguinte conteúdo no arquivo:

      ```
      FROM public.ecr.aws/aws-observability/aws-for-fluent-bit:latest
      ADD extra.conf /extra.conf
      ```

   1. Salve o arquivo como `Dockerfile`.

1. Usando o Dockerfile, crie uma imagem Fluent Bit personalizada com o arquivo de configuração personalizado incluído.
**nota**  
É possível colocar o arquivo de configuração em qualquer lugar da imagem do Docker, exceto em `/fluent-bit/etc/fluent-bit.conf`, pois esse caminho de arquivo é usado pelo FireLens.

   1. Crie a imagem: `docker build -t fluent-bit-multiline-image.`

      Onde: `fluent-bit-multiline-image` é o nome da imagem neste exemplo.

   1. Verifique se a imagem foi criada corretamente: `docker images —filter reference=fluent-bit-multiline-image` 

      Se tiver êxito, a saída mostrará a imagem e a etiqueta `latest`.

1. Carregue a imagem personalizada do Fluent Bit no Amazon Elastic Container Registry.

   1. Crie um repositório do Amazon ECR para armazenar a imagem: `aws ecr create-repository --repository-name fluent-bit-multiline-repo --region us-east-1`

      Onde: `fluent-bit-multiline-repo` é o nome do repositório e `us-east-1` é a região neste exemplo. 

      A saída fornece os detalhes do novo repositório. 

   1. Marque sua imagem com o valor `repositoryUri` da saída anterior: `docker tag fluent-bit-multiline-image repositoryUri` 

      Exemplo: `docker tag fluent-bit-multiline-image xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/fluent-bit-multiline-repo` 

   1. Execute a imagem do Docker para verificar se ela é executada corretamente: `docker images —filter reference=repositoryUri`

      Na saída, o nome do repositório muda de fluent-bit-multiline-repo para o `repositoryUri`.

   1. Autentique-se no Amazon ECR executando o comando `aws ecr get-login-password` e especificando o ID de registro para o qual deseja fazer a autenticação: `aws ecr get-login-password | docker login --username AWS --password-stdin registry ID.dkr.ecr.region.amazonaws.com` 

      Exemplo: `ecr get-login-password | docker login --username AWS --password-stdin xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com`

      Uma mensagem de login com êxito é exibida.

   1. Envie a imagem para o Amazon ECR: `docker push registry ID.dkr.ecr.region.amazonaws.com/repository name` 

      Exemplo: `docker push xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/fluent-bit-multiline-repo`

**Crie e carregue a imagem para uma aplicação de várias linhas de demonstração**

Essa imagem incluirá um arquivo de script Python que executa a aplicação e um arquivo de log de amostra. 

1. Crie uma pasta denominada `multiline-app`: `mkdir multiline-app` 

1. Crie um arquivo de script do Python.

   1. Na pasta `multiline-app`, crie um arquivo de texto e denomine-o `main.py`.

   1. Cole o seguinte conteúdo no arquivo:

      ```
      import os
      import time
      file1 = open('/test.log', 'r')
      Lines = file1.readlines()
       
      count = 0
      
      for i in range(10):
          print("app running normally...")
          time.sleep(1)
      
      # Strips the newline character
      for line in Lines:
          count += 1
          print(line.rstrip())
      print(count)
      print("app terminated.")
      ```

   1. Salve o arquivo `main.py`.

1. Crie um arquivo de log de exemplo. 

   1. Na pasta `multiline-app`, crie um arquivo de texto e denomine-o `test.log`.

   1. Cole o seguinte conteúdo no arquivo:

      ```
      panic: my panic
      
      goroutine 4 [running]:
      panic(0x45cb40, 0x47ad70)
        /usr/local/go/src/runtime/panic.go:542 +0x46c fp=0xc42003f7b8 sp=0xc42003f710 pc=0x422f7c
      main.main.func1(0xc420024120)
        foo.go:6 +0x39 fp=0xc42003f7d8 sp=0xc42003f7b8 pc=0x451339
      runtime.goexit()
        /usr/local/go/src/runtime/asm_amd64.s:2337 +0x1 fp=0xc42003f7e0 sp=0xc42003f7d8 pc=0x44b4d1
      created by main.main
        foo.go:5 +0x58
      
      goroutine 1 [chan receive]:
      runtime.gopark(0x4739b8, 0xc420024178, 0x46fcd7, 0xc, 0xc420028e17, 0x3)
        /usr/local/go/src/runtime/proc.go:280 +0x12c fp=0xc420053e30 sp=0xc420053e00 pc=0x42503c
      runtime.goparkunlock(0xc420024178, 0x46fcd7, 0xc, 0x1000f010040c217, 0x3)
        /usr/local/go/src/runtime/proc.go:286 +0x5e fp=0xc420053e70 sp=0xc420053e30 pc=0x42512e
      runtime.chanrecv(0xc420024120, 0x0, 0xc420053f01, 0x4512d8)
        /usr/local/go/src/runtime/chan.go:506 +0x304 fp=0xc420053f20 sp=0xc420053e70 pc=0x4046b4
      runtime.chanrecv1(0xc420024120, 0x0)
        /usr/local/go/src/runtime/chan.go:388 +0x2b fp=0xc420053f50 sp=0xc420053f20 pc=0x40439b
      main.main()
        foo.go:9 +0x6f fp=0xc420053f80 sp=0xc420053f50 pc=0x4512ef
      runtime.main()
        /usr/local/go/src/runtime/proc.go:185 +0x20d fp=0xc420053fe0 sp=0xc420053f80 pc=0x424bad
      runtime.goexit()
        /usr/local/go/src/runtime/asm_amd64.s:2337 +0x1 fp=0xc420053fe8 sp=0xc420053fe0 pc=0x44b4d1
      
      goroutine 2 [force gc (idle)]:
      runtime.gopark(0x4739b8, 0x4ad720, 0x47001e, 0xf, 0x14, 0x1)
        /usr/local/go/src/runtime/proc.go:280 +0x12c fp=0xc42003e768 sp=0xc42003e738 pc=0x42503c
      runtime.goparkunlock(0x4ad720, 0x47001e, 0xf, 0xc420000114, 0x1)
        /usr/local/go/src/runtime/proc.go:286 +0x5e fp=0xc42003e7a8 sp=0xc42003e768 pc=0x42512e
      runtime.forcegchelper()
        /usr/local/go/src/runtime/proc.go:238 +0xcc fp=0xc42003e7e0 sp=0xc42003e7a8 pc=0x424e5c
      runtime.goexit()
        /usr/local/go/src/runtime/asm_amd64.s:2337 +0x1 fp=0xc42003e7e8 sp=0xc42003e7e0 pc=0x44b4d1
      created by runtime.init.4
        /usr/local/go/src/runtime/proc.go:227 +0x35
      
      goroutine 3 [GC sweep wait]:
      runtime.gopark(0x4739b8, 0x4ad7e0, 0x46fdd2, 0xd, 0x419914, 0x1)
        /usr/local/go/src/runtime/proc.go:280 +0x12c fp=0xc42003ef60 sp=0xc42003ef30 pc=0x42503c
      runtime.goparkunlock(0x4ad7e0, 0x46fdd2, 0xd, 0x14, 0x1)
        /usr/local/go/src/runtime/proc.go:286 +0x5e fp=0xc42003efa0 sp=0xc42003ef60 pc=0x42512e
      runtime.bgsweep(0xc42001e150)
        /usr/local/go/src/runtime/mgcsweep.go:52 +0xa3 fp=0xc42003efd8 sp=0xc42003efa0 pc=0x419973
      runtime.goexit()
        /usr/local/go/src/runtime/asm_amd64.s:2337 +0x1 fp=0xc42003efe0 sp=0xc42003efd8 pc=0x44b4d1
      created by runtime.gcenable
        /usr/local/go/src/runtime/mgc.go:216 +0x58
      one more line, no multiline
      ```

   1. Salve o arquivo `test.log`.

1. Dentro da pasta `multiline-app`, crie o Dockerfile.

   1. Cole o seguinte conteúdo no arquivo:

      ```
      FROM public.ecr.aws/amazonlinux/amazonlinux:latest
      ADD test.log /test.log
      
      RUN yum upgrade -y && yum install -y python3
      
      WORKDIR /usr/local/bin
      
      COPY main.py .
      
      CMD ["python3", "main.py"]
      ```

   1. Salve o arquivo `Dockerfile`.

1. Usando o Dockerfile, crie uma imagem.

   1. Crie a imagem: `docker build -t multiline-app-image `

      Onde: `multiline-app-image` é o nome da imagem neste exemplo.

   1. Verifique se a imagem foi criada corretamente: `docker images —filter reference=multiline-app-image` 

      Se tiver êxito, a saída mostrará a imagem e a etiqueta `latest`.

1. Carregue a imagem no Amazon Elastic Container Registry.

   1. Crie um repositório do Amazon ECR para armazenar a imagem: `aws ecr create-repository --repository-name multiline-app-repo --region us-east-1`

      Onde: `multiline-app-repo` é o nome do repositório e `us-east-1` é a região neste exemplo. 

      A saída fornece os detalhes do novo repositório. Anote o valor do `repositoryUri`, pois ele será necessário na próxima etapa. 

   1. Marque sua imagem com o valor `repositoryUri` da saída anterior: `docker tag multiline-app-image repositoryUri` 

      Exemplo: `docker tag multiline-app-image xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/multiline-app-repo` 

   1. Execute a imagem do Docker para verificar se ela é executada corretamente: `docker images —filter reference=repositoryUri`

      Na saída, o nome do repositório muda de `multiline-app-repo` para o valor `repositoryUri`.

   1. Envie a imagem para o Amazon ECR: `docker push aws_account_id.dkr.ecr.region.amazonaws.com/repository name` 

      Exemplo: `docker push xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/multiline-app-repo`

**Crie a definição da tarefa e execute a tarefa**

1. Crie um arquivo de definição de tarefa com o nome de arquivo `multiline-task-definition.json`. 

1. Cole o seguinte conteúdo no arquivo `multiline-task-definition.json`: 

   ```
   {
       "family": "firelens-example-multiline",
       "taskRoleArn": "task role ARN,
       "executionRoleArn": "execution role ARN",
       "containerDefinitions": [
           {
               "essential": true,
               "image": "aws_account_id.dkr.ecr.us-east-1.amazonaws.com/fluent-bit-multiline-image:latest",
               "name": "log_router",
               "firelensConfiguration": {
                   "type": "fluentbit",
                   "options": {
                       "config-file-type": "file",
                       "config-file-value": "/extra.conf"
                   }
               },
               "memoryReservation": 50
           },
           {
               "essential": true,
               "image": "aws_account_id.dkr.ecr.us-east-1.amazonaws.com/multiline-app-image:latest",
               "name": "app",
               "logConfiguration": {
                   "logDriver": "awsfirelens",
                   "options": {
                       "Name": "cloudwatch_logs",
                       "region": "us-east-1",
                       "log_group_name": "multiline-test/application",
                       "auto_create_group": "true",
                       "log_stream_prefix": "multiline-"
                   }
               },
               "memoryReservation": 100
           }
       ],
       "requiresCompatibilities": ["FARGATE"],
       "networkMode": "awsvpc",
       "cpu": "256",
       "memory": "512"
   }
   ```

   Substitua o seguinte na definição de tarefa `multiline-task-definition.json`:

   1. `task role ARN`

      Para encontrar o ARN da função de tarefa, acesse o console do IAM. Escolha **Roles** (Funções) e encontre a função de tarefa `ecs-task-role-for-firelens` que você criou. Escolha a função e copie o **ARN** que consta na seção **Summary** (Resumo).

   1. `execution role ARN`

      Para encontrar o ARN da função de execução, acesse o console do IAM. Selecione **Roles** (Funções) e localize a função `ecsTaskExecutionRole`. Escolha a função e copie o **ARN** que consta na seção **Summary** (Resumo).

   1. `aws_account_id`

      Para encontrar seu `aws_account_id`, faça login no Console de gerenciamento da AWS. Escolha seu nome de usuário no canto superior direito e copie o ID da conta.

   1. `us-east-1`

      Substitua a região, se necessário.

1. Registre o arquivo de definição de tarefa: `aws ecs register-task-definition --cli-input-json file://multiline-task-definition.json --region us-east-1` 

1. Abra o console em [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2).

1. No painel de navegação, selecione **Task Definitions** (Definições de tarefa) e, em seguida, escolha a família `firelens-example-multiline`, pois registramos a definição de tarefa para essa família na primeira linha da definição de tarefa acima.

1. Escolha a versão mais recente. 

1. Escolha **Implantar**, **Executar tarefa**. 

1. Na página **Executar tarefa**, para **Cluster**, escolha o cluster e em **Rede**, para **Sub-redes**, escolha as sub-redes disponíveis para sua tarefa. 

1. Escolha **Criar**. 

**Verifique se as mensagens de log de várias linhas no Amazon CloudWatch parecem concatenadas**

1. Abra o console do CloudWatch, em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. No painel de navegação, expanda **Logs** e escolha **Log groups** (Grupos de log). 

1. Escolha o grupo de logs `multiline-test/applicatio`. 

1. Escolha o log e veja as mensagens. As linhas que correspondem às regras no arquivo do analisador são concatenadas e aparecem como uma única mensagem. 

   O trecho de log a seguir mostra um rastreamento de pilha Go concatenado em um único evento: 

   ```
   {
       "log": "panic: my panic\n\ngoroutine 4 [running]:\npanic(0x45cb40, 0x47ad70)\n  /usr/local/go/src/runtime/panic.go:542 +0x46c fp=0xc42003f7b8 sp=0xc42003f710 pc=0x422f7c\nmain.main.func1(0xc420024120)\n  foo.go:6 +0x39 fp=0xc42003f7d8 sp=0xc42003f7b8 pc=0x451339\nruntime.goexit()\n  /usr/local/go/src/runtime/asm_amd64.s:2337 +0x1 fp=0xc42003f7e0 sp=0xc42003f7d8 pc=0x44b4d1\ncreated by main.main\n  foo.go:5 +0x58\n\ngoroutine 1 [chan receive]:\nruntime.gopark(0x4739b8, 0xc420024178, 0x46fcd7, 0xc, 0xc420028e17, 0x3)\n  /usr/local/go/src/runtime/proc.go:280 +0x12c fp=0xc420053e30 sp=0xc420053e00 pc=0x42503c\nruntime.goparkunlock(0xc420024178, 0x46fcd7, 0xc, 0x1000f010040c217, 0x3)\n  /usr/local/go/src/runtime/proc.go:286 +0x5e fp=0xc420053e70 sp=0xc420053e30 pc=0x42512e\nruntime.chanrecv(0xc420024120, 0x0, 0xc420053f01, 0x4512d8)\n  /usr/local/go/src/runtime/chan.go:506 +0x304 fp=0xc420053f20 sp=0xc420053e70 pc=0x4046b4\nruntime.chanrecv1(0xc420024120, 0x0)\n  /usr/local/go/src/runtime/chan.go:388 +0x2b fp=0xc420053f50 sp=0xc420053f20 pc=0x40439b\nmain.main()\n  foo.go:9 +0x6f fp=0xc420053f80 sp=0xc420053f50 pc=0x4512ef\nruntime.main()\n  /usr/local/go/src/runtime/proc.go:185 +0x20d fp=0xc420053fe0 sp=0xc420053f80 pc=0x424bad\nruntime.goexit()\n  /usr/local/go/src/runtime/asm_amd64.s:2337 +0x1 fp=0xc420053fe8 sp=0xc420053fe0 pc=0x44b4d1\n\ngoroutine 2 [force gc (idle)]:\nruntime.gopark(0x4739b8, 0x4ad720, 0x47001e, 0xf, 0x14, 0x1)\n  /usr/local/go/src/runtime/proc.go:280 +0x12c fp=0xc42003e768 sp=0xc42003e738 pc=0x42503c\nruntime.goparkunlock(0x4ad720, 0x47001e, 0xf, 0xc420000114, 0x1)\n  /usr/local/go/src/runtime/proc.go:286 +0x5e fp=0xc42003e7a8 sp=0xc42003e768 pc=0x42512e\nruntime.forcegchelper()\n  /usr/local/go/src/runtime/proc.go:238 +0xcc fp=0xc42003e7e0 sp=0xc42003e7a8 pc=0x424e5c\nruntime.goexit()\n  /usr/local/go/src/runtime/asm_amd64.s:2337 +0x1 fp=0xc42003e7e8 sp=0xc42003e7e0 pc=0x44b4d1\ncreated by runtime.init.4\n  /usr/local/go/src/runtime/proc.go:227 +0x35\n\ngoroutine 3 [GC sweep wait]:\nruntime.gopark(0x4739b8, 0x4ad7e0, 0x46fdd2, 0xd, 0x419914, 0x1)\n  /usr/local/go/src/runtime/proc.go:280 +0x12c fp=0xc42003ef60 sp=0xc42003ef30 pc=0x42503c\nruntime.goparkunlock(0x4ad7e0, 0x46fdd2, 0xd, 0x14, 0x1)\n  /usr/local/go/src/runtime/proc.go:286 +0x5e fp=0xc42003efa0 sp=0xc42003ef60 pc=0x42512e\nruntime.bgsweep(0xc42001e150)\n  /usr/local/go/src/runtime/mgcsweep.go:52 +0xa3 fp=0xc42003efd8 sp=0xc42003efa0 pc=0x419973\nruntime.goexit()\n  /usr/local/go/src/runtime/asm_amd64.s:2337 +0x1 fp=0xc42003efe0 sp=0xc42003efd8 pc=0x44b4d1\ncreated by runtime.gcenable\n  /usr/local/go/src/runtime/mgc.go:216 +0x58",
       "container_id": "xxxxxx-xxxxxx",
       "container_name": "app",
       "source": "stdout",
       "ecs_cluster": "default",
       "ecs_task_arn": "arn:aws:ecs:us-east-1:xxxxxxxxxxxx:task/default/xxxxxx",
       "ecs_task_definition": "firelens-example-multiline:2"
   }
   ```

   O trecho de log a seguir mostra como o mesmo evento aparece se você executar um contêiner ECS que não esteja configurado para concatenar mensagens de log de várias linhas. O campo de log contém uma única linha.

   ```
   {
       "log": "panic: my panic",
       "container_id": "xxxxxx-xxxxxx",
       "container_name": "app",
       "source": "stdout",
       "ecs_cluster": "default",
       "ecs_task_arn": "arn:aws:ecs:us-east-1:xxxxxxxxxxxx:task/default/xxxxxx",
       "ecs_task_definition": "firelens-example-multiline:3"
   ```

**nota**  
Se seus registros forem para arquivos de log em vez da saída padrão, recomendamos especificar os parâmetros de configuração `multiline.parser` e `multiline.key_content` no [Plug-in de entrada final](https://docs.fluentbit.io/manual/pipeline/inputs/tail#multiline-support) em vez do Filtro.

# Implantar o Fluent Bit em contêineres do Windows no Amazon ECS
<a name="tutorial-deploy-fluentbit-on-windows"></a>

O Fluent Bit é um processador e roteador de logs rápido e flexível compatível com vários sistemas operacionais. Ele pode ser usado para encaminhar logs a vários destinos da AWS, como o Amazon CloudWatch Logs, Firehose, Amazon S3 e Amazon OpenSearch Service. O Fluent Bit é compatível com soluções comuns de parceiros, como [Datadog](https://www.datadoghq.com/), [Splunk](https://www.splunk.com/) e servidores HTTP personalizados. Para obter mais informações sobre o Fluent Bit, consulte o site do [https://fluentbit.io/](https://fluentbit.io/).

O **AWS para Fluent Bit** está disponível no Amazon ECR na Galeria Pública do Amazon ECR e em um repositório do Amazon ECR na maioria das regiões para alta disponibilidade. Para obter mais informações, consulte [https://github.com/aws/aws-for-fluent-bit](https://github.com/aws/aws-for-fluent-bit) no site do GitHub.

Este tutorial explica como implantar contêineres do Fluent Bit em instâncias do Windows em execução no Amazon ECS para transmitir logs gerados pelas tarefas do Windows para o Amazon CloudWatch para logs centralizados. 

Este tutorial usa a seguinte abordagem:
+ O Fluent Bit é executado como um serviço com a estratégia de programação do Daemon. Essa estratégia garante que uma única instância do Fluent Bit sempre seja executada nas instâncias de contêiner no cluster.
  + Recebe na porta 24224 usando o plug-in de entrada de encaminhamento.
  + Exponha a porta 24224 ao host para que o runtime do docker possa enviar logs para o Fluent Bit usando essa porta exposta.
  + Tem uma configuração que permite que o Fluent Bit envie os registros de logs para destinos especificados.
+ Inicie todos os outros contêineres de tarefas do Amazon ECS usando o driver de log fluentd. Para obter mais informações, consulte [Fluentd logging driver](https://docs.docker.com/engine/logging/drivers/fluentd/) (Driver de log do Fluentd) no site de documentação do Docker.
  + O Docker se conecta ao soquete TCP 24224 no localhost dentro do namespace do host.
  + O agente do Amazon ECS adiciona rótulos aos contêineres, incluindo o nome do cluster, o nome da família da definição de tarefa, o número da revisão da definição de tarefa, o ARN da tarefa e o nome do contêiner. As mesmas informações são adicionadas ao registro de logs usando a opção labels (rótulos) do driver de logs do docker fluentd. Para obter mais informações, consulte [labels, labels-regex, env e env-regex](https://docs.docker.com/config/containers/logging/fluentd/#labels-labels-regex-env-and-env-regex) no site de documentação do Docker.
  + Como a opção `async` do driver de logs fluentd está definida como `true`, quando o contêiner do Fluent Bit é reiniciado, o docker armazena os logs em buffer até que o contêiner do Fluent Bit seja reiniciado. É possível aumentar o limite de armazenamento em buffer definindo a opção fluentd-buffer-limit. Para obter mais informações, consulte [fluentd-buffer-limit](https://docs.docker.com/config/containers/logging/fluentd/#fluentd-buffer-limit) no site da documentação do Docker.

 O fluxo de trabalho é o seguinte:
+ O contêiner do Fluent Bit inicia e recebe na porta 24224, que está exposta ao host.
+ O Fluent Bit usa as credenciais do perfil do IAM da tarefa especificadas na definição da tarefa.
+ Outras tarefas iniciadas na mesma instância usam o driver de logs do docker do fluentd para se conectar ao contêiner do Fluent Bit na porta 24224. 
+ Quando os contêineres da aplicação geram logs, o runtime do docker marca esses registros, adiciona metadados especificados nos rótulos e os encaminha pela porta 24224 no namespace do host. 
+ O Fluent Bit recebe o registro de log na porta 24224 porque ela está exposta ao namespace do host.
+ O Fluent Bit executa seu processamento interno e roteia os logs, conforme especificado.

Este tutorial usa a configuração padrão do Fluent Bit do CloudWatch, que faz o seguinte:
+ Cria um novo grupo de logs para cada cluster e família de definição de tarefa.
+ Cria um novo fluxo de logs para cada contêiner de tarefas no grupo de logs gerado acima sempre que uma nova tarefa é iniciada. Cada fluxo será marcado com o ID da tarefa à qual o contêiner pertence.
+ Adiciona metadados, incluindo o nome do cluster, o ARN da tarefa, o nome do contêiner da tarefa, a família de definição de tarefa e o número da revisão da definição de tarefa em cada entrada de log.

  Por exemplo, se você tiver `task_1` com `container_1` e `container_2` e t`ask_2` com `container_3`, os fluxos de logs do CloudWatch serão os seguintes:
  + `/aws/ecs/windows.ecs_task_1`

    `task-out.TASK_ID.container_1`

    `task-out.TASK_ID.container_2`
  + `/aws/ecs/windows.ecs_task_2`

    `task-out.TASK_ID.container_3`

**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
](#tutorial-deploy-fluentbit-on-windows-prereqs)
+ [

## Etapa 1: criar os perfis de acesso do IAM
](#tutorial-deploy-fluentbit-on-windows-iam-access-role)
+ [

## Etapa 2: criar uma instância de contêiner do Windows do Amazon ECS
](#tutorial-deploy-fluentbit-on-windows-instance)
+ [

## Etapa 3: configurar o Fluent Bit
](#tutorial-deploy-fluentbit-on-windows-configure-fluentbit)
+ [

## Etapa 4: registrar uma definição de tarefa do Fluent Bit no Windows que roteia os logs para o CloudWatch
](#tutorial-deploy-fluentbit-on-windows-register-task-definition)
+ [

## Etapa 5: executar a definição de tarefa `ecs-windows-fluent-bit` como um serviço do Amazon ECS usando a estratégia de programação do daemon
](#tutorial-deploy-fluentbit-on-windows-run-task)
+ [

## Etapa 6: registrar uma definição de tarefa do Windows que gere os logs
](#tutorial-deploy-fluentbit-on-windows-register-task-def-logs)
+ [

## Etapa 7: executar a definição de tarefa `windows-app-task`
](#tutorial-deploy-fluentbit-on-windows-run-task-fluentbit)
+ [

## Etapa 8: verificar os logs no CloudWatch
](#tutorial-deploy-fluentbit-on-windows-verify)
+ [

## Etapa 9: limpar
](#tutorial-deploy-fluentbit-on-windows-cleanup)

## Pré-requisitos
<a name="tutorial-deploy-fluentbit-on-windows-prereqs"></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, 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).
+ A imagem do contêiner `aws-for-fluent-bit` está disponível para os seguintes sistemas operacionais Windows:
  + Windows Server 2019 Core
  + Windows Server 2019 Full
  + Windows Server 2022 Core
  + Windows Server 2022 Full
+ As etapas em [Configuração para usar o Amazon ECS](get-set-up-for-amazon-ecs.md) foram concluídas.
+ Você tem um cluster. Neste tutorial, o nome do cluster é **FluentBit-cluster**.
+ Você tem uma VPC com uma sub-rede pública em que a instância do EC2 será iniciada. É possível usar a VPC padrão. Você também pode usar uma sub-rede privada que permita que os endpoints do Amazon CloudWatch alcancem a sub-rede. Para obter mais informações sobre endpoints do Amazon CloudWatch, consulte [Endpoints e cotas do Amazon CloudWatch](https://docs.aws.amazon.com/general/latest/gr/cw_region.html) na *Referência geral da AWS*. Para obter mais informações sobre como usar o assistente da Amazon VPC para criar uma VPC, consulte [Criar uma nuvem privada virtual](get-set-up-for-amazon-ecs.md#create-a-vpc).

## Etapa 1: criar os perfis de acesso do IAM
<a name="tutorial-deploy-fluentbit-on-windows-iam-access-role"></a>

Crie os perfis do IAM do Amazon ECS.

1.  Crie o perfil da instância de contêiner do Amazon ECS de nome "ecsInstanceRole". Para obter mais informações, consulte [Perfil do IAM de instância de contêiner do Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html).

1. Crie um perfil do IAM para a tarefa do Fluent Bit denominada `fluentTaskRole`. Para obter mais informações, consulte [Perfil do IAM para tarefas do Amazon ECS](task-iam-roles.md).

    As permissões do IAM concedidas no perfil do IAM são assumidas pelos contêineres das tarefas. Para permitir que o Fluent Bit envie logs para o CloudWatch, é preciso anexar as seguintes permissões ao perfil do IAM da tarefa.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
       {
           "Effect": "Allow",
           "Action": [
               "logs:CreateLogStream",
               "logs:CreateLogGroup",
               "logs:DescribeLogStreams",
               "logs:PutLogEvents"
           ],
           "Resource": "*"
       }
       ]
   }
   ```

------

1. Anexe a política ao perfil.

   1. Salve o conteúdo acima em um arquivo denominado `fluent-bit-policy.json`.

   1. Execute o comando a seguir para anexar a política em linha ao perfil `fluentTaskRole` do IAM.

      ```
      aws iam put-role-policy --role-name fluentTaskRole --policy-name fluentTaskPolicy --policy-document file://fluent-bit-policy.json
      ```

## Etapa 2: criar uma instância de contêiner do Windows do Amazon ECS
<a name="tutorial-deploy-fluentbit-on-windows-instance"></a>

Crie uma instância de contêiner do Windows do Amazon ECS.

**Para criar uma instância do Amazon ECS**

1. Use o comando `aws ssm get-parameters` para recuperar o ID da AMI para a região que hospeda sua VPC. Para obter mais informações, consulte [Recuperar os metadados da AMI otimizada para Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/retrieve-ecs-optimized_windows_AMI.html).

1. Use o console do Amazon EC2 para iniciar a instância.

   1. Abra o console do Amazon EC2 em [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).

   1. Na barra de navegação, selecione a Região a ser usada.

   1. No **Painel do EC2**, escolha **Launch Instance** (Iniciar instância).

   1. Em **Name (Nome)**, insira um nome exclusivo.

   1. Em **Application and OS Images (Amazon Machine Image)** (Imagens de aplicações e SO [Amazon Machine Image]), escolha a AMI que você recuperou na primeira etapa.

   1. Em **tipo de instância**, escolha `t3.xlarge`.

   1. Em **Key pair (login)** (Par de chaves [login]), escolha um par de chaves. 

   1. Em **Network settings** (Configurações de rede), em **Security group** (Grupo de segurança), selecione um grupo de segurança existente ou crie outro.

   1. Em **Network settings** (Configurações de rede), em **Auto-assign Public IPC** (Atribuir IP público automaticamente), selecione **Enable** (Habilitar). 

   1. Em **Advanced details** (Detalhes avançados), em **IAM instance profile** (Perfil de instância do IAM), escolha **ecsInstanceRole**.

   1. Configure a instância de contêiner do Amazon ECS com os dados de usuário a seguir. Em **Advanced Details** (Detalhes avançados), cole o seguinte script no campo **User data** (Dados do usuário), substituindo *cluster\$1name* pelo nome do cluster.

      ```
      <powershell>
      Import-Module ECSTools
      Initialize-ECSAgent -Cluster cluster-name -EnableTaskENI -EnableTaskIAMRole -LoggingDrivers '["awslogs","fluentd"]'
      </powershell>
      ```

   1. Quando estiver pronto, selecione o campo de confirmação e, então, escolha **Launch Instances**. 

   1. Uma página de confirmação informa que sua instância está sendo executada. Selecione **Visualizar instâncias** para fechar a página de confirmação e voltar ao console.

## Etapa 3: configurar o Fluent Bit
<a name="tutorial-deploy-fluentbit-on-windows-configure-fluentbit"></a>

É possível usar a configuração padrão a seguir fornecida pela AWS para começar rapidamente:
+ [Amazon CloudWatch](https://github.com/aws/aws-for-fluent-bit/blob/mainline/ecs_windows_forward_daemon/cloudwatch.conf), que é baseado no plug-in do Fluent Bit para [Amazon CloudWatch](https://docs.fluentbit.io/manual/v/1.9-pre/pipeline/outputs/cloudwatch) no *Manual oficial do Fluent Bit*.

Como alternativa, é possível usar outras configurações padrão fornecidas pela AWS. Para obter mais informações, consulte [Overriding the entrypoint for the Windows image](https://github.com/aws/aws-for-fluent-bit/tree/mainline/ecs_windows_forward_daemon#overriding-the-entrypoint-for-the-windows-image) (Substituir o ponto de entrada da imagem do Windows) no site `aws-for-fluent-bit` do Github.

A configuração padrão do Fluent Bit do Amazon CloudWatch é mostrada abaixo.

Substitua as seguintes variáveis:
+ *região* pela região para a qual você deseja enviar logs do Amazon CloudWatch.

```
[SERVICE]
    Flush               5
    Log_Level           info
    Daemon              off

[INPUT]
    Name                forward
    Listen              0.0.0.0
    Port                24224
    Buffer_Chunk_Size   1M
    Buffer_Max_Size     6M
    Tag_Prefix          ecs.

# Amazon ECS agent adds the following log keys as labels to the docker container.
# We would use fluentd logging driver to add these to log record while sending it to Fluent Bit.
[FILTER]
    Name                modify
    Match               ecs.*
    Rename              com.amazonaws.ecs.cluster ecs_cluster
    Rename              com.amazonaws.ecs.container-name ecs_container_name
    Rename              com.amazonaws.ecs.task-arn ecs_task_arn
    Rename              com.amazonaws.ecs.task-definition-family ecs_task_definition_family
    Rename              com.amazonaws.ecs.task-definition-version ecs_task_definition_version

[FILTER]
    Name                rewrite_tag
    Match               ecs.*
    Rule                $ecs_task_arn ^([a-z-:0-9]+)/([a-zA-Z0-9-_]+)/([a-z0-9]+)$  out.$3.$ecs_container_name false
    Emitter_Name        re_emitted

[OUTPUT]
    Name                cloudwatch_logs
    Match               out.*
    region              region
    log_group_name      fallback-group
    log_group_template  /aws/ecs/$ecs_cluster.$ecs_task_definition_family
    log_stream_prefix   task-
    auto_create_group   On
```

Cada log que entra no Fluent Bit tem uma tag que você especifica ou é gerada automaticamente quando você não fornece uma. As tags podem ser usadas para rotear diferentes logs para destinos diferentes. Para obter informações adicionais, consulte [Tag](https://docs.fluentbit.io/manual/concepts/key-concepts#tag) no *Manual oficial do Fluent Bit*. 

A configuração do Fluent Bit descrita acima tem as seguintes propriedades:
+ O plug-in de entrada de encaminhamento recebe o tráfego de entrada na porta TCP 24224. 
+ Cada entrada de log recebida nessa porta tem uma tag que o plug-in de entrada de encaminhamento modifica para prefixar o registro com a string `ecs.`. 
+ O pipeline interno do Fluent Bit roteia a entrada de log para modificar o filtro usando o regex Match (Corresponder). Esse filtro substitui as chaves no registro de log JSON pelo formato que o Fluent Bit pode consumir. 
+ A entrada de log modificada é consumida pelo filtro rewrite\$1tag. Esse filtro altera a tag do registro de log para o formato out.*TASK\$1ID*.*CONTAINER\$1NAME*. 
+ A nova tag será roteada para o plug-in cloudwatch\$1logs de saída, que cria os grupos e fluxos de logs, conforme descrito anteriormente, usando as opções `log_group_template` e `log_stream_prefix` do plug-in de saída do CloudWatch. Para obter informações adicionais, consulte [Configuration parameters](https://docs.fluentbit.io/manual/v/1.9-pre/pipeline/outputs/cloudwatch#configuration-parameters) (Parâmetros de configuração) no *Manual oficial do Fluent Bit*. 

## Etapa 4: registrar uma definição de tarefa do Fluent Bit no Windows que roteia os logs para o CloudWatch
<a name="tutorial-deploy-fluentbit-on-windows-register-task-definition"></a>

Registre uma definição de tarefa do Fluent Bit no Windows que roteia os logs para o CloudWatch.

**nota**  
Essa definição de tarefa expõe a porta 24224 do contêiner do Fluent Bit para a porta 24224 do host. Verifique se essa porta não está aberta em seu grupo de segurança de instâncias do EC2 para impedir o acesso externo.

**Para registrar uma definição de tarefa**

1. Crie um arquivo denominado `fluent-bit.json` com os conteúdos a seguir.

   Substitua as seguintes variáveis:
   + *task-iam-role* pelo nome do recurso da Amazon (ARN) do perfil do IAM da tarefa
   + *region* (região) pela região em que a tarefa é executada

   ```
   {
     "family": "ecs-windows-fluent-bit",
     "taskRoleArn": "task-iam-role",
     "containerDefinitions": [
       {
         "name": "fluent-bit",
         "image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:windowsservercore-latest",
         "cpu": 512,
         "portMappings": [
           {
             "hostPort": 24224,
             "containerPort": 24224,
             "protocol": "tcp"
           }
         ],
         "entryPoint": [
           "Powershell",
           "-Command"
         ],
         "command": [
           "C:\\entrypoint.ps1 -ConfigFile C:\\ecs_windows_forward_daemon\\cloudwatch.conf"
         ],
         "environment": [
           {
             "name": "AWS_REGION",
             "value": "region"
           }
         ],
         "memory": 512,
         "essential": true,
         "logConfiguration": {
           "logDriver": "awslogs",
           "options": {
             "awslogs-group": "/ecs/fluent-bit-logs",
             "awslogs-region": "region",
             "awslogs-stream-prefix": "flb",
             "awslogs-create-group": "true"
           }
         }
       }
     ],
     "memory": "512",
     "cpu": "512"
   }
   ```

1. Use o comando a seguir para registrar a definição de tarefa.

   ```
   aws ecs register-task-definition --cli-input-json file://fluent-bit.json --region region
   ```

   É possível listar as definições de tarefa para a conta executando o comando `list-task-definitions`. A saída exibe os valores da família e da revisão que você pode usar com `run-task` ou `start-task`.

## Etapa 5: executar a definição de tarefa `ecs-windows-fluent-bit` como um serviço do Amazon ECS usando a estratégia de programação do daemon
<a name="tutorial-deploy-fluentbit-on-windows-run-task"></a>

Depois de registrar uma definição de tarefa para sua conta, será possível executar uma tarefa no cluster. Para este tutorial, você executa uma única instância da definição de tarefa `ecs-windows-fluent-bit:1` no cluster `FluentBit-cluster`. Execute a tarefa em um serviço que use a estratégia de programação do daemon, o que garante que uma única instância do Fluent Bit sempre seja executada em cada instância de contêiner.

**Para executar uma tarefa**

1. Execute o comando a seguir para iniciar a definição de tarefa `ecs-windows-fluent-bit:1`(registrada na etapa anterior) como um serviço.
**nota**  
Essa definição de tarefa usa o driver de log `awslogs`. Sua instância de contêiner precisa ter as permissões necessárias.

   Substitua as seguintes variáveis:
   + *region* (região) pela região em que o serviço é executado

   ```
   aws ecs create-service \
       --cluster FluentBit-cluster \
       --service-name FluentBitForwardDaemonService \
       --task-definition ecs-windows-fluent-bit:1 \
       --launch-type EC2 \
       --scheduling-strategy DAEMON \
       --region region
   ```

1. Execute o comando a seguir para listar as tarefas.

   Substitua as seguintes variáveis:
   + *region* (região) pela região em que as tarefas de serviço são executadas

   ```
   aws ecs list-tasks --cluster FluentBit-cluster --region region
   ```

## Etapa 6: registrar uma definição de tarefa do Windows que gere os logs
<a name="tutorial-deploy-fluentbit-on-windows-register-task-def-logs"></a>

Registre uma definição de tarefa do Windows que gere os logs. Essa definição de tarefa implanta uma imagem de contêiner do Windows que gravará um número incremental no `stdout` a cada segundo.

A definição de tarefa usa o driver de log fluentd que se conecta à porta 24224 que o plug-in do Fluent Bit recebe. O agente do Amazon ECS rotula cada contêiner do Amazon ECS com tags, incluindo o nome do cluster, o ARN da tarefa, o nome da família da definição de tarefa, o número da revisão da definição de tarefa e o nome do contêiner da tarefa. Esses rótulos de valores-chave são passados para o Fluent Bit.

**nota**  
Essa tarefa usa o modo de rede `default`. Entretanto, também é possível usar o modo de rede `awsvpc` com a tarefa.

**Para registrar uma definição de tarefa**

1. Crie um arquivo denominado `windows-app-task.json` com os conteúdos a seguir.

   ```
   {
     "family": "windows-app-task",
     "containerDefinitions": [
       {
         "name": "sample-container",
         "image": "mcr.microsoft.com/windows/servercore:ltsc2019",
         "cpu": 512,
         "memory": 512,
         "essential": true,
         "entryPoint": [
           "Powershell",
           "-Command"
         ],
         "command": [
           "$count=1;while(1) { Write-Host $count; sleep 1; $count=$count+1;}"
         ],
         "logConfiguration": {
           "logDriver": "fluentd",
           "options": {
             "fluentd-address": "localhost:24224",
             "tag": "{{ index .ContainerLabels \"com.amazonaws.ecs.task-definition-family\" }}",
             "fluentd-async": "true",
             "labels": "com.amazonaws.ecs.cluster,com.amazonaws.ecs.container-name,com.amazonaws.ecs.task-arn,com.amazonaws.ecs.task-definition-family,com.amazonaws.ecs.task-definition-version"
           }
         }
       }
     ],
     "memory": "512",
     "cpu": "512"
   }
   ```

1. Use o comando a seguir para registrar a definição de tarefa.

   Substitua as seguintes variáveis:
   + *region* (região) pela região em que a tarefa é executada

   ```
   aws ecs register-task-definition --cli-input-json file://windows-app-task.json --region region
   ```

   É possível listar as definições de tarefa para a conta executando o comando `list-task-definitions`. A saída exibe os valores da família e da revisão que você pode usar com `run-task` ou `start-task`.

## Etapa 7: executar a definição de tarefa `windows-app-task`
<a name="tutorial-deploy-fluentbit-on-windows-run-task-fluentbit"></a>

Depois de registrar a definição de tarefa `windows-app-task`, execute-a no cluster `FluentBit-cluster`.

**Para executar uma tarefa**

1. Execute a definição de tarefa `windows-app-task:1` que você registrou na etapa anterior.

   Substitua as seguintes variáveis:
   + *region* (região) pela região em que a tarefa é executada

   ```
   aws ecs run-task --cluster FluentBit-cluster --task-definition windows-app-task:1 --count 2 --region region
   ```

1. Execute o comando a seguir para listar as tarefas.

   ```
   aws ecs list-tasks --cluster FluentBit-cluster
   ```

## Etapa 8: verificar os logs no CloudWatch
<a name="tutorial-deploy-fluentbit-on-windows-verify"></a>

Para verificar a configuração do Fluent Bit, verifique os seguintes grupos de log no console do CloudWatch:
+ `/ecs/fluent-bit-logs`: este é o grupo de logs que corresponde ao contêiner do daemon do Fluent Bit que está sendo executado na instância de contêiner.
+ `/aws/ecs/FluentBit-cluster.windows-app-task`: este é o grupo de logs que corresponde a todas as tarefas iniciadas para a família de definição de tarefa `windows-app-task` dentro do cluster `FluentBit-cluster`.

   `task-out.FIRST_TASK_ID.sample-container`: este fluxo de logs contém todos os logs gerados pela primeira instância da tarefa no contêiner de tarefas do contêiner de amostra. 

  `task-out.SECOND_TASK_ID.sample-container`: este fluxo de logs contém todos os logs gerados pela segunda instância da tarefa no contêiner de tarefas do contêiner de amostra. 

 O fluxo de logs `task-out.TASK_ID.sample-container` tem campos semelhantes aos seguintes:

```
{
    "source": "stdout",
    "ecs_task_arn": "arn:aws:ecs:region:0123456789012:task/FluentBit-cluster/13EXAMPLE",
    "container_name": "/ecs-windows-app-task-1-sample-container-cEXAMPLE",
    "ecs_cluster": "FluentBit-cluster",
    "ecs_container_name": "sample-container",
    "ecs_task_definition_version": "1",
    "container_id": "61f5e6EXAMPLE",
    "log": "10",
    "ecs_task_definition_family": "windows-app-task"
}
```

**Para verificar a configuração do Fluent Bit**

1. Abra o console do CloudWatch, em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1. No painel de navegação, escolha **Grupos de logs**. Certifique-se de que você esteja na região em que implantou o Fluent Bit para seus contêineres.

   Na lista de grupos de log na Região da AWS, você deve ver o seguinte:
   + `/ecs/fluent-bit-logs`
   + `/aws/ecs/FluentBit-cluster.windows-app-task`

   Caso você veja esses grupos de logs, a configuração do Fluent Bit estará verificada.

## Etapa 9: limpar
<a name="tutorial-deploy-fluentbit-on-windows-cleanup"></a>

Ao concluir este tutorial, limpe os recursos associados a ele para evitar cobranças por recursos que você não está usando. 

**Para limpar os recursos do tutorial**

1. Interrompa as tarefas `windows-simple-task` e `ecs-fluent-bit`. Para obter mais informações, consulte [Interrupção de uma tarefa do Amazon ECS](standalone-task-stop.md).

1. Execute o comando a seguir para excluir o grupo de logs `/ecs/fluent-bit-logs`. Para obter mais informações sobre a exclusão de grupos de logs, consulte [delete-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/delete-log-group.html) na *Referência do AWS Command Line Interface*.

   ```
   aws logs delete-log-group --log-group-name /ecs/fluent-bit-logs
   aws logs delete-log-group --log-group-name /aws/ecs/FluentBit-cluster.windows-app-task
   ```

1. Execute o comando a seguir para encerrar a instância.

   ```
   aws ec2 terminate-instances --instance-ids instance-id
   ```

1. Execute o comando a seguir para excluir os perfis do IAM. 

   ```
   aws iam delete-role --role-name ecsInstanceRole
   aws iam delete-role --role-name fluentTaskRole
   ```

1. Execute o comando a seguir para excluir o cluster do Amazon ECS.

   ```
   aws ecs delete-cluster --cluster FluentBit-cluster
   ```

# Usar gMSA para contêineres do Linux do EC2 no Amazon ECS
<a name="linux-gmsa"></a>

O Amazon ECS oferece suporte à autenticação do Active Directory para contêineres do Linux no EC2 por meio de um tipo especial de conta de serviço denominada *Conta de serviço gerenciada por grupo* (gMSA).

Aplicações de rede baseadas no Linux, como as aplicações .NET Core, podem usar o Active Directory para facilitar o gerenciamento da autenticação e da autorização entre usuários e serviços. É possível usar esse recurso criando aplicações que se integram ao Active Directory e são executadas em servidores associados ao domínio. Mas, como os contêineres do Linux não podem ser associados a um domínio, você precisa configurar um contêiner do Linux para ser executado com o gMSA.

Um contêiner do Linux executado com gMSA depende do daemon `credentials-fetcher` executado na instância do Amazon EC2 hospedeira do contêiner. Ou seja, o daemon recupera as credenciais do gMSA do controlador de domínio do Active Directory e, em seguida, transfere essas credenciais para a instância de contêiner. Para obter mais informações sobre contas de serviço, consulte [Criação de gMSAs para contêineres do Windows](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/manage-serviceaccounts) no site do Microsoft Learn.

## Considerações
<a name="linux-gmsa-considerations"></a>

Considere o seguinte antes de usar gMSA para contêineres do Linux:
+ Se seus contêineres são executados no EC2, é possível usar gMSA para contêineres do Windows e contêineres do Linux. Para obter informações sobre como usar gMSA no contêiner do Linux no Fargate, consulte [Uso de gMSA em contêineres do Linux no Fargate](fargate-linux-gmsa.md).
+ Talvez você precise de um computador Windows associado ao domínio para concluir os pré-requisitos. Por exemplo, é possível que seja preciso um computador Windows associado ao domínio para criar o gMSA no Active Directory com o PowerShell. As ferramentas PowerShell do Active Director RSAT estão disponíveis somente para Windows. Para obter mais informações, consulte [Instalação das ferramentas de administração do Active Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_install_ad_tools.html).
+ Você escolhe entre **gMSA sem domínio** e **associar cada instância a um único domínio**. Ao usar gMSA sem domínio, a instância de contêiner não será associada ao domínio, outras aplicações na instância não podem usar as credenciais para acessar o domínio e as tarefas que associam domínios diferentes podem ser executadas na mesma instância.

  Em seguida, escolha o armazenamento de dados para o CredSpec e, opcionalmente, para as credenciais de usuário do Active Directory para o gMSA sem domínio.

  O Amazon ECS usa um arquivo de especificação de credenciais do Active Directory (CredSpec). Esse arquivo contém os metadados de gMSA usados para propagar o contexto da conta de gMSA para o contêiner. Você gera o arquivo CredSpec e o armazena em uma das opções de armazenamento do CredSpec na tabela a seguir, específica para o sistema operacional das instâncias de contêiner. Para usar o método sem domínio, uma seção opcional no arquivo CredSpec pode especificar credenciais em uma das opções de armazenamento de *domainless user credentials* na tabela a seguir, específica para o sistema operacional das instâncias de contêiner.    
<a name="gmsa-table"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonECS/latest/developerguide/linux-gmsa.html)

## Pré-requisitos
<a name="linux-gmsa-prerequisites"></a>

Antes de usar o recurso gMSA para contêineres do Linux com o Amazon ECS, verifique se você concluiu o seguinte:
+ Você configurou um domínio do Active Directory com os recursos que deseja que seus contêineres acessem. O Amazon ECS oferece suporte às configurações a seguir:
  + Um Active Directory Directory Service. O Directory Service é um Active Directory gerenciado pela AWS e hospedado no Amazon EC2. Para obter mais informações, consulte [Conceitos básicos do Microsoft AD gerenciado pela AWS](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html) no *Guia de administração do AWS Directory Service*.
  + Um Active Directory on-premises. Você deve garantir que a instância de contêiner Linux do Amazon ECS possa se associar ao domínio. Para obter mais informações, consulte [AWS Direct Connect](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/aws-direct-connect.html).
+ Você tem uma conta de gMSA existente no Active Directory. Para obter mais informações, consulte [Usar gMSA para contêineres do Linux do EC2 no Amazon ECS](#linux-gmsa).
+ Você instalou e está executando o daemon `credentials-fetcher` em uma instância de contêiner do Linux do Amazon ECS. Você também adicionou um conjunto inicial de credenciais ao daemon `credentials-fetcher` para se autenticar no Active Directory.
**nota**  
O daemon `credentials-fetcher` só está disponível para Amazon Linux 2023 e Fedora 37 e versões posteriores. O daemon não está disponível para o Amazon Linux 2. Para obter mais informações, consulte [aws/credentials-fetcher](https://github.com/aws/credentials-fetcher) no GitHub.
+ Você configurou as credenciais do daemon `credentials-fetcher` para se autenticar no Active Directory. As credenciais devem ser um membro do grupo de segurança do Active Directory que tenha acesso à conta gMSA. Existem várias opções em [Decida se você quer associar as instâncias ao domínio ou usar gMSA sem domínio.](#linux-gmsa-initial-creds).
+ Você adicionou as permissões necessárias do IAM. As permissões necessárias dependem dos métodos escolhidos para as credenciais iniciais e para armazenar a especificação da credencial:
  + Se você usa o *gMSA sem domínio* para as credenciais iniciais, as permissões do IAM para o AWS Secrets Manager são necessárias no perfil de execução da tarefa.
  + Se você armazenar a especificação da credencial no SSM Parameter Store, as permissões do IAM para o Amazon EC2 Systems Manager Parameter Store serão necessárias no perfil de execução da tarefa.
  + Se você armazenar a especificação da credencial no Amazon S3, as permissões do IAM para o Amazon Simple Storage Service serão necessárias no perfil de execução da tarefa.

## Configuração de contêineres do Linux compatíveis com o gMSA no Amazon ECS
<a name="linux-gmsa-setup"></a>
<a name="linux-gmsa-setup-infra"></a>
**Preparar a infraestrutura**  
As etapas a seguir são considerações e configurações que são executadas uma vez. Depois de concluir essas etapas, será possível automatizar a criação de instâncias de contêiner para reutilizar essa configuração.

Decida como as credenciais iniciais serão fornecidas e configure os dados do usuário do EC2 em um modelo de execução do EC2 reutilizável para instalar o daemon `credentials-fetcher`.

1. <a name="linux-gmsa-initial-creds"></a>

**Decida se você quer associar as instâncias ao domínio ou usar gMSA sem domínio.**
   + <a name="linux-gmsa-initial-join"></a>

**Associar instâncias do EC2 ao domínio do Active Directory**

     
     + <a name="linux-gmsa-initial-join-userdata"></a>

**Associar as instâncias por dados do usuário**

       Adicione as etapas de associação ao domínio do Active Directory aos seus dados de usuário do EC2 em um modelo de execução do EC2. Vários grupos do Amazon EC2 Auto Scaling podem usar o mesmo modelo de execução.

       É possível usar as etapas em [Associar a um domínio do Active Directory ou FreeIPA](https://docs.fedoraproject.org/en-US/quick-docs/join-active-directory-freeipa/) no Fedora Docs.
   + <a name="linux-gmsa-initial-domainless"></a>

**Crie um usuário do Active Directory para gMSA sem domínio**

     O daemon `credentials-fetcher` tem um recurso chamado *gMSA sem domínio*. Esse recurso requer um domínio, mas a instância do EC2 não precisa estar associada ao domínio. Ao usar gMSA sem domínio, a instância de contêiner não será associada ao domínio, outras aplicações na instância não podem usar as credenciais para acessar o domínio e as tarefas que associam domínios diferentes podem ser executadas na mesma instância. Em vez disso, você fornece o nome de um segredo no AWS Secrets Manager no arquivo CredSpec. O segredo deve conter um nome de usuário, uma senha e o domínio no qual fazer login.

     Há suporte para esse recurso e ele pode ser usado com contêineres Linux e Windows.

     Esse recurso é semelhante ao recurso *gMSA support for non-domain-joined container hosts*. Para obter mais informações sobre o recurso do Windows, consulte [Arquitetura e melhorias do gMSA](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/manage-serviceaccounts#gmsa-architecture-and-improvements) no site do Microsoft Learn.

     1. Crie um usuário no seu domínio do Active Directory. O usuário no Active Directory deve ter permissão para acessar as contas de serviço do gMSA que você usa nas tarefas.

     1. Crie um segredo no AWS Secrets Manager, depois de criar o usuário no Active Directory. Para obter mais informações, consulte [Criar um segredo no AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html).

     1. Insira o nome de usuário, a senha e o domínio do usuário nos pares de valores-chave JSON denominados `username`, `password` e `domainName`, respectivamente.

        ```
        {"username":"username","password":"passw0rd", "domainName":"example.com"}
        ```

     1. Adicione a configuração ao arquivo CredSpec da conta de serviço. A `HostAccountConfig` adicional contém o nome do recurso da Amazon (ARN) do segredo no Secrets Manager

        No Windows, o `PluginGUID` deve corresponder ao GUID no trecho de exemplo a seguir. No Linux, o `PluginGUID` é ignorado. Substitua `MySecret` pelo exemplo com o nome do recurso da Amazon (ARN) do seu segredo.

        ```
            "ActiveDirectoryConfig": {
                "HostAccountConfig": {
                    "PortableCcgVersion": "1",
                    "PluginGUID": "{859E1386-BDB4-49E8-85C7-3070B13920E1}",
                    "PluginInput": {
                        "CredentialArn": "arn:aws:secretsmanager:aws-region:111122223333:secret:MySecret"
                    }
                }
        ```

     1. O recurso *gMSA sem domínio* precisa de permissões adicionais no perfil de execução da tarefa. Siga a etapa [(Opcional) Segredo de gMSA sem domínio](#linux-gmsa-domainless-secret).

1. <a name="linux-gmsa-install"></a>

**Configurar instâncias e instalar o daemon `credentials-fetcher`**

   É possível instalar o daemon `credentials-fetcher` com um script de dados do usuário em seu modelo de inicialização do EC2. Os exemplos a seguir demonstram dois tipos de dados do usuário, `cloud-config` YAML ou script de bash. Esses exemplos são para o Amazon Linux 2023 (AL2023). Substitua `MyCluster` pelo nome do cluster do Amazon ECS ao qual você deseja que essas instâncias se associem.
   + <a name="linux-gmsa-install-yaml"></a>

**`cloud-config` YAML**

     ```
     Content-Type: text/cloud-config
     package_reboot_if_required: true
     packages:
       # prerequisites
       - dotnet
       - realmd
       - oddjob
       - oddjob-mkhomedir
       - sssd
       - adcli
       - krb5-workstation
       - samba-common-tools
       # https://github.com/aws/credentials-fetcher gMSA credentials management for containers
       - credentials-fetcher
     write_files:
     # configure the ECS Agent to join your cluster.
     # replace MyCluster with the name of your cluster.
     - path: /etc/ecs/ecs.config
       owner: root:root
       permissions: '0644'
       content: |
         ECS_CLUSTER=MyCluster
         ECS_GMSA_SUPPORTED=true
     runcmd:
     # start the credentials-fetcher daemon and if it succeeded, make it start after every reboot
     - "systemctl start credentials-fetcher"
     - "systemctl is-active credentials-fetcher && systemctl enable credentials-fetcher"
     ```
   + <a name="linux-gmsa-install-userdata"></a>

**Script bash**

     Se você se sentir mais confortável com scripts de bash e tiver várias variáveis nas quais escrever em `/etc/ecs/ecs.config`, use o formato `heredoc` a seguir. Esse formato grava tudo entre as linhas que começam com **cat** e `EOF` no arquivo de configuração.

     ```
     #!/usr/bin/env bash
     set -euxo pipefail
     
     # prerequisites
     timeout 30 dnf install -y dotnet realmd oddjob oddjob-mkhomedir sssd adcli krb5-workstation samba-common-tools
     # install https://github.com/aws/credentials-fetcher gMSA credentials management for containers
     timeout 30 dnf install -y credentials-fetcher
     
     # start credentials-fetcher
     systemctl start credentials-fetcher
     systemctl is-active credentials-fetcher && systemctl enable credentials-fetcher
     
     cat <<'EOF' >> /etc/ecs/ecs.config
     ECS_CLUSTER=MyCluster
     ECS_GMSA_SUPPORTED=true
     EOF
     ```

   Há variáveis de configuração opcionais para o daemon `credentials-fetcher` que pode ser configurado em `/etc/ecs/ecs.config`. Recomendamos que você defina as variáveis nos dados do usuário no bloco YAML ou `heredoc` forma semelhante aos exemplos anteriores. Isso evitará problemas com a configuração parcial que podem ocorrer com a edição de um arquivo várias vezes. Para obter mais informações sobre a configuração do agente de ECS, consulte [Agente de contêiner do Amazon ECS](https://github.com/aws/amazon-ecs-agent/blob/master/README.md#environment-variables) no GitHub.
   + Opcionalmente, é possível usar a variável `CREDENTIALS_FETCHER_HOST` se alterar a configuração do daemon `credentials-fetcher` para mover o soquete para outro local.

**Configuração de permissões e segredos**  
Execute as etapas a seguir uma vez para cada aplicação e cada definição de tarefa. Use as práticas recomendadas de concessão de privilégio mínimo e restrinja as permissões usadas na política. Dessa forma, cada tarefa só pode ler os segredos de que precisa.

1. <a name="linux-gmsa-domainless-secret"></a>

**(Opcional) Segredo de gMSA sem domínio**

   Se você usar o método sem domínio em que a instância não está associada ao domínio, siga esta etapa.

   É preciso adicionar as permissões a seguir como uma política em linha ao perfil do IAM de execução da tarefa. Isso dá ao daemon `credentials-fetcher` acesso ao segredo do Secrets Manager. Substitua o exemplo `MySecret` pelo nome do recurso da Amazon (ARN) do seu segredo na lista `Resource`.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "secretsmanager:GetSecretValue"
               ],
               "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-AbCdEf"
           }
       ]
   }
   ```

------
**nota**  
Se você usar sua própria chave KMS para criptografar seu segredo, deverá adicionar as permissões necessárias a esse perfil e adicioná-lo à política de chaves AWS KMS.

1. 

**Decida se você está usando o SSM Parameter Store ou o S3 para armazenar o CredSpec**

   O Amazon ECS é compatível com as seguintes maneiras de referenciar o caminho do arquivo no campo `credentialSpecs` de definição da tarefa.

   Se você associar as instâncias em um domínio único, use o prefixo `credentialspec:` no início do ARN na string. Se você usa gMSA sem domínio, use `credentialspecdomainless:`.

   Para obter mais informações sobre o CredSpec, consulte [Arquivo de especificação de credenciais](#linux-gmsa-credentialspec).
   + <a name="linux-gmsa-credspec-s3"></a>

**Bucket do Amazon S3**

     Adicione a especificação da credencial a um bucket do Amazon S3. Em seguida, referencie o nome do recurso da Amazon (ARN) do bucket do Amazon S3 no campo `credentialSpecs` da definição de tarefa.

     ```
     {
         "family": "",
         "executionRoleArn": "",
         "containerDefinitions": [
             {
                 "name": "",
                 ...
                 "credentialSpecs": [
                     "credentialspecdomainless:arn:aws:s3:::${BucketName}/${ObjectName}"
                 ],
                 ...
             }
         ],
         ...
     }
     ```

     Para fornecer às suas tarefas acesso ao bucket do S3, adicione as permissões a seguir como uma política em linha ao perfil do IAM de execução da tarefa do Amazon ECS.

------
#### [ JSON ]

****  

     ```
     {
         "Version":"2012-10-17",		 	 	 
         "Statement": [
             {
                 "Sid": "VisualEditor",
                 "Effect": "Allow",
                 "Action": [
                     "s3:Get*",
                     "s3:List*"
                 ],
                 "Resource": [
                     "arn:aws:s3:::amzn-s3-demo-bucket",
                     "arn:aws:s3:::amzn-s3-demo-bucket/{object}"
                 ]
             }
         ]
     }
     ```

------
   + <a name="linux-gmsa-credspec-ssm"></a>

**Parâmetro do Parameter Store do SSM**

     Adicione a especificação da credencial a um parâmetro do SSM Parameter Store. Em seguida, referencie o nome do recurso da Amazon (ARN) do parâmetro do SSM Parameter Store no campo `credentialSpecs` da definição da tarefa.

     ```
     {
         "family": "",
         "executionRoleArn": "",
         "containerDefinitions": [
             {
                 "name": "",
                 ...
                 "credentialSpecs": [
                     "credentialspecdomainless:arn:aws:ssm:aws-region:111122223333:parameter/parameter_name"
                 ],
                 ...
             }
         ],
         ...
     }
     ```

     Para fornecer às suas tarefas acesso ao parâmetro do SSM Parameter Store, adicione as permissões a seguir como uma política em linha ao perfil do IAM de execução da tarefa do Amazon ECS.

------
#### [ JSON ]

****  

     ```
     {
         "Version":"2012-10-17",		 	 	 
         "Statement": [
             {
                 "Effect": "Allow",
                 "Action": [
                     "ssm:GetParameters"
                 ],
                 "Resource": "arn:aws:ssm:us-east-1:123456789012:parameter/my-parameter"
             }
         ]
     }
     ```

------

## Arquivo de especificação de credenciais
<a name="linux-gmsa-credentialspec"></a>

O Amazon ECS usa um arquivo de especificação de credenciais do Active Directory (*CredSpec*). Esse arquivo contém os metadados do gMSA usados para propagar o contexto da conta gMSA para o contêiner de Linux. Você gera o CredSpec e o referencia no campo `credentialSpecs` em sua definição de tarefa. O arquivo CredSpec não contém nenhum segredo.

Veja a seguir um exemplo de arquivo CredSpec.

```
{
    "CmsPlugins": [
        "ActiveDirectory"
    ],
    "DomainJoinConfig": {
        "Sid": "S-1-5-21-2554468230-2647958158-2204241789",
        "MachineAccountName": "WebApp01",
        "Guid": "8665abd4-e947-4dd0-9a51-f8254943c90b",
        "DnsTreeName": "example.com",
        "DnsName": "example.com",
        "NetBiosName": "example"
    },
    "ActiveDirectoryConfig": {
        "GroupManagedServiceAccounts": [
            {
                "Name": "WebApp01",
                "Scope": "example.com"
            }
        ],
        "HostAccountConfig": {
            "PortableCcgVersion": "1",
            "PluginGUID": "{859E1386-BDB4-49E8-85C7-3070B13920E1}",
            "PluginInput": {
                "CredentialArn": "arn:aws:secretsmanager:aws-region:111122223333:secret:MySecret"
            }
        }
    }
}
```
<a name="linux-gmsa-credentialspec-create"></a>
**Criação de um CredSpec**  
Você cria um CredSpec usando o módulo CredSpec PowerShell em um computador Windows que esteja associado ao domínio. Siga as etapas em [Criar uma especificação de credencial](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/manage-serviceaccounts#create-a-credential-spec) no site do Microsoft Learn.

# Uso de gMSA em contêineres do Linux no Fargate
<a name="fargate-linux-gmsa"></a>

O Amazon ECS oferece suporte à autenticação do Active Directory para contêineres do Linux no Fargate por meio de um tipo especial de conta de serviço denominada *Conta de serviço gerenciada por grupo* (gMSA).

Aplicações de rede baseadas no Linux, como as aplicações .NET Core, podem usar o Active Directory para facilitar o gerenciamento da autenticação e da autorização entre usuários e serviços. É possível usar esse recurso criando aplicações que se integram ao Active Directory e são executadas em servidores associados ao domínio. Mas, como os contêineres do Linux não podem ser associados a um domínio, você precisa configurar um contêiner do Linux para ser executado com o gMSA.

## Considerações
<a name="fargate-linux-gmsa-considerations"></a>

Considere o seguinte antes de usar o gMSA em contêineres do Linux no Fargate:
+ Você deve estar executando a versão da plataforma 1.4 ou posterior.
+ Talvez você precise de um computador Windows associado ao domínio para concluir os pré-requisitos. Por exemplo, é possível que seja preciso um computador Windows associado ao domínio para criar o gMSA no Active Directory com o PowerShell. As ferramentas PowerShell do Active Director RSAT estão disponíveis somente para Windows. Para obter mais informações, consulte [Instalação das ferramentas de administração do Active Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_install_ad_tools.html).
+ Você deve usar o **gMSA sem domínio**. 

  O Amazon ECS usa um arquivo de especificação de credenciais do Active Directory (CredSpec). Esse arquivo contém os metadados de gMSA usados para propagar o contexto da conta de gMSA para o contêiner. Você gera o arquivo CredSpec e o armazena em um bucket do Amazon S3.
+ Uma tarefa só é compatível com um Active Directory.

## Pré-requisitos
<a name="fargate-linux-gmsa-prerequisites"></a>

Antes de usar o recurso gMSA para contêineres do Linux com o Amazon ECS, verifique se você concluiu o seguinte:
+ Você configurou um domínio do Active Directory com os recursos que deseja que seus contêineres acessem. O Amazon ECS oferece suporte às configurações a seguir:
  + Um Active Directory Directory Service. O Directory Service é um Active Directory gerenciado pela AWS e hospedado no Amazon EC2. Para obter mais informações, consulte [Conceitos básicos do Microsoft AD gerenciado pela AWS](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html) no *Guia de administração do AWS Directory Service*.
  + Um Active Directory on-premises. Você deve garantir que a instância de contêiner Linux do Amazon ECS possa se associar ao domínio. Para obter mais informações, consulte [AWS Direct Connect](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/aws-direct-connect-network-to-amazon.html).
+ Você tem uma conta existente do gMSA no Active Directory e um usuário com permissão para acessar a conta de serviço do gMSA. Para obter mais informações, consulte [Crie um usuário do Active Directory para gMSA sem domínio](#fargate-linux-gmsa-initial-domainless).
+ Você tem um bucket do Amazon S3. Para obter mais informações, consulte [Como criar um bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) no *Guia do usuário do Amazon S3*.

## Configuração de contêineres do Linux compatíveis com o gMSA no Amazon ECS
<a name="fargate-linux-gmsa-setup"></a>
<a name="linux-gmsa-setup-infra"></a>
**Preparar a infraestrutura**  
As etapas a seguir são considerações e configurações que são executadas uma vez. 
+ <a name="fargate-linux-gmsa-initial-domainless"></a>

**Crie um usuário do Active Directory para gMSA sem domínio**

  Ao usar gMSA sem domínio, o contêiner não é associado ao domínio. Outras aplicações executadas no contêiner não podem usar as credenciais para acessar o domínio. Tarefas que usam um domínio diferente podem ser executadas no mesmo contêiner. Forneça o nome de um segredo no AWS Secrets Manager no arquivo CredSpec. O segredo deve conter um nome de usuário, uma senha e o domínio no qual fazer login.

  Esse recurso é semelhante ao recurso *gMSA support for non-domain-joined container hosts*. Para obter mais informações sobre o recurso do Windows, consulte [Arquitetura e melhorias do gMSA](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/manage-serviceaccounts#gmsa-architecture-and-improvements) no site do Microsoft Learn.

  1. Configure um usuário em seu domínio do Active Directory. O usuário no Active Directory deve ter permissão para acessar a conta de serviço do gMSA que você usa nas tarefas.

  1. Você tem uma VPC e sub-redes que podem resolver o nome de domínio do Active Directory. Configure a VPC com opções de DHCP com o nome de domínio que direciona ao nome de serviço do Active Directory. Para obter informações sobre como configurar opções de DHCP em uma VPC, consulte [Trabalhar com conjuntos de opções DHCP](https://docs.aws.amazon.com/vpc/latest/userguide/DHCPOptionSet.html) no *Guia do usuário da Amazon Virtual Private Cloud*.

  1. Crie um segredo no AWS Secrets Manager. 

  1. Crie o arquivo de especificação da credencial.

**Configuração de permissões e segredos**  
Execute as etapas a seguir uma vez para cada aplicação e cada definição de tarefa. Use as práticas recomendadas de concessão de privilégio mínimo e restrinja as permissões usadas na política. Dessa forma, cada tarefa só pode ler os segredos de que precisa.

1. Crie um usuário no seu domínio do Active Directory. O usuário no Active Directory deve ter permissão para acessar as contas de serviço do gMSA que você usa nas tarefas.

1. Crie um segredo no AWS Secrets Manager, depois de criar o usuário no Active Directory. Para obter mais informações, consulte [Criar um segredo no AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html).

1. Insira o nome de usuário, a senha e o domínio do usuário nos pares de valores-chave JSON denominados `username`, `password` e `domainName`, respectivamente.

   ```
   {"username":"username","password":"passw0rd", "domainName":"example.com"}
   ```

1. <a name="fargate-linux-gmsa-domainless-secret"></a>É preciso adicionar as permissões a seguir como uma política em linha ao perfil do IAM de execução da tarefa. Isso dá ao daemon `credentials-fetcher` acesso ao segredo do Secrets Manager. Substitua o exemplo `MySecret` pelo nome do recurso da Amazon (ARN) do seu segredo na lista `Resource`.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "secretsmanager:GetSecretValue"
               ],
               "Resource": [
               "arn:aws:secretsmanager:us-east-1:111122223333:secret:MySecret"
               ]
           }
       ]
   }
   ```

------
**nota**  
Se você usar sua própria chave KMS para criptografar seu segredo, deverá adicionar as permissões necessárias a esse perfil e adicioná-lo à política de chaves AWS KMS.

1. <a name="linux-gmsa-credspec-ssm"></a>Adicione a especificação da credencial a um bucket do Amazon S3. Em seguida, referencie o nome do recurso da Amazon (ARN) do bucket do Amazon S3 no campo `credentialSpecs` da definição de tarefa.

   ```
   {
       "family": "",
       "executionRoleArn": "",
       "containerDefinitions": [
           {
               "name": "",
               ...
               "credentialSpecs": [
                   "credentialspecdomainless:arn:aws:s3:::${BucketName}/${ObjectName}"
               ],
               ...
           }
       ],
       ...
   }
   ```

   Para fornecer às suas tarefas acesso ao bucket do S3, adicione as permissões a seguir como uma política em linha ao perfil do IAM de execução da tarefa do Amazon ECS.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Sid": "VisualEditor",
               "Effect": "Allow",
               "Action": [
               "s3:GetObjectVersion",
               "s3:ListBucket"
               ],
               "Resource": [
                   "arn:aws:s3:::{bucket_name}",
                   "arn:aws:s3:::{bucket_name}/{object}"
               ]
           }
       ]
   }
   ```

------

## Arquivo de especificação de credenciais
<a name="fargate-linux-gmsa-credentialspec"></a>

O Amazon ECS usa um arquivo de especificação de credenciais do Active Directory (*CredSpec*). Esse arquivo contém os metadados do gMSA usados para propagar o contexto da conta gMSA para o contêiner de Linux. Você gera o CredSpec e o referencia no campo `credentialSpecs` em sua definição de tarefa. O arquivo CredSpec não contém nenhum segredo.

Veja a seguir um exemplo de arquivo CredSpec.

```
{
    "CmsPlugins": [
        "ActiveDirectory"
    ],
    "DomainJoinConfig": {
        "Sid": "S-1-5-21-2554468230-2647958158-2204241789",
        "MachineAccountName": "WebApp01",
        "Guid": "8665abd4-e947-4dd0-9a51-f8254943c90b",
        "DnsTreeName": "example.com",
        "DnsName": "example.com",
        "NetBiosName": "example"
    },
    "ActiveDirectoryConfig": {
        "GroupManagedServiceAccounts": [
            {
                "Name": "WebApp01",
                "Scope": "example.com"
            }
        ],
        "HostAccountConfig": {
            "PortableCcgVersion": "1",
            "PluginGUID": "{859E1386-BDB4-49E8-85C7-3070B13920E1}",
            "PluginInput": {
                "CredentialArn": "arn:aws:secretsmanager:aws-region:111122223333:secret:MySecret"
            }
        }
    }
}
```
<a name="fargate-linux-gmsa-credentialspec-create"></a>
**Como criar um CredSpec e fazer upload em um Amazon S3**  
Você cria um CredSpec usando o módulo CredSpec PowerShell em um computador Windows que esteja associado ao domínio. Siga as etapas em [Criar uma especificação de credencial](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/manage-serviceaccounts#create-a-credential-spec) no site do Microsoft Learn.

Depois de criar o arquivo de especificação da credencial, faça upload dele em um bucket do Amazon S3. Copie o arquivo CredSpec para o computador ou ambiente em que você está executando os comandos da AWS CLI.

Execute o comando AWS CLI a seguir para fazer upload do CredSpec no Amazon S3. Substitua `amzn-s3-demo-bucket` pelo nome do bucket do Amazon S3. É possível armazenar o arquivo como um objeto em qualquer bucket e local, mas deve permitir o acesso a esse bucket e ao local na política que você anexa ao perfil de execução da tarefa.

No PowerShell, use o seguinte comando:

```
$ Write-S3Object -BucketName "amzn-s3-demo-bucket" -Key "ecs-domainless-gmsa-credspec" -File "gmsa-cred-spec.json"
```

O comando da AWS CLI a seguir usa caracteres de continuação de barra invertida que são usados pelo `sh` e por shells compatíveis. 

```
$ aws s3 cp gmsa-cred-spec.json \
s3://amzn-s3-demo-bucket/ecs-domainless-gmsa-credspec
```

# Usar contêineres do Windows no Amazon ECS com gMSA sem domínio usando a AWS CLI
<a name="tutorial-gmsa-windows"></a>

O tutorial a seguir mostra como criar uma tarefa do Amazon ECS que execute um contêiner do Windows com credenciais para acessar o Active Directory com a AWS CLI. Ao usar gMSA sem domínio, a instância de contêiner não será associada ao domínio, outras aplicações na instância não podem usar as credenciais para acessar o domínio e as tarefas que associam domínios diferentes podem ser executadas na mesma instância.

**Topics**
+ [

## Pré-requisitos
](#tutorial-gmsa-windows-prerequisites)
+ [

## Etapa 1: criar e configurar a conta gMSA nos Serviços de Domínio Active Directory (AD DS)
](#tutorial-gmsa-windows-step1)
+ [

## Etapa 2: fazer upload de credenciais no Secrets Manager
](#tutorial-gmsa-windows-step2)
+ [

## Etapa 3: modificar seu JSON do CredSpec para incluir informações do gMSA sem domínio
](#tutorial-gmsa-windows-step3)
+ [

## Etapa 4: fazer upload do CredSpec no Amazon S3
](#tutorial-gmsa-windows-step4)
+ [

## Etapa 5: (opcional) criar um cluster do Amazon ECS
](#tutorial-gmsa-windows-step5)
+ [

## Etapa 6: criar um perfil do IAM para instâncias de contêiner
](#tutorial-gmsa-windows-step6)
+ [

## Etapa 7: criar um perfil de execução de tarefa personalizado
](#tutorial-gmsa-windows-step7)
+ [

## Etapa 8: criar um perfil de tarefa para o Amazon ECS Exec
](#tutorial-gmsa-windows-step8)
+ [

## Etapa 9: registrar uma definição de tarefa que usa gMSA sem domínio
](#tutorial-gmsa-windows-step9)
+ [

## Etapa 10: registrar uma instância de contêiner do Windows no cluster
](#tutorial-gmsa-windows-step10)
+ [

## Etapa 11: verificar a instância de contêiner
](#tutorial-gmsa-windows-step11)
+ [

## Etapa 12: executar uma tarefa do Windows
](#tutorial-gmsa-windows-step12)
+ [

## Etapa 13: verificar se o contêiner tem credenciais gMSA
](#tutorial-gmsa-windows-step13)
+ [

## Etapa 14: limpar
](#tutorial-gmsa-windows-step14)
+ [

## Depuração do gMSA sem domínio do Amazon ECS para contêineres Windows
](#tutorial-gmsa-windows-debugging)

## Pré-requisitos
<a name="tutorial-gmsa-windows-prerequisites"></a>

Este tutorial pressupõe que os seguintes pré-requisitos foram concluídos:
+ 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).
+  A versão mais recente da AWS CLI está instalada e configurada. Para obter mais informações sobre como instalar ou fazer upgrade da AWS CLI, consulte [Instalar a AWS Command Line Interface](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).
+ Você configurou um domínio do Active Directory com os recursos que deseja que seus contêineres acessem. O Amazon ECS oferece suporte às configurações a seguir:
  + Um Active Directory Directory Service. O Directory Service é um Active Directory gerenciado pela AWS e hospedado no Amazon EC2. Para obter mais informações, consulte [Conceitos básicos do Microsoft AD gerenciado pela AWS](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html) no *Guia de administração do AWS Directory Service*.
  + Um Active Directory on-premises. Você deve garantir que a instância de contêiner Linux do Amazon ECS possa se associar ao domínio. Para obter mais informações, consulte [AWS Direct Connect](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/aws-direct-connect-network-to-amazon.html).
+ Você tem uma VPC e sub-redes que podem resolver o nome de domínio do Active Directory.
+ Você escolhe entre **gMSA sem domínio** e **associar cada instância a um único domínio**. Ao usar gMSA sem domínio, a instância de contêiner não será associada ao domínio, outras aplicações na instância não podem usar as credenciais para acessar o domínio e as tarefas que associam domínios diferentes podem ser executadas na mesma instância.

  Em seguida, escolha o armazenamento de dados para o CredSpec e, opcionalmente, para as credenciais de usuário do Active Directory para o gMSA sem domínio.

  O Amazon ECS usa um arquivo de especificação de credenciais do Active Directory (CredSpec). Esse arquivo contém os metadados de gMSA usados para propagar o contexto da conta de gMSA para o contêiner. Você gera o arquivo CredSpec e o armazena em uma das opções de armazenamento do CredSpec na tabela a seguir, específica para o sistema operacional das instâncias de contêiner. Para usar o método sem domínio, uma seção opcional no arquivo CredSpec pode especificar credenciais em uma das opções de armazenamento de *domainless user credentials* na tabela a seguir, específica para o sistema operacional das instâncias de contêiner.    
<a name="gmsa-table"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonECS/latest/developerguide/tutorial-gmsa-windows.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 e configurar a conta gMSA nos Serviços de Domínio Active Directory (AD DS)
<a name="tutorial-gmsa-windows-step1"></a>

Crie e configure uma conta gMSA no domínio do Active Directory.

**nota**  
Esta etapa cria duas contas separadas: uma conta de serviço gerenciada pelo grupo (gMSA) que fornece a identidade para seus contêineres e uma conta de usuário comum que é usada para autenticação de domínio. Essas contas têm propósitos diferentes e devem ter nomes diferentes.

1. 

**Gerar uma chave raiz do Serviço de Distribuição de Chaves**
**nota**  
Se estiver usando o Directory Service, será possível ignorar esta etapa.

   A chave raiz do KDS e as permissões do gMSA são configuradas com seu Microsoft AD gerenciado pela AWS.

   Se você ainda não criou uma conta de serviço do gMSA em seu domínio, primeiro precisará gerar uma chave raiz do Serviço de Distribuição de Chaves (KDS). O KDS é responsável por criar, alternar e liberar a senha do gMSA para os hosts autorizados. Quando o `ccg.exe` precisa recuperar as credenciais do gMSA, ele entra em contato com o KDS para recuperar a senha atual.

   Para verificar se a chave raiz do KDS já foi criada, execute o cmdlet do PowerShell a seguir com privilégios de administrador de domínio em um controlador de domínio usando o módulo do `ActiveDirectory` do PowerShell. Para obter mais informações sobre o módulo, consulte [Módulo do ActiveDirectory](https://learn.microsoft.com/en-us/powershell/module/activedirectory/?view=windowsserver2022-ps) no site do Microsoft Learn.

   ```
   PS C:\> Get-KdsRootKey
   ```

   Se o comando retornar uma ID de chave, será possível ignorar o restante desta etapa. Caso contrário, crie a chave raiz do KDS executando o comando a seguir:

   ```
   PS C:\> Add-KdsRootKey -EffectiveImmediately
   ```

   Embora o argumento `EffectiveImmediately` para o comando implique que a chave entra em vigor imediatamente, é preciso esperar 10 horas antes que a chave raiz do KDS seja replicada e esteja disponível para uso em todos os controladores de domínio.

1. 

**Criar a conta gMSA**

   Para criar a conta gMSA e permitir que o `ccg.exe` recupere a senha do gMSA, execute os comandos a seguir do PowerShell em um Windows Server ou cliente com acesso ao domínio. Substitua `ExampleAccount` pelo nome que você deseja para sua conta gMSA e `example-domain` pelo nome de domínio do Active Directory (por exemplo, se seu domínio for `contoso.com`, use `contoso`).

   1. 

      ```
      PS C:\> Install-WindowsFeature RSAT-AD-PowerShell
      ```

   1. 

      ```
      PS C:\> New-ADGroup -Name "ExampleAccount Authorized Hosts" -SamAccountName "ExampleAccountHosts" -GroupScope DomainLocal
      ```

   1. 

      ```
      PS C:\> New-ADServiceAccount -Name "ExampleAccount" -DnsHostName "example-domain" -ServicePrincipalNames "host/ExampleAccount", "host/example-domain" -PrincipalsAllowedToRetrieveManagedPassword "ExampleAccountHosts"
      ```

   1. Crie um usuário com uma senha permanente que não expire. Essas credenciais são armazenadas no AWS Secrets Manager e usadas por cada tarefa para se associar ao domínio. Esta é uma conta de usuário separada da conta gMSA criada acima. Substitua `ExampleServiceUser` pelo nome que você deseja para essa conta de usuário do serviço.

      ```
      PS C:\> New-ADUser -Name "ExampleServiceUser" -AccountPassword (ConvertTo-SecureString -AsPlainText "Test123" -Force) -Enabled 1 -PasswordNeverExpires 1
      ```

   1. 

      ```
      PS C:\> Add-ADGroupMember -Identity "ExampleAccountHosts" -Members "ExampleServiceUser"
      ```

   1. Instale o módulo PowerShell para criar objetos do CredSpec no Active Directory e gere a saída de JSON do CredSpec.

      ```
      PS C:\> Install-PackageProvider -Name NuGet -Force
      ```

      ```
      PS C:\> Install-Module CredentialSpec
      ```

   1. 

      ```
      PS C:\> New-CredentialSpec -AccountName ExampleAccount
      ```

1. Copie a saída de JSON do comando anterior em um arquivo chamado `gmsa-cred-spec.json`. Esse é o arquivo CredSpec. Ele será usado na Etapa 3, [Etapa 3: modificar seu JSON do CredSpec para incluir informações do gMSA sem domínio](#tutorial-gmsa-windows-step3).

## Etapa 2: fazer upload de credenciais no Secrets Manager
<a name="tutorial-gmsa-windows-step2"></a>

Copie as credenciais do Active Directory em um sistema seguro de armazenamento de credenciais, para que cada tarefa as recupere. Esse é o método do gMSA sem domínio. Ao usar gMSA sem domínio, a instância de contêiner não será associada ao domínio, outras aplicações na instância não podem usar as credenciais para acessar o domínio e as tarefas que associam domínios diferentes podem ser executadas na mesma instância.

Esta etapa usa a AWS CLI. É possível executar esses comandos no AWS CloudShell no shell padrão, que é o `bash`.
+ Execute o comando AWS CLI a seguir e substitua o nome de usuário, a senha e o nome do domínio de acordo com o seu ambiente. Use o nome da conta do usuário do serviço (não o nome da conta gMSA) como o nome de usuário. Guarde o ARN do segredo para usar na próxima etapa, [Etapa 3: modificar seu JSON do CredSpec para incluir informações do gMSA sem domínio](#tutorial-gmsa-windows-step3)

  O comando a seguir usa caracteres de continuação de barra invertida que são usados pelo `sh` e por shells compatíveis. Esse comando não é compatível com o PowerShell. Você deve modificar o comando para usá-lo com o PowerShell.

  ```
  $ aws secretsmanager create-secret \
  --name gmsa-plugin-input \
  --description "Amazon ECS - gMSA Portable Identity." \
  --secret-string "{\"username\":\"ExampleServiceUser\",\"password\":\"Test123\",\"domainName\":\"contoso.com\"}"
  ```

## Etapa 3: modificar seu JSON do CredSpec para incluir informações do gMSA sem domínio
<a name="tutorial-gmsa-windows-step3"></a>

Antes de fazer o upload de CredSpec para uma das opções de armazenamento, adicione informações ao CredSpec com o ARN do segredo no Secrets Manager da etapa anterior. Para obter mais informações, consulte [Configuração adicional de especificações de credenciais para o caso de uso de host de contêiner não associado a domínio](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/manage-serviceaccounts#additional-credential-spec-configuration-for-non-domain-joined-container-host-use-case) no site do Microsoft Learn.

1. Adicione as informações a seguir ao arquivo CredSpec dentro do `ActiveDirectoryConfig`. Substitua o ARN pelo segredo no Secrets Manager da etapa anterior.

   Observe que o valor `PluginGUID` deve corresponder ao GUID no trecho de exemplo a seguir, e é obrigatório.

   ```
   "HostAccountConfig": {
         "PortableCcgVersion": "1",
         "PluginGUID": "{859E1386-BDB4-49E8-85C7-3070B13920E1}",
         "PluginInput": "{\"credentialArn\": \"arn:aws:secretsmanager:aws-region:111122223333:secret:gmsa-plugin-input\"}"
       }
   ```

   Você também pode usar um segredo no SSM Parameter Store usando o ARN neste formato: `\"arn:aws:ssm:aws-region:111122223333:parameter/gmsa-plugin-input\"`.

1. Depois de modificar o arquivo CredSpec, ele será semelhante à saída do exemplo a seguir:

   ```
   {
     "CmsPlugins": [
       "ActiveDirectory"
     ],
     "DomainJoinConfig": {
       "Sid": "S-1-5-21-4066351383-705263209-1606769140",
       "MachineAccountName": "ExampleAccount",
       "Guid": "ac822f13-583e-49f7-aa7b-284f9a8c97b6",
       "DnsTreeName": "example-domain",
       "DnsName": "example-domain",
       "NetBiosName": "example-domain"
     },
     "ActiveDirectoryConfig": {
       "GroupManagedServiceAccounts": [
         {
           "Name": "ExampleAccount",
           "Scope": "example-domain"
         },
         {
           "Name": "ExampleAccount",
           "Scope": "example-domain"
         }
       ],
       "HostAccountConfig": {
         "PortableCcgVersion": "1",
         "PluginGUID": "{859E1386-BDB4-49E8-85C7-3070B13920E1}",
         "PluginInput": "{\"credentialArn\": \"arn:aws:secretsmanager:aws-region:111122223333:secret:gmsa-plugin-input\"}"
       }
     }
   }
   ```

## Etapa 4: fazer upload do CredSpec no Amazon S3
<a name="tutorial-gmsa-windows-step4"></a>



Esta etapa usa a AWS CLI. É possível executar esses comandos no AWS CloudShell no shell padrão, que é o `bash`.

1. Copie o arquivo CredSpec para o computador ou ambiente em que você está executando os comandos da AWS CLI.

1. Execute o comando AWS CLI a seguir para fazer upload do CredSpec no Amazon S3. Substitua `MyBucket` pelo nome do bucket do Amazon S3. É possível armazenar o arquivo como um objeto em qualquer bucket e local, mas deve permitir o acesso a esse bucket e ao local na política que você anexa ao perfil de execução da tarefa.

   O comando a seguir usa caracteres de continuação de barra invertida que são usados pelo `sh` e por shells compatíveis. Esse comando não é compatível com o PowerShell. Você deve modificar o comando para usá-lo com o PowerShell.

   ```
   $ aws s3 cp gmsa-cred-spec.json \
   s3://MyBucket/ecs-domainless-gmsa-credspec
   ```

## Etapa 5: (opcional) criar um cluster do Amazon ECS
<a name="tutorial-gmsa-windows-step5"></a>

Por padrão, sua conta tem um cluster Amazon ECS chamado `default`. Esse cluster é usado por padrão na AWS CLI, nos SDKs e no CloudFormation. É possível usar clusters adicionais para agrupar e organizar tarefas e infraestrutura e atribuir padrões para algumas configurações.

É possível criar um cluster a partir do Console de gerenciamento da AWS, da AWS CLI, de SDKs ou do CloudFormation. As definições e a configuração no cluster não afetam o gMSA.

Esta etapa usa a AWS CLI. É possível executar esses comandos no AWS CloudShell no shell padrão, que é o `bash`.

```
$ aws ecs create-cluster --cluster-name windows-domainless-gmsa-cluster
```

**Importante**  
Caso você escolha criar seu o próprio cluster, você deverá especificar `--cluster clusterName` para cada comando que pretender usar com esse cluster.

## Etapa 6: criar um perfil do IAM para instâncias de contêiner
<a name="tutorial-gmsa-windows-step6"></a>

Uma *instância de contêiner* é um computador host para executar contêineres em tarefas do ECS, por exemplo, instâncias do Amazon EC2. Cada instância de contêiner se registra em um cluster do Amazon ECS. Para poder iniciar instâncias do Amazon EC2 e registrá-las em um cluster, você deve criar um perfil do IAM para suas instâncias de contêiner usarem.

Para criar o perfil da instância de contêiner, consulte [Função do IAM de instância de contêiner do Amazon ECS](instance_IAM_role.md). O `ecsInstanceRole` padrão tem permissões suficientes para concluir este tutorial.

## Etapa 7: criar um perfil de execução de tarefa personalizado
<a name="tutorial-gmsa-windows-step7"></a>

O Amazon ECS pode usar um perfil do IAM diferente para as permissões necessárias para iniciar cada tarefa, em vez do perfil da instância de contêiner. Esse perfil é chamado de *perfil de execução de tarefa*. Recomendamos criar um perfil de execução de tarefa apenas com as permissões necessárias para que o ECS execute a tarefa, também conhecidas como *permissões de privilégio mínimo*. Para obter mais informações sobre o princípio do privilégio mínimo, consulte [SEC03-BP02 Conceder acesso com privilégio mínimo](https://docs.aws.amazon.com/wellarchitected/latest/framework/sec_permissions_least_privileges.html) no *AWS Well-Architected Framework*.

1. Para criar um perfil de execução de tarefa, consulte [Criar a função de execução de tarefa do](task_execution_IAM_role.md#create-task-execution-role). As permissões padrão permitem que a instância de contêiner extraia imagens de contêiner do Amazon Elastic Container Registry e `stdout` e `stderr` de suas aplicações para serem registradas em log no Amazon CloudWatch Logs.

   Como o perfil precisa de permissões personalizadas para este tutorial, é possível atribuir ao perfil um nome diferente de `ecsTaskExecutionRole`. Este tutorial usa `ecsTaskExecutionRole` em etapas adicionais.

1. Adicione as permissões a seguir criando uma política personalizada, uma política em linha que só exista para esse perfil ou uma política que você possa reutilizar. Substitua o ARN para o `Resource` na primeira declaração pelo bucket do Amazon S3 e a localização, e o segundo `Resource` pelo ARN do segredo no Secrets Manager.

   Se você criptografar o segredo no Secrets Manager com uma chave personalizada, também deverá permitir `kms:Decrypt` para a chave.

   Se você usar o SSM Parameter Store em vez do Secrets Manager, deverá permitir `ssm:GetParameter` para o parâmetro, em vez de `secretsmanager:GetSecretValue`.

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "s3:GetObject"
               ],
               "Resource": "arn:aws:s3:::MyBucket/ecs-domainless-gmsa-credspec/gmsa-cred-spec.json"
           },
           {
               "Effect": "Allow",
               "Action": [
                   "secretsmanager:GetSecretValue"
               ],
               "Resource": "arn:aws:secretsmanager:us-east-1:111122223333:secret:gmsa-plugin-AbCdEf"
           }
       ]
   }
   ```

------

## Etapa 8: criar um perfil de tarefa para o Amazon ECS Exec
<a name="tutorial-gmsa-windows-step8"></a>

Este tutorial usa o Amazon ECS Exec para verificar a funcionalidade executando um comando dentro de uma tarefa em execução. Para usar o ECS Exec, o serviço ou a tarefa deve ativar o ECS Exec, e o perfil da tarefa (mas não o perfil de execução da tarefa) deve ter permissões `ssmmessages`. Para saber mais sobre a política do IAM necessária, consulte [Permissões do ECS Exec](task-iam-roles.md#ecs-exec-required-iam-permissions).

Esta etapa usa a AWS CLI. É possível executar esses comandos no AWS CloudShell no shell padrão, que é o `bash`.

Para criar um perfil de tarefa usando a AWS CLI, siga estas etapas.

1. Crie um arquivo chamado `ecs-tasks-trust-policy.json` com o conteúdo a seguir:

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Principal": {
                   "Service": "ecs-tasks.amazonaws.com"
               },
               "Action": "sts:AssumeRole"
           }
       ]
   }
   ```

------

1. Criar um perfil do IAM. É possível substituir o nome `ecs-exec-demo-task-role`, mas mantenha-o nas etapas a seguir.

   O comando a seguir usa caracteres de continuação de barra invertida que são usados pelo `sh` e por shells compatíveis. Esse comando não é compatível com o PowerShell. Você deve modificar o comando para usá-lo com o PowerShell.

   ```
   $ aws iam create-role --role-name ecs-exec-demo-task-role \
   --assume-role-policy-document file://ecs-tasks-trust-policy.json
   ```

   É possível excluir o arquivo `ecs-tasks-trust-policy.json`.

1. Crie um arquivo chamado `ecs-exec-demo-task-role-policy.json` com o conteúdo a seguir:

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "ssmmessages:CreateControlChannel",
                   "ssmmessages:CreateDataChannel",
                   "ssmmessages:OpenControlChannel",
                   "ssmmessages:OpenDataChannel"
               ],
               "Resource": "*"
           }
       ]
   }
   ```

------

1. Crie uma política do IAM e anexe-a ao perfil da etapa anterior.

   O comando a seguir usa caracteres de continuação de barra invertida que são usados pelo `sh` e por shells compatíveis. Esse comando não é compatível com o PowerShell. Você deve modificar o comando para usá-lo com o PowerShell.

   ```
   $ aws iam put-role-policy \
       --role-name ecs-exec-demo-task-role \
       --policy-name ecs-exec-demo-task-role-policy \
       --policy-document file://ecs-exec-demo-task-role-policy.json
   ```

   É possível excluir o arquivo `ecs-exec-demo-task-role-policy.json`.

## Etapa 9: registrar uma definição de tarefa que usa gMSA sem domínio
<a name="tutorial-gmsa-windows-step9"></a>



Esta etapa usa a AWS CLI. É possível executar esses comandos no AWS CloudShell no shell padrão, que é o `bash`.

1. Crie um arquivo chamado `windows-gmsa-domainless-task-def.json` com o conteúdo a seguir:

   ```
   {
     "family": "windows-gmsa-domainless-task",
     "containerDefinitions": [
       {
         "name": "windows_sample_app",
         "image": "mcr.microsoft.com/windows/servercore/iis",
         "cpu": 1024,
         "memory": 1024,
         "essential": true,
         "credentialSpecs": [
                   "credentialspecdomainless:arn:aws:s3:::ecs-domainless-gmsa-credspec/gmsa-cred-spec.json"
         ],
         "entryPoint": [
           "powershell",
           "-Command"
         ],
         "command": [
           "New-Item -Path C:\\inetpub\\wwwroot\\index.html -ItemType file -Value '<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>' -Force ; C:\\ServiceMonitor.exe w3svc"
         ],
         "portMappings": [
           {
             "protocol": "tcp",
             "containerPort": 80,
             "hostPort": 8080
           }
         ]
       }
     ],
     "taskRoleArn": "arn:aws:iam::111122223333:role/ecs-exec-demo-task-role",
     "executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole"
   }
   ```

1. Registre a definição de tarefa executando o comando a seguir.

   O comando a seguir usa caracteres de continuação de barra invertida que são usados pelo `sh` e por shells compatíveis. Esse comando não é compatível com o PowerShell. Você deve modificar o comando para usá-lo com o PowerShell.

   ```
   $ aws ecs register-task-definition \
   --cli-input-json file://windows-gmsa-domainless-task-def.json
   ```

## Etapa 10: registrar uma instância de contêiner do Windows no cluster
<a name="tutorial-gmsa-windows-step10"></a>

Inicie uma instância de Windows do Amazon EC2 e execute o agente de contêiner do ECS para registrá-la como uma instância de contêiner no cluster. O ECS executa tarefas nas instâncias de contêiner registradas no cluster em que as tarefas são iniciadas.

1. Para iniciar uma instância de Windows do Amazon EC2 que esteja configurada para o Amazon ECS no Console de gerenciamento da AWS, consulte [Iniciar uma instância de contêiner do Windows do Amazon ECS](launch_window-container_instance.md). Pare na etapa de *dados do usuário*.

1. Em gMSA, os dados do usuário devem definir a variável de ambiente `ECS_GMSA_SUPPORTED` antes de iniciar o agente de contêiner do ECS.

   Para o ECS Exec, o agente deve começar com o argumento `-EnableTaskIAMRole`.

   Para proteger o perfil do IAM da instância impedindo que as tarefas cheguem ao serviço da Web IMDS do EC2 para recuperar as credenciais do perfil, adicione o argumento `-AwsvpcBlockIMDS`. Isso se aplica somente às tarefas que usem o modo de rede `awsvpc`.

   ```
   <powershell>
   [Environment]::SetEnvironmentVariable("ECS_GMSA_SUPPORTED", $TRUE, "Machine")
   Import-Module ECSTools
   Initialize-ECSAgent -Cluster windows-domainless-gmsa-cluster -EnableTaskIAMRole -AwsvpcBlockIMDS
   </powershell>
   ```

1. Revise um resumo da configuração da instância no painel **Summary** (Resumo) e, quando você estiver pronto, escolha **Launch instance** (Iniciar instância).

## Etapa 11: verificar a instância de contêiner
<a name="tutorial-gmsa-windows-step11"></a>

É possível verificar se há uma instância de contêiner no cluster usando o Console de gerenciamento da AWS. No entanto, o gMSA precisa de recursos adicionais indicados como *atributos*. Esses atributos não são visíveis no Console de gerenciamento da AWS, portanto, este tutorial usa o AWS CLI.

Esta etapa usa a AWS CLI. É possível executar esses comandos no AWS CloudShell no shell padrão, que é o `bash`.

1. Listar as instâncias de contêiner no cluster. As instâncias de contêiner têm um ID diferente do ID da instância do EC2.

   ```
   $ aws ecs list-container-instances
   ```

   Resultado:

   ```
   {
       "containerInstanceArns": [
           "arn:aws:ecs:aws-region:111122223333:container-instance/default/MyContainerInstanceID"
       ]
   }
   ```

   Por exemplo, `526bd5d0ced448a788768334e79010fd` é um ID de instância de contêiner válido.

1. Use o ID da instância de contêiner da etapa anterior para obter os detalhes da instância de contêiner. Substitua `MyContainerInstanceID` pelo ID.

   O comando a seguir usa caracteres de continuação de barra invertida que são usados pelo `sh` e por shells compatíveis. Esse comando não é compatível com o PowerShell. Você deve modificar o comando para usá-lo com o PowerShell.

   ```
   $ aws ecs describe-container-instances \
        ----container-instances MyContainerInstanceID
   ```

   Observe que a saída é muito longa.

1. Verifique se a lista `attributes` tem um objeto com a chave chamada `name` e um valor de `ecs.capability.gmsa-domainless`. Veja a seguir um exemplo do objeto.

   Resultado:

   ```
   {
       "name": "ecs.capability.gmsa-domainless"
   }
   ```

## Etapa 12: executar uma tarefa do Windows
<a name="tutorial-gmsa-windows-step12"></a>

Execute uma tarefa do Amazon ECS. Se houver apenas uma instância de contêiner no cluster, será possível usar `run-task`. Se houver muitas instâncias de contêiner diferentes, talvez seja mais fácil usar `start-task` e especificar o ID da instância de contêiner para executar a tarefa do que adicionar restrições de posicionamento à definição da tarefa para controlar em que tipo de instância de contêiner executar essa tarefa.

Esta etapa usa a AWS CLI. É possível executar esses comandos no AWS CloudShell no shell padrão, que é o `bash`.

1. 

   O comando a seguir usa caracteres de continuação de barra invertida que são usados pelo `sh` e por shells compatíveis. Esse comando não é compatível com o PowerShell. Você deve modificar o comando para usá-lo com o PowerShell.

   ```
   aws ecs run-task --task-definition windows-gmsa-domainless-task \
       --enable-execute-command --cluster windows-domainless-gmsa-cluster
   ```

   Anote o ID da tarefa retornado pelo comando.

1. Execute o comando a seguir para verificar se a tarefa foi iniciada. Esse comando espera e não retorna o prompt do shell até que a tarefa seja iniciada. Substitua `MyTaskID` pelo ID da tarefa da etapa anterior.

   ```
   $ aws ecs wait tasks-running --task MyTaskID
   ```

## Etapa 13: verificar se o contêiner tem credenciais gMSA
<a name="tutorial-gmsa-windows-step13"></a>

Verifique se o contêiner na tarefa tem um token Kerberos. gMSA 

Esta etapa usa a AWS CLI. É possível executar esses comandos no AWS CloudShell no shell padrão, que é o `bash`.

1. 

   O comando a seguir usa caracteres de continuação de barra invertida que são usados pelo `sh` e por shells compatíveis. Esse comando não é compatível com o PowerShell. Você deve modificar o comando para usá-lo com o PowerShell.

   ```
   $ aws ecs execute-command \
   --task MyTaskID \
   --container windows_sample_app \
   --interactive \
   --command powershell.exe
   ```

   A saída será um prompt do PowerShell.

1. Execute o comando a seguir no terminal do PowerShell dentro do contêiner.

   ```
   PS C:\> klist get ExampleAccount$
   ```

   Na saída, observe que `Principal` é o que você criou anteriormente.

## Etapa 14: limpar
<a name="tutorial-gmsa-windows-step14"></a>

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

Esta etapa usa a AWS CLI. É possível executar esses comandos no AWS CloudShell no shell padrão, que é o `bash`.

1. Interrompa a tarefa. Substitua `MyTaskID` pelo ID da tarefa da etapa 12, [Etapa 12: executar uma tarefa do Windows](#tutorial-gmsa-windows-step12).

   ```
   $ aws ecs stop-task --task MyTaskID
   ```

1. Encerre a instância do Amazon EC2. Depois disso, a instância de contêiner no cluster será excluída automaticamente após uma hora.

   É possível encontrar e encerrar a instância usando o console do Amazon EC2. É possível executar o comando a seguir: Para executar o comando, encontre o ID da instância do EC2 na saída do comando `aws ecs describe-container-instances` da etapa 1, [Etapa 11: verificar a instância de contêiner](#tutorial-gmsa-windows-step11). i-10a64379 é um exemplo de ID de instância do EC2.

   ```
   $ aws ec2 terminate-instances --instance-ids MyInstanceID
   ```

1. Exclua o arquivo CredSpec no Amazon S3. Substitua `MyBucket` pelo nome do bucket do Amazon S3.

   ```
   $ aws s3api delete-object --bucket MyBucket --key ecs-domainless-gmsa-credspec/gmsa-cred-spec.json
   ```

1. Exclua o segredo no Secrets Manager. Se você usou o SSM Parameter Store em vez disso, exclua o parâmetro.

   O comando a seguir usa caracteres de continuação de barra invertida que são usados pelo `sh` e por shells compatíveis. Esse comando não é compatível com o PowerShell. Você deve modificar o comando para usá-lo com o PowerShell.

   ```
   $ aws secretsmanager delete-secret --secret-id gmsa-plugin-input \
        --force-delete-without-recovery
   ```

1. Cancele o registro e exclua a definição de tarefa. Ao cancelar o registro da definição da tarefa, você a marca como inativa para que não possa ser usada para iniciar novas tarefas. Em seguida, é possível excluir a definição da tarefa.

   1. Cancele o registro da definição da tarefa especificando a versão. O ECS cria automaticamente versões das definições de tarefas, que são numeradas a partir de 1. Você faz referência às versões no mesmo formato dos rótulos nas imagens do contêiner, como `:1`.

      ```
      $ aws ecs deregister-task-definition --task-definition windows-gmsa-domainless-task:1
      ```

   1. Exclua a definição da tarefa.

      ```
      $ aws ecs delete-task-definitions --task-definition windows-gmsa-domainless-task:1
      ```

1. (Opcional) Exclua o cluster do ECS se você tiver criado um cluster.

   ```
   $ aws ecs delete-cluster --cluster windows-domainless-gmsa-cluster
   ```

## Depuração do gMSA sem domínio do Amazon ECS para contêineres Windows
<a name="tutorial-gmsa-windows-debugging"></a>



Status da tarefa do Amazon ECS  
O ECS tenta iniciar uma tarefa exatamente uma vez. Qualquer tarefa que tenha um problema é interrompida e definida para o status `STOPPED`. Há dois tipos comuns de problemas com tarefas. Primeiro, tarefas que não puderam ser iniciadas. Segundo, tarefas em que a aplicação foi interrompida dentro de um dos contêineres. No Console de gerenciamento da AWS, observe o campo **Motivo da parada** para obter o motivo pelo qual a tarefa foi interrompida. Na AWS CLI, descreva a tarefa e veja o `stoppedReason`. Para ver as etapas em Console de gerenciamento da AWS e AWS CLI, consulte [Visualizar erros de tarefa interrompida do Amazon ECS](stopped-task-errors.md).

Eventos do Windows  
Os eventos do Windows para gMSA em contêineres são registrados em log no arquivo de `Microsoft-Windows-Containers-CCG` log e podem ser encontrados no Visualizador de Eventos na seção Aplicações e Serviços em `Logs\Microsoft\Windows\Containers-CCG\Admin`. Para obter mais dicas de depuração, consulte [Solucionar problemas de GMSAs para contêineres Windows](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/gmsa-troubleshooting#non-domain-joined-container-hosts-use-event-logs-to-identify-configuration-issues) no site do Microsoft Learn.

Plug-in gMSA do agente do ECS  
O registro em log do plug-in gMSA para o agente do ECS na instância do contêiner do Windows está no diretório a seguir, `C:/ProgramData/Amazon/gmsa-plugin/`. Examine esse registro para ver se as credenciais do usuário sem domínio foram baixadas do local de armazenamento, como o Secrets Manager, e se o formato da credencial foi lido corretamente.

# Saiba como usar gMSAs para contêineres do Windows do Amazon EC2 para o Amazon ECS
<a name="windows-gmsa"></a>

O Amazon ECS é compatível com a autenticação do Active Directory para contêineres do Windows por meio de um tipo especial de conta de serviço denominado *Conta de serviço gerenciada pelo grupo* (gMSA).

Aplicativos de rede baseados no Windows, como os aplicativos.NET, geralmente usam o Active Directory para facilitar o gerenciamento de autenticação e autorização entre usuários e serviços. Os desenvolvedores geralmente projetam seus aplicativos para se integrarem ao Active Directory e serem executados em servidores associados ao domínio para essa finalidade. Como os contêineres do Windows não podem ser associados ao domínio, os contêineres do Windows devem ser configurados para ser executado com o gMSA.

Um contêiner do Windows em execução com a gMSA depende da instância do Amazon EC2 do host para recuperar as credenciais da gMSA do controlador de domínio do Active Directory e fornecê-las à instância de contêiner. Para obter mais informações, consulte [Criar gMSAs para contêineres do Windows](https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/manage-serviceaccounts).

**nota**  
Não há suporte para esse recurso nos contêineres do Windows no Fargate.

**Topics**
+ [

## Considerações
](#windows-gmsa-considerations)
+ [

## Pré-requisitos
](#windows-gmsa-prerequisites)
+ [

## Configuração do gMSA para contêineres do Windows no Amazon ECS
](#windows-gmsa-setup)

## Considerações
<a name="windows-gmsa-considerations"></a>

Ao usar gMSAs para contêineres do Windows, deve-se levar em consideração o seguinte:
+ Ao usar a AMI do Windows Server 2016 Full otimizada para Amazon ECS para as instâncias de contêiner, o nome do host do contêiner deve ser o mesmo que o nome da conta gMSA definido no arquivo de especificação de credenciais. Para especificar um nome de host para um contêiner, use o parâmetro de definição de contêiner `hostname`. Para obter mais informações, consulte [Configurações de rede](task_definition_parameters.md#container_definition_network).
+ Você escolhe entre **gMSA sem domínio** e **associar cada instância a um único domínio**. Ao usar gMSA sem domínio, a instância de contêiner não será associada ao domínio, outras aplicações na instância não podem usar as credenciais para acessar o domínio e as tarefas que associam domínios diferentes podem ser executadas na mesma instância.

  Em seguida, escolha o armazenamento de dados para o CredSpec e, opcionalmente, para as credenciais de usuário do Active Directory para o gMSA sem domínio.

  O Amazon ECS usa um arquivo de especificação de credenciais do Active Directory (CredSpec). Esse arquivo contém os metadados de gMSA usados para propagar o contexto da conta de gMSA para o contêiner. Você gera o arquivo CredSpec e o armazena em uma das opções de armazenamento do CredSpec na tabela a seguir, específica para o sistema operacional das instâncias de contêiner. Para usar o método sem domínio, uma seção opcional no arquivo CredSpec pode especificar credenciais em uma das opções de armazenamento de *domainless user credentials* na tabela a seguir, específica para o sistema operacional das instâncias de contêiner.    
<a name="gmsa-table"></a>[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonECS/latest/developerguide/windows-gmsa.html)

## Pré-requisitos
<a name="windows-gmsa-prerequisites"></a>

Antes de usar o recurso gMSA para contêineres do Windows com o Amazon ECS, verifique se você concluiu o seguinte:
+ Você configurou um domínio do Active Directory com os recursos que deseja que seus contêineres acessem. O Amazon ECS oferece suporte às configurações a seguir:
  + Um Active Directory Directory Service. O Directory Service é um Active Directory gerenciado pela AWS e hospedado no Amazon EC2. Para obter mais informações, consulte [Conceitos básicos do Microsoft AD gerenciado pela AWS](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html) no *Guia de administração do AWS Directory Service*.
  + Um Active Directory on-premises. Você deve garantir que a instância de contêiner Linux do Amazon ECS possa se associar ao domínio. Para obter mais informações, consulte [AWS Direct Connect](https://docs.aws.amazon.com/whitepapers/latest/aws-vpc-connectivity-options/aws-direct-connect-network-to-amazon.html).
+ Você tem uma conta de gMSA existente no Active Directory. Para obter mais informações, consulte [Criar gMSAs para contêineres do Windows](https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/manage-serviceaccounts).
+ **Você escolheu usar o *gMSA sem domínio* ou a instância de contêiner do Windows do Amazon ECS que hospeda a tarefa do Amazon ECS deve ser um *domínio associado* ao Active Directory e fazer parte do grupo de segurança do Active Directory que tem acesso à conta gMSA.**

  Ao usar gMSA sem domínio, a instância de contêiner não será associada ao domínio, outras aplicações na instância não podem usar as credenciais para acessar o domínio e as tarefas que associam domínios diferentes podem ser executadas na mesma instância.
+ Você adicionou as permissões necessárias do IAM. As permissões necessárias dependem dos métodos escolhidos para as credenciais iniciais e para armazenar a especificação da credencial:
  + Se você usa o *gMSA sem domínio* para as credenciais iniciais, as permissões do IAM para o AWS Secrets Manager são necessárias no perfil da instância do Amazon EC2.
  + Se você armazenar a especificação da credencial no SSM Parameter Store, as permissões do IAM para o Amazon EC2 Systems Manager Parameter Store serão necessárias no perfil de execução da tarefa.
  + Se você armazenar a especificação da credencial no Amazon S3, as permissões do IAM para o Amazon Simple Storage Service serão necessárias no perfil de execução da tarefa.

## Configuração do gMSA para contêineres do Windows no Amazon ECS
<a name="windows-gmsa-setup"></a>

Para configurar o gMSA para contêineres de Windows no Amazon ECS, siga o tutorial completo que inclui a configuração dos pré-requisitos [Usar contêineres do Windows no Amazon ECS com gMSA sem domínio usando a AWS CLI](tutorial-gmsa-windows.md).

As seções a seguir abordam a configuração do CredSpec em detalhes.

**Topics**
+ [

### Exemplo CredSpec
](#windows-gmsa-example)
+ [

### Configuração de gMSA sem domínio
](#windows-gmsa-domainless)
+ [

### Referência a um arquivo de especificações de credenciais em uma definição de tarefa
](#windows-gmsa-credentialspec)

### Exemplo CredSpec
<a name="windows-gmsa-example"></a>

O Amazon ECS usa um arquivo de especificação de credenciais que contém os metadados de gMSA usados para propagar o contexto da conta gMSA para o contêiner do Windows. É possível gerar o arquivo de especificação de credenciais e mencioná-lo no campo `credentialSpec` em sua definição de tarefa. O arquivo de especificação de credenciais não contém nenhum segredo.

Veja a seguir um exemplo de arquivo de especificação de credenciais:

```
{
    "CmsPlugins": [
        "ActiveDirectory"
    ],
    "DomainJoinConfig": {
        "Sid": "S-1-5-21-2554468230-2647958158-2204241789",
        "MachineAccountName": "WebApp01",
        "Guid": "8665abd4-e947-4dd0-9a51-f8254943c90b",
        "DnsTreeName": "contoso.com",
        "DnsName": "contoso.com",
        "NetBiosName": "contoso"
    },
    "ActiveDirectoryConfig": {
        "GroupManagedServiceAccounts": [
            {
                "Name": "WebApp01",
                "Scope": "contoso.com"
            }
        ]
    }
}
```

### Configuração de gMSA sem domínio
<a name="windows-gmsa-domainless"></a>

Recomendamos a utilização de gMSA sem domínio em vez de associar as instâncias do contêiner a um único domínio. Ao usar gMSA sem domínio, a instância de contêiner não será associada ao domínio, outras aplicações na instância não podem usar as credenciais para acessar o domínio e as tarefas que associam domínios diferentes podem ser executadas na mesma instância.

1. Antes de fazer o upload de CredSpec para uma das opções de armazenamento, adicione informações ao CredSpec com o ARN do segredo no Secrets Manager ou no SSM Parameter Store. Para obter mais informações, consulte [Configuração adicional de especificações de credenciais para o caso de uso de host de contêiner não associado a domínio](https://learn.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/manage-serviceaccounts#additional-credential-spec-configuration-for-non-domain-joined-container-host-use-case) no site do Microsoft Learn.

**Formato de credencial de gMSA sem domínio**  
A seguir está o formato JSON para as credenciais de gMSA sem domínio do seu Active Directory. Armazene as credenciais no Secrets Manager ou no SSM Parameter Store.

   ```
   {
       "username":"WebApp01",
       "password":"Test123!",
       "domainName":"contoso.com"
   }
   ```

1. Adicione as informações a seguir ao arquivo CredSpec dentro do `ActiveDirectoryConfig`. Substitua o ARN pelo segredo no Secrets Manager ou no SSM Parameter Store.

   Observe que o valor `PluginGUID` deve corresponder ao GUID no trecho de exemplo a seguir, e é obrigatório.

   ```
       "HostAccountConfig": {
           "PortableCcgVersion": "1",
           "PluginGUID": "{859E1386-BDB4-49E8-85C7-3070B13920E1}",
           "PluginInput": "{\"credentialArn\": \"arn:aws:secretsmanager:aws-region:111122223333:secret:gmsa-plugin-input\"}"
       }
   ```

   Você também pode usar um segredo no SSM Parameter Store usando o ARN neste formato: `\"arn:aws:ssm:aws-region:111122223333:parameter/gmsa-plugin-input\"`.

1. Depois de modificar o arquivo CredSpec, ele será semelhante à saída do exemplo a seguir:

   ```
   {
     "CmsPlugins": [
       "ActiveDirectory"
     ],
     "DomainJoinConfig": {
       "Sid": "S-1-5-21-4066351383-705263209-1606769140",
       "MachineAccountName": "WebApp01",
       "Guid": "ac822f13-583e-49f7-aa7b-284f9a8c97b6",
       "DnsTreeName": "contoso",
       "DnsName": "contoso",
       "NetBiosName": "contoso"
     },
     "ActiveDirectoryConfig": {
       "GroupManagedServiceAccounts": [
         {
           "Name": "WebApp01",
           "Scope": "contoso"
         },
         {
           "Name": "WebApp01",
           "Scope": "contoso"
         }
       ],
       "HostAccountConfig": {
         "PortableCcgVersion": "1",
         "PluginGUID": "{859E1386-BDB4-49E8-85C7-3070B13920E1}",
         "PluginInput": "{\"credentialArn\": \"arn:aws:secretsmanager:aws-region:111122223333:secret:gmsa-plugin-input\"}"
       }
     }
   }
   ```

### Referência a um arquivo de especificações de credenciais em uma definição de tarefa
<a name="windows-gmsa-credentialspec"></a>

O Amazon ECS é compatível com as seguintes maneiras de referenciar o caminho do arquivo no campo `credentialSpecs` de definição da tarefa. Para cada uma dessas opções, é possível fornecer `credentialspec:` ou `domainlesscredentialspec:`, dependendo se você estiver associando as instâncias de contêiner a um domínio único ou usando gMSA sem domínio, respectivamente.

#### Bucket do Amazon S3
<a name="gmsa-credspec-s3"></a>

Adicione a especificação de credencial a um bucket do Amazon S3 e, em seguida, referencie o nome do recurso da Amazon (ARN) do bucket do Amazon S3 no campo `credentialSpecs` da definição de tarefa.

```
{
    "family": "",
    "executionRoleArn": "",
    "containerDefinitions": [
        {
            "name": "",
            ...
            "credentialSpecs": [
                "credentialspecdomainless:arn:aws:s3:::${BucketName}/${ObjectName}"
            ],
            ...
        }
    ],
    ...
}
```

Você também deve adicionar as seguintes permissões como uma política alinhada com a função do IAM de execução de tarefas do Amazon ECS para que suas tarefas tenham acesso ao bucket do Amazon S3.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Sid": "VisualEditor",
            "Effect": "Allow",
            "Action": [
                "s3:Get*",
                "s3:List*"
            ],
            "Resource": [
                "arn:aws:s3:::{bucket_name}",
                "arn:aws:s3:::{bucket_name}/{object}"
            ]
        }
    ]
}
```

------

#### Parâmetro do Parameter Store do SSM
<a name="gmsa-credspec-ssm"></a>

Adicione a especificação de credencial a um parâmetro do Parameter Store do SSM e, em seguida, referencie o nome do recurso da Amazon (ARN) do parâmetro do Parameter Store do SSM no campo `credentialSpecs` da definição de tarefa.

```
{
    "family": "",
    "executionRoleArn": "",
    "containerDefinitions": [
        {
            "name": "",
            ...
            "credentialSpecs": [
                "credentialspecdomainless:arn:aws:ssm:region:111122223333:parameter/parameter_name"
            ],
            ...
        }
    ],
    ...
}
```

Você também deve adicionar as seguintes permissões como uma política alinhada com a função do IAM de execução de tarefas do Amazon ECS para que suas tarefas tenham acesso ao parâmetro do Parameter Store do SSM.

------
#### [ JSON ]

****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ssm:GetParameters"
            ],
            "Resource": "arn:aws:ssm:*:111122223333:parameter/example*"
        }
    ]
}
```

------

#### Arquivo local
<a name="gmsa-credspec-file"></a>

Com os detalhes da especificação de credenciais em um arquivo local, faça referência ao caminho do arquivo no campo `credentialSpecs` da definição da tarefa. O caminho do arquivo referenciado deve ser relativo ao diretório `C:\ProgramData\Docker\CredentialSpecs` e usar a barra invertida ('\$1') como separador do caminho do arquivo.

```
{
    "family": "",
    "executionRoleArn": "",
    "containerDefinitions": [
        {
            "name": "",
            ...
            "credentialSpecs": [
                "credentialspec:file://CredentialSpecDir\CredentialSpecFile.json"
            ],
            ...
        }
    ],
    ...
}
```

# Uso do EC2 Image Builder para criar AMIs personalizadas otimizadas para Amazon ECS
<a name="image-builder-tutorial"></a>

A AWS recomenda usar as AMIs otimizadas para Amazon ECS por serem pré-configuradas com os requisitos e recomendações para executar as workloads de contêiner. Pode haver momentos em que você precise personalizar a AMI para adicionar software. Você pode usar o EC2 Image Builder para criar, gerenciar e implantar suas imagens de servidor. Você retém a propriedade das imagens personalizadas criadas na sua conta. Você pode usar os pipelines do EC2 Image Builder para automatizar atualizações e patches do sistema das imagens ou utilizar um comando autônomo para criar uma imagem com seus recursos de configuração definidos.

Você cria uma fórmula para a imagem. A fórmula inclui uma imagem pai e quaisquer componentes adicionais. Você também cria um pipeline que distribui sua AMI personalizada.

Você cria uma fórmula para a imagem. Uma fórmula de imagem do Image Builder é um documento que define a imagem de base e os componentes que são aplicados à imagem de base para produzir a configuração desejada para a imagem AMI de saída. Você também cria um pipeline que distribui sua AMI personalizada. Para obter mais informações, consulte [How EC2 Image Builder works](https://docs.aws.amazon.com/imagebuilder/latest/userguide/how-image-builder-works.html) no *Guia do usuário do EC2 Image Builder*.

Recomendamos usar uma das seguintes AMIs otimizadas para o Amazon ECS como “imagem pai” no EC2 Image Builder:
+ Linux
  + AL2023 x86 otimizado para o Amazon ECS
  + AMI do Amazon Linux 2023 (arm64) otimizada para Amazon ECS
  + AMI do kernel 5 do Amazon Linux 2 otimizada para o Amazon ECS
  + AMI do Amazon Linux 2 x86 otimizada para o Amazon ECS
+ Windows
  + Windows 2022 Full x86 otimizado para o Amazon ECS
  + Windows 2022 Core x86 otimizado para o Amazon ECS
  + Windows 2019 Full x86 otimizado para o Amazon ECS
  + Windows 2019 Core x86 otimizado para o Amazon ECS
  + Windows 2016 Full x86 otimizado para o Amazon ECS

Também recomendamos selecionar “Usar a versão mais recente do sistema operacional disponível”. O pipeline usará o versionamento semântico para a imagem pai, o que ajuda a detectar as atualizações de dependência em trabalhos programados automaticamente. Para obter mais informações, consulte [Semantic versioning](https://docs.aws.amazon.com/imagebuilder/latest/userguide/ibhow-semantic-versioning.html) no *Guia do usuário do EC2 Image Builder*.

A AWS atualiza regularmente as imagens de AMI otimizadas para Amazon ECS com patches de segurança e a nova versão do agente de contêiner. Ao usar um ID de AMI como imagem pai na fórmula de imagem, você precisa verificar regularmente se há atualizações na imagem pai. Se houver atualizações, é preciso criar uma versão da fórmula com a AMI atualizada. Isso garante que suas imagens personalizadas incorporem a versão mais recente da imagem pai. Para obter informações sobre como criar um fluxo de trabalho para atualizar automaticamente as instâncias do EC2 no cluster do Amazon ECS com as AMIs recém-criadas, consulte [How to create an AMI hardening pipeline and automate updates to your ECS instance fleet](https://aws.amazon.com/blogs/security/how-to-create-an-ami-hardening-pipeline-and-automate-updates-to-your-ecs-instance-fleet/).

Você também pode especificar o nome do recurso da Amazon (ARN) de uma imagem pai publicada por meio de um pipeline gerenciado do EC2 Image Builder. A Amazon publica rotineiramente imagens de AMI otimizadas para Amazon ECS por meio de pipelines gerenciados. Essas imagens são acessíveis ao público. Você deve ter as permissões corretas para acessar a imagem. Ao usar um ARN de imagem em vez de uma AMI na fórmula do Image Builder, seu pipeline usa automaticamente a versão mais recente da imagem pai sempre que é executada. Essa abordagem elimina a necessidade de criar manualmente versões da fórmula para cada atualização. 

## Limpar a AMI otimizada para o Amazon ECS
<a name="cleanup-ecs-optimized-ami"></a>

Ao usar uma AMI otimizada para o Amazon ECS como imagem principal, você deve limpar a imagem para evitar problemas transitórios. A AMI otimizada para o Amazon ECS é pré-configurada para que o agente do Amazon ECS seja iniciado automaticamente e se registre como instância de contêiner no Amazon ECS. Usá-la como imagem base sem a limpeza correta pode causar problemas na sua AMI personalizada.

Para limpar a imagem para uso futuro, crie um componente que execute os seguintes comandos para interromper o pacote ecs-init e os processos do Docker:

```
sudo systemctl stop ecs
sudo systemctl stop docker
```

Remova todos os arquivos de log da instância atual para evitar preservá-los ao salvar a imagem. Use o script de exemplo em [Práticas recomendadas de segurança do EC2 Image Builder](https://docs.aws.amazon.com/imagebuilder/latest/userguide/security-best-practices.html) para limpar os vários arquivos da instância.

Para limpar dados específicos do Amazon ECS, execute os seguintes comandos:

```
sudo rm -rf /var/log/ecs/*
sudo rm /var/lib/ecs/data/agent.db
```

Para obter mais informações sobre a criação de AMIs personalizadas otimizadas para o Amazon ECS, consulte [Como criar uma AMI personalizada usando uma AMI otimizada para o Amazon ECS?](https://forums.aws.amazon.com/knowledge-center/ecs-create-custom-amis/) no Centro de Conhecimento da AWS.

## Uso do ARN de imagem com a infraestrutura como código (IaC)
<a name="infrastructure-as-code-arn"></a>

Você pode configurar a fórmula usando o console do EC2 Image Builder, a infraestrutura como código (por exemplo, o CloudFormation) ou o AWS SDK. Ao especificar uma imagem pai na fórmula, você pode especificar um ID de AMI do EC2, um ARN de imagem do Image Builder, um ID de produto do AWS Marketplace ou uma imagem de contêiner. A AWS disponibiliza publicamente IDs de AMI e ARNs de imagem do Image Builder de AMIs otimizadas para Amazon ECS. Este é o formato de ARN da imagem:

```
arn:${Partition}:imagebuilder:${Region}:${Account}:image/${ImageName}/${ImageVersion}
```

A `ImageVersion` tem o formato a seguir. Substitua *principal*, *secundário* e *patch* pelos valores mais recentes.

```
<major>.<minor>.<patch>
```

Você pode substituir `major`, `minor` e `patch` por valores específicos ou usar o ARN sem versão de uma imagem, para que o pipeline permaneça atualizado com a versão mais recente da imagem pai. Um ARN sem versão usa o formato curinga ‘x.x.x’ para representar a versão da imagem. Essa abordagem permite que o serviço Image Builder seja resolvido automaticamente para a versão mais recente da imagem. Usar o ARN sem versão garante que sua referência sempre direcione para a imagem mais recente disponível, simplificando o processo de manutenção de imagens atualizadas na implantação. Ao criar uma fórmula com o console, o EC2 Image Builder identifica automaticamente o ARN da imagem pai. Ao usar o IaC para criar a fórmula, você deve identificar o ARN e selecionar a versão da imagem desejada ou usar o ARN sem versão para indicar a última imagem disponível. Recomendamos criar um script automatizado para filtrar e exibir somente imagens que estejam alinhadas com seus critérios. O script em Python a seguir mostra como recuperar uma lista de AMIs otimizadas para Amazon ECS. 

O script aceita dois argumentos opcionais: `owner` e `platform`, com valores padrão de “Amazon” e “Windows”, respectivamente. Os valores válidos do argumento do proprietário são: `Self`, `Shared`, `Amazon` e `ThirdParty`. Os valores válidos do argumento da plataforma são `Windows` e `Linux`. Por exemplo, se você executar o script com o argumento `owner` definido como `Amazon` e o `platform` definido como `Linux`, o script gera uma lista de imagens publicadas pela Amazon, incluindo imagens otimizadas para Amazon ECS.

```
import boto3
import argparse

def list_images(owner, platform):
    # Create a Boto3 session
    session = boto3.Session()
    
    # Create an EC2 Image Builder client
    client = session.client('imagebuilder')

    # Define the initial request parameters
    request_params = {
        'owner': owner,
        'filters': [
            {
                'name': 'platform',
                'values': [platform]
            }
        ]
    }

    # Initialize the results list
    all_images = []

    # Get the initial response with the first page of results
    response = client.list_images(**request_params)

    # Extract images from the response
    all_images.extend(response['imageVersionList'])

    # While 'nextToken' is present, continue paginating
    while 'nextToken' in response and response['nextToken']:
        # Update the token for the next request
        request_params['nextToken'] = response['nextToken']

        # Get the next page of results
        response = client.list_images(**request_params)

        # Extract images from the response
        all_images.extend(response['imageVersionList'])

    return all_images

def main():
    # Initialize the parser
    parser = argparse.ArgumentParser(description="List AWS images based on owner and platform")
    
    # Add the parameters/arguments
    parser.add_argument("--owner", default="Amazon", help="The owner of the images. Default is 'Amazon'.")
    parser.add_argument("--platform", default="Windows", help="The platform type of the images. Default is 'Windows'.")

    # Parse the arguments
    args = parser.parse_args()

    # Retrieve all images based on the provided owner and platform
    images = list_images(args.owner, args.platform)

    # Print the details of the images
    for image in images:
        print(f"Name: {image['name']}, Version: {image['version']}, ARN: {image['arn']}")

if __name__ == "__main__":
    main()
```

## Uso do ARN de imagem com o CloudFormation
<a name="arn-with-cloudformation"></a>

Uma fórmula de imagem do Image Builder é um esquema que especifica a imagem pai e os componentes necessários para alcançar a configuração pretendida da imagem de saída. Use o recurso `AWS::ImageBuilder::ImageRecipe`. Defina o valor de `ParentImage` para o ARN de imagem. Use o ARN sem versão da imagem desejada para garantir que o pipeline sempre use a versão mais recente da imagem. Por exemplo, `arn:aws:imagebuilder:us-east-1:aws:image/amazon-linux-2023-ecs-optimized-x86/x.x.x`. A definição do recurso `AWS::ImageBuilder::ImageRecipe` a seguir usa um ARN de imagem gerenciada pela Amazon:

```
ECSRecipe:
    Type: AWS::ImageBuilder::ImageRecipe
    Properties:
      Name: MyRecipe
      Version: '1.0.0'
      Components:
        - ComponentArn: [<The component arns of the image recipe>]
      ParentImage: "arn:aws:imagebuilder:us-east-1:aws:image/amazon-linux-2023-ecs-optimized-x86/x.x.x"
```

Para obter mais informações sobre o recurso [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-imagebuilder-imagerecipe.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-imagebuilder-imagerecipe.html), consulte o *Guia do usuário do AWS CloudFormation*.

Você pode automatizar a criação de imagens no pipeline definindo a propriedade de `Schedule` do recurso `AWS::ImageBuilder::ImagePipeline`. O cronograma inclui uma condição inicial e uma expressão cron. Consulte mais informações em [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-imagebuilder-imagepipeline.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-imagebuilder-imagepipeline.html) no *Guia de Usuário AWS CloudFormation*.

 O exemplo de `AWS::ImageBuilder::ImagePipeline` a seguir faz com que o pipeline execute uma compilação às 10h do Tempo Universal Coordenado (UTC) todos os dias. Defina os seguintes valores de `Schedule`:
+ Defina `PipelineExecutionStartCondition` como `EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE`. A compilação é iniciada somente se os recursos dependentes, como a imagem pai ou os componentes, que usam o caractere curinga ‘x’ em suas versões semânticas, forem atualizados. Isso garante que a compilação incorpore as atualizações mais recentes desses recursos.
+ Defina ScheduleExpression como a expressão cron `(0 10 * * ? *)`.

```
ECSPipeline:
    Type: AWS::ImageBuilder::ImagePipeline
    Properties:
      Name: my-pipeline
      ImageRecipeArn: <arn of the recipe you created in previous step>
      InfrastructureConfigurationArn: <ARN of the infrastructure configuration associated with this image pipeline>
      Schedule:
        PipelineExecutionStartCondition: EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE
        ScheduleExpression: 'cron(0 10 * * ? *)'
```

## Uso do ARN de imagem com o Terraform
<a name="arn-with-terraform"></a>

A abordagem para especificar a imagem pai e o cronograma do pipeline no Terraform está alinhada com a do AWS CloudFormation. Use o recurso `aws_imagebuilder_image_recipe`. Defina o valor de `parent_image` para o ARN de imagem. Use o ARN sem versão da imagem desejada para garantir que o pipeline sempre use a versão mais recente da imagem. Para obter mais informações, consulte [https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/imagebuilder_image_recipe#argument-reference](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/imagebuilder_image_recipe#argument-reference) na documentação do Terraform. 

No bloco de configuração de agendamento do `aws_imagebuilder_image_pipeline resource`, defina o valor do argumento `schedule_expression` como uma expressão cron de sua escolha para especificar a frequência de execução do pipeline e defina a `pipeline_execution_start_condition` como `EXPRESSION_MATCH_AND_DEPENDENCY_UPDATES_AVAILABLE`. Para obter mais informações, consulte [https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/imagebuilder_image_pipeline#argument-reference](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/imagebuilder_image_pipeline#argument-reference) na documentação do Terraform. 

# Usar containers de aprendizado profundo da AWS no Amazon ECS
<a name="deep-learning-containers"></a>

Os contêineres de deep learning da AWS fornecem um conjunto de imagens do Docker para treinar e fornecer modelos no TensorFlow e no Apache MXNet (Incubating) no Amazon ECS. O Deep Learning Containers fornece ambientes otimizados com bibliotecas TensorFlow, NVIDIA CUDA (para instâncias de GPU) e Intel MKL (para instâncias de CPU). As imagens de contêiner para o Deep Learning Containers estão disponíveis no Amazon ECR para referência nas definições de tarefa do Amazon ECS. É possível usar o Deep Learning Containers junto com o Amazon Elastic Inference para reduzir os custos de inferência.

Para começar a usar o Deep Learning Containers sem o Elastic Inference no Amazon ECS, consulte [Configuração do Amazon ECS](https://docs.aws.amazon.com/deep-learning-containers/latest/devguide/deep-learning-containers-ecs-setup.html) no *Guia do desenvolvedor do AMIs de deep learning da AWS*.

# Tutorial: como criar um serviço usando uma implantação azul/verde
<a name="create-blue-green"></a>

O Amazon ECS integrou as implantações azul/verde ao assistente Create Service (Criar serviço) no console do Amazon ECS. Para obter mais informações, consulte [Criação de uma implantação de atualização contínua do Amazon ECS](create-service-console-v2.md).

O tutorial a seguir mostra como criar um serviço do Amazon ECS contendo uma tarefa do Fargate que usa o tipo de implantação azul/verde com a AWS CLI.

**nota**  
Adicionado suporte para executar uma implantação azul/verde para CloudFormation. Para obter mais informações, consulte [Executar implantações azuis/verdes do Amazon ECS por meio do CodeDeploy usando o CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/blue-green.html) no * Guia do usuário do AWS CloudFormation*.

## Pré-requisitos
<a name="create-blue-green-prereqs"></a>

Este tutorial pressupõe que você concluiu os seguintes pré-requisitos:
+ A versão mais recente da AWS CLI está instalada e configurada. Para obter mais informações sobre como instalar ou fazer upgrade do AWS CLI, consulte [Instalar o AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/installing.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. Para obter mais informações, consulte [Criar uma nuvem privada virtual](get-set-up-for-amazon-ecs.md#create-a-vpc).
+ A função do IAM do CodeDeploy do Amazon ECS é criada. Para obter mais informações, consulte [Função do IAM para CodeDeploy do Amazon ECS](codedeploy_IAM_role.md).

## Etapa 1: criar um Application Load Balancer
<a name="create-blue-green-loadbalancer"></a>

Os serviços do Amazon ECS que usam o tipo de implantação azul/verde exigem o uso de um Application Load Balancer ou de um Network Load Balancer. Este tutorial usa um Application Load Balancer.

**Para criar um Application Load Balancer**

1. Use o comando [create-load-balancer](https://docs.aws.amazon.com/cli/latest/reference/elbv2/create-load-balancer.html) para criar um Application Load Balancer. Especifique duas sub-redes que não estejam na mesma Zona de disponibilidade, bem como um grupo de segurança.

   ```
   aws elbv2 create-load-balancer \
        --name bluegreen-alb \
        --subnets subnet-abcd1234 subnet-abcd5678 \
        --security-groups sg-abcd1234 \
        --region us-east-1
   ```

   O resultado inclui o Nome de recurso da Amazon (ARN) do load balancer, com o seguinte formato:

   ```
   arn:aws:elasticloadbalancing:region:aws_account_id:loadbalancer/app/bluegreen-alb/e5ba62739c16e642
   ```

1. Use o comando [create-target-group](https://docs.aws.amazon.com/cli/latest/reference/elbv2/create-target-group.html) para criar um grupo de destino. Esse grupo de destino roteará o tráfego para a tarefa original definida no seu serviço.

   ```
   aws elbv2 create-target-group \
        --name bluegreentarget1 \
        --protocol HTTP \
        --port 80 \
        --target-type ip \
        --vpc-id vpc-abcd1234 \
        --region us-east-1
   ```

   A saída inclui o ARN do grupo de destino, com o seguinte formato:

   ```
   arn:aws:elasticloadbalancing:region:aws_account_id:targetgroup/bluegreentarget1/209a844cd01825a4
   ```

1. Use o comando [create-listener](https://docs.aws.amazon.com/cli/latest/reference/elbv2/create-listener.html) para criar um listener do load balancer com uma regra padrão que encaminha solicitações ao grupo de destino.

   ```
   aws elbv2 create-listener \
        --load-balancer-arn arn:aws:elasticloadbalancing:region:aws_account_id:loadbalancer/app/bluegreen-alb/e5ba62739c16e642 \
        --protocol HTTP \
        --port 80 \
        --default-actions Type=forward,TargetGroupArn=arn:aws:elasticloadbalancing:region:aws_account_id:targetgroup/bluegreentarget1/209a844cd01825a4 \
        --region us-east-1
   ```

   A saída inclui o ARN do listener, com o seguinte formato:

   ```
   arn:aws:elasticloadbalancing:region:aws_account_id:listener/app/bluegreen-alb/e5ba62739c16e642/665750bec1b03bd4
   ```

## Etapa 2: criar um cluster do Amazon ECS
<a name="create-blue-green-cluster"></a>

Use o comando [create-cluster](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-cluster.html) para criar um cluster chamado `tutorial-bluegreen-cluster` a ser usado.

```
aws ecs create-cluster \
     --cluster-name tutorial-bluegreen-cluster \
     --region us-east-1
```

A saída inclui o ARN do cluster, com o seguinte formato:

```
arn:aws:ecs:region:aws_account_id:cluster/tutorial-bluegreen-cluster
```

## Etapa 3: registrar uma definição de tarefa
<a name="create-blue-green-taskdef"></a>

Use o comando [register-task-definition](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html) para registrar uma definição de tarefa compatível com o Fargate. Ele exige o uso do modo de rede `awsvpc`. Veja a seguir o exemplo de definição de tarefa usado para este tutorial.

Primeiro, crie um arquivo chamado `fargate-task.json` com os conteúdos a seguir. Certifique-se de usar o ARN para a sua função de execução da tarefa. Para obter mais informações, consulte [Função do IAM de execução de tarefas do Amazon ECS](task_execution_IAM_role.md).

```
{
    "family": "sample-fargate", 
    "networkMode": "awsvpc", 
    "containerDefinitions": [
        {
            "name": "sample-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"
}
```

Em seguida, registre a definição de tarefa usando o arquivo `fargate-task.json` criado.

```
aws ecs register-task-definition \
     --cli-input-json file://fargate-task.json \
     --region us-east-1
```

## Etapa 4: criar um serviço do Amazon ECS
<a name="create-blue-green-service"></a>

Use o comando [create-service](https://docs.aws.amazon.com/cli/latest/reference/ecs/create-service.html) para criar um serviço. 

Primeiro, crie um arquivo chamado `service-bluegreen.json` com os conteúdos a seguir.

```
{
    "cluster": "tutorial-bluegreen-cluster",
    "serviceName": "service-bluegreen",
    "taskDefinition": "tutorial-task-def",
    "loadBalancers": [
        {
            "targetGroupArn": "arn:aws:elasticloadbalancing:region:aws_account_id:targetgroup/bluegreentarget1/209a844cd01825a4",
            "containerName": "sample-app",
            "containerPort": 80
        }
    ],
    "launchType": "FARGATE",
    "schedulingStrategy": "REPLICA",
    "deploymentController": {
        "type": "CODE_DEPLOY"
    },
    "platformVersion": "LATEST",
    "networkConfiguration": {
       "awsvpcConfiguration": {
          "assignPublicIp": "ENABLED",
          "securityGroups": [ "sg-abcd1234" ],
          "subnets": [ "subnet-abcd1234", "subnet-abcd5678" ]
       }
    },
    "desiredCount": 1
}
```

Em seguida, crie o seu serviço usando o arquivo `service-bluegreen.json` que você criou.

```
aws ecs create-service \
     --cli-input-json file://service-bluegreen.json \
     --region us-east-1
```

A saída inclui o ARN do serviço, com o seguinte formato:

```
arn:aws:ecs:region:aws_account_id:service/service-bluegreen
```

## Etapa 5: criar os recursos do AWS CodeDeploy
<a name="create-blue-green-codedeploy"></a>

Use as etapas a seguir para criar a aplicação do CodeDeploy, o grupo de destino do Application Load Balancer para o grupo de implantação do CodeDeploy e o grupo de implantação do CodeDeploy.

**Para criar recursos do CodeDeploy**

1. Use o comando [create-application](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-application.html) para criar uma aplicação do CodeDeploy. Especifique a plataforma de computação `ECS`.

   ```
   aws deploy create-application \
        --application-name tutorial-bluegreen-app \
        --compute-platform ECS \
        --region us-east-1
   ```

   A saída inclui o ID do aplicativo, com o seguinte formato:

   ```
   {
       "applicationId": "b8e9c1ef-3048-424e-9174-885d7dc9dc11"
   }
   ```

1. Use o comando [create-target-group](https://docs.aws.amazon.com/cli/latest/reference/elbv2/create-target-group.html) para criar um segundo grupo de destino do Application Load Balancer, que será usado quando for criado o grupo de implantação do CodeDeploy.

   ```
   aws elbv2 create-target-group \
        --name bluegreentarget2 \
        --protocol HTTP \
        --port 80 \
        --target-type ip \
        --vpc-id "vpc-0b6dd82c67d8012a1" \
        --region us-east-1
   ```

   A saída inclui o ARN para o grupo de destino, com o seguinte formato:

   ```
   arn:aws:elasticloadbalancing:region:aws_account_id:targetgroup/bluegreentarget2/708d384187a3cfdc
   ```

1. Use o comando [create-deployment-group](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment-group.html) para criar um grupo de implantação do CodeDeploy.

   Primeiro, crie um arquivo chamado `tutorial-deployment-group.json` com os conteúdos a seguir. Este exemplo usa o recurso que você criou. Para o `serviceRoleArn`, especifique o ARN da função do IAM do CodeDeploy do Amazon ECS. Para obter mais informações, consulte [Função do IAM para CodeDeploy do Amazon ECS](codedeploy_IAM_role.md).

   ```
   {
      "applicationName": "tutorial-bluegreen-app",
      "autoRollbackConfiguration": {
         "enabled": true,
         "events": [ "DEPLOYMENT_FAILURE" ]
      },
      "blueGreenDeploymentConfiguration": {
         "deploymentReadyOption": {
            "actionOnTimeout": "CONTINUE_DEPLOYMENT",
            "waitTimeInMinutes": 0
         },
         "terminateBlueInstancesOnDeploymentSuccess": {
            "action": "TERMINATE",
            "terminationWaitTimeInMinutes": 5
         }
      },
      "deploymentGroupName": "tutorial-bluegreen-dg",
      "deploymentStyle": {
         "deploymentOption": "WITH_TRAFFIC_CONTROL",
         "deploymentType": "BLUE_GREEN"
      },
      "loadBalancerInfo": {
         "targetGroupPairInfoList": [
           {
             "targetGroups": [
                {
                    "name": "bluegreentarget1"
                },
                {
                    "name": "bluegreentarget2"
                }
             ],
             "prodTrafficRoute": {
                 "listenerArns": [
                     "arn:aws:elasticloadbalancing:region:aws_account_id:listener/app/bluegreen-alb/e5ba62739c16e642/665750bec1b03bd4"
                 ]
             }
           }
         ]
      },
      "serviceRoleArn": "arn:aws:iam::aws_account_id:role/ecsCodeDeployRole",
      "ecsServices": [
          {
              "serviceName": "service-bluegreen",
              "clusterName": "tutorial-bluegreen-cluster"
          }
      ]
   }
   ```

   Em seguida, cria um grupo de implantação do CodeDeploy.

   ```
   aws deploy create-deployment-group \
        --cli-input-json file://tutorial-deployment-group.json \
        --region us-east-1
   ```

   A saída inclui o ID do grupo de implantação, com o seguinte formato:

   ```
   {
       "deploymentGroupId": "6fd9bdc6-dc51-4af5-ba5a-0a4a72431c88"
   }
   ```

## Etapa 6: criar e monitorar uma implantação do CodeDeploy
<a name="create-blue-green-verify"></a>

Use as seguintes etapas para criar e carregar um arquivo de especificação de aplicação (arquivo AppSpec) e uma implantação do CodeDeploy.

**Para criar e monitorar uma implantação do CodeDeploy**

1. Crie e faça upload de um arquivo AppSpec usando as etapas a seguir.

   1. Crie um arquivo denominado `appspec.yaml` com o conteúdo do grupo de implantação do CodeDeploy. Este exemplo usa os recursos criados por você anteriormente no tutorial.

      ```
      version: 0.0
      Resources:
        - TargetService:
            Type: AWS::ECS::Service
            Properties:
              TaskDefinition: "arn:aws:ecs:region:aws_account_id:task-definition/first-run-task-definition:7"
              LoadBalancerInfo:
                ContainerName: "sample-app"
                ContainerPort: 80
              PlatformVersion: "LATEST"
      ```

   1. Use o comando [s3 mb](https://docs.aws.amazon.com/cli/latest/reference/s3/mb.html) para criar um bucket do Amazon S3 para o arquivo AppSpec.

      ```
      aws s3 mb s3://tutorial-bluegreen-bucket
      ```

   1. Use o comando [s3 cp](https://docs.aws.amazon.com/cli/latest/reference/s3/cp.html) para carregar o arquivo AppSpec para o bucket do Amazon S3.

      ```
      aws s3 cp ./appspec.yaml s3://tutorial-bluegreen-bucket/appspec.yaml
      ```

1. Crie a implantação do CodeDeploy usando as etapas a seguir.

   1. Crie um arquivo denominado `create-deployment.json` com o conteúdo da implantação do CodeDeploy. Este exemplo usa os recursos criados por você anteriormente no tutorial.

      ```
      {
          "applicationName": "tutorial-bluegreen-app",
          "deploymentGroupName": "tutorial-bluegreen-dg",
          "revision": {
              "revisionType": "S3",
              "s3Location": {
                  "bucket": "tutorial-bluegreen-bucket",
                  "key": "appspec.yaml",
                  "bundleType": "YAML"
              }
          }
      }
      ```

   1. Use o comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/deploy/create-deployment.html) para criar uma implantação.

      ```
      aws deploy create-deployment \
           --cli-input-json file://create-deployment.json \
           --region us-east-1
      ```

      A saída inclui o ID de implantação, com o seguinte formato:

      ```
      {
          "deploymentId": "d-RPCR1U3TW"
      }
      ```

   1. Use o comando [get-deployment-target](https://docs.aws.amazon.com/cli/latest/reference/deploy/get-deployment-target.html) para obter os detalhes da implantação, especificando o `deploymentId` da saída anterior.

      ```
      aws deploy get-deployment-target \
           --deployment-id "d-IMJU3A8TW" \
           --target-id tutorial-bluegreen-cluster:service-bluegreen \
           --region us-east-1
      ```

      Continue a recuperar os detalhes de implantação até que o status seja `Succeeded`, como mostra a saída a seguir.

      ```
      {
          "deploymentTarget": {
              "deploymentTargetType": "ECSTarget",
              "ecsTarget": {
                  "deploymentId": "d-RPCR1U3TW",
                  "targetId": "tutorial-bluegreen-cluster:service-bluegreen",
                  "targetArn": "arn:aws:ecs:region:aws_account_id:service/service-bluegreen",
                  "lastUpdatedAt": 1543431490.226,
                  "lifecycleEvents": [
                      {
                          "lifecycleEventName": "BeforeInstall",
                          "startTime": 1543431361.022,
                          "endTime": 1543431361.433,
                          "status": "Succeeded"
                      },
                      {
                          "lifecycleEventName": "Install",
                          "startTime": 1543431361.678,
                          "endTime": 1543431485.275,
                          "status": "Succeeded"
                      },
                      {
                          "lifecycleEventName": "AfterInstall",
                          "startTime": 1543431485.52,
                          "endTime": 1543431486.033,
                          "status": "Succeeded"
                      },
                      {
                          "lifecycleEventName": "BeforeAllowTraffic",
                          "startTime": 1543431486.838,
                          "endTime": 1543431487.483,
                          "status": "Succeeded"
                      },
                      {
                          "lifecycleEventName": "AllowTraffic",
                          "startTime": 1543431487.748,
                          "endTime": 1543431488.488,
                          "status": "Succeeded"
                      },
                      {
                          "lifecycleEventName": "AfterAllowTraffic",
                          "startTime": 1543431489.152,
                          "endTime": 1543431489.885,
                          "status": "Succeeded"
                      }
                  ],
                  "status": "Succeeded",
                  "taskSetsInfo": [
                      {
                          "identifer": "ecs-svc/9223370493425779968",
                          "desiredCount": 1,
                          "pendingCount": 0,
                          "runningCount": 1,
                          "status": "ACTIVE",
                          "trafficWeight": 0.0,
                          "targetGroup": {
                              "name": "bluegreentarget1"
                          }
                      },
                      {
                          "identifer": "ecs-svc/9223370493423413672",
                          "desiredCount": 1,
                          "pendingCount": 0,
                          "runningCount": 1,
                          "status": "PRIMARY",
                          "trafficWeight": 100.0,
                          "targetGroup": {
                              "name": "bluegreentarget2"
                          }
                      }
                  ]
              }
          }
      }
      ```

## Etapa 7: limpar
<a name="create-blue-green-cleanup"></a>

Ao concluir este tutorial, limpe os recursos associados a ele para evitar cobranças por recursos que você não está usando.

**Limpando os recursos do tutorial**

1. Use o comando [delete-deployment-group](https://docs.aws.amazon.com/cli/latest/reference/deploy/delete-deployment-group.html) para excluir o grupo de implantação do CodeDeploy.

   ```
   aws deploy delete-deployment-group \
        --application-name tutorial-bluegreen-app \
        --deployment-group-name tutorial-bluegreen-dg \
        --region us-east-1
   ```

1. Use o comando [delete-application](https://docs.aws.amazon.com/cli/latest/reference/deploy/delete-application.html) para excluir a aplicação do CodeDeploy.

   ```
   aws deploy delete-application \
        --application-name tutorial-bluegreen-app \
        --region us-east-1
   ```

1. Use o comando [delete-service](https://docs.aws.amazon.com/cli/latest/reference/ecs/delete-service.html) para excluir o serviço do Amazon ECS. Usar o sinalizador `--force` permite que você exclua um serviço, ainda que ele não tenha sido reduzido a zero tarefas.

   ```
   aws ecs delete-service \
        --service arn:aws:ecs:region:aws_account_id:service/service-bluegreen \
        --force \
        --region us-east-1
   ```

1. Use o comando [delete-cluster](https://docs.aws.amazon.com/cli/latest/reference/ecs/delete-cluster.html) para excluir o cluster do Amazon ECS.

   ```
   aws ecs delete-cluster \
        --cluster tutorial-bluegreen-cluster \
        --region us-east-1
   ```

1. Use o comando [s3 rm](https://docs.aws.amazon.com/cli/latest/reference/s3/rm.html) para excluir o arquivo AppSpec do bucket do Amazon S3.

   ```
   aws s3 rm s3://tutorial-bluegreen-bucket/appspec.yaml
   ```

1. Use o comando [s3 rb](https://docs.aws.amazon.com/cli/latest/reference/s3/rb.html) para excluir o bucket do Amazon S3.

   ```
   aws s3 rb s3://tutorial-bluegreen-bucket
   ```

1. Use o comando [delete-load-balancer](https://docs.aws.amazon.com/cli/latest/reference/elbv2/delete-load-balancer.html) para excluir o Application Load Balancer.

   ```
   aws elbv2 delete-load-balancer \
        --load-balancer-arn arn:aws:elasticloadbalancing:region:aws_account_id:loadbalancer/app/bluegreen-alb/e5ba62739c16e642 \
        --region us-east-1
   ```

1. Use o comando [delete-target-group](https://docs.aws.amazon.com/cli/latest/reference/elbv2/delete-target-group.html) para excluir os dois grupos de destino do Application Load Balancer.

   ```
   aws elbv2 delete-target-group \
        --target-group-arn arn:aws:elasticloadbalancing:region:aws_account_id:targetgroup/bluegreentarget1/209a844cd01825a4 \
        --region us-east-1
   ```

   ```
   aws elbv2 delete-target-group \
        --target-group-arn arn:aws:elasticloadbalancing:region:aws_account_id:targetgroup/bluegreentarget2/708d384187a3cfdc \
        --region us-east-1
   ```