Criar uma tarefa do Amazon ECS para o tipo de inicialização do EC2 com a AWS CLI

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.

Pré-requisitos

Este tutorial pressupõe que os seguintes pré-requisitos foram concluídos:

Criar um cluster

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

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

aws ecs create-cluster --cluster-name MyCluster

Saída:

{
    "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

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.

Listar instâncias de contêiner

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

aws ecs list-container-instances --cluster default

Saída:

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

Descrever sua instância de contêiner

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

Saída:

{
    "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 ECS ou com o comando aws ec2 describe-instances --instance-id instance_id.

Registrar uma definição de tarefa

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.

{
    "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

É 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

Saída:

{
    "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

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 padrão.

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

Saída:

{
    "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

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

Saída:

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

Descrever o serviço

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

Saída:

{
    "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

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

Saída:

{
    "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

Limpar recursos

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