Como solucionar problemas de erros comuns com chamadas de API no Amazon ECS?

Breve descrição

As APIs do Amazon ECS podem falhar com um dos seguintes erros:

• AccessDeniedException
• ClientException
• ClusterNotFoundException
• InvalidParameterException
• ServerException
• ServiceNotActiveException
• PlatformTaskDefinitionIncompatibilityException
• PlatformUnknownException
• ServiceNotFoundException
• UnsupportedFeatureException

Você também pode enfrentar problemas de API com a aplicação que está sendo executada dentro das suas tarefas do Amazon ECS

Resolução

Suas solicitações de API são registradas no AWS CloudTrail como eventos. Quando a atividade ocorre no Amazon ECS, ela é registrada em um evento do CloudTrail junto com outros eventos de serviço da AWS em Event history (Histórico de eventos). Você pode visualizar, pesquisar e baixar eventos recentes na sua conta da AWS.

Para visualizar o histórico de eventos do CloudTrail e localizar os erros de API, faça o seguinte:

1. Abra o console do AWS CloudTrail.
2. No painel de navegação, escolha Event history (Histórico de eventos).
3. Escolha o ícone de engrenagem.
4. Em Select visible columns (Selecionar colunas visíveis), selecione Error code (Código de erro).
5. Escolha Confirm (Confirmar).
6. Na página Event history (Histórico de eventos), para Lookup attributes (Atributos de pesquisa), selecione Event name (Nome do evento).
7. Para Enter an event name (Inserir um nome de evento), insira a ação que falhou.
   Observação: se você não souber o nome do evento, faça o seguinte:
   Para Lookup attributes (Atributos de pesquisa), selecione Event source (Fonte do evento).
   Para Enter an event source (Inserir uma fonte de evento), selecione ecs.amazonaws.com para filtrar todos os eventos relacionados ao seu serviço do ECS.
8. Na lista de resultados, escolha os eventos com códigos de erro de sua escolha para visualizar os detalhes desses eventos.

AccessDeniedException

Esse erro é registrado quando o usuário ou a função do AWS Identity and Access Management (IAM) que faz a chamada de API não tem as permissões necessárias para executar a ação solicitada.

O erro AccessDeniedException é semelhante ao seguinte:

An error occurred (AccessDeniedException) when calling the CreateCluster operation: User: arn:aws:sts::123456789012:assumed-role/test-role/test-session is not authorized to perform: ecs:CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action

Você pode visualizar os seguintes detalhes no registro de eventos do CloudTrail relacionado:

• Informações do usuário:

"type": "AssumedRole",
"principalId": "AROAZEPPWYLQU45ZDJY6V:test-session",
"arn": "arn:aws:sts::123456789012:assumed-role/test-role/test-session"

• Nome do evento:

"eventName": "CreateCluster"

• Mensagem de erro:

"errorMessage": "User: arn:aws:sts::123456789012:assumed-role/test-role/test-session is not authorized to perform: ecs:CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action"

Para testar uma política que não está anexada a um usuário, grupo de usuários ou função, use o simulador de políticas do IAM.

Para resolver esse erro, faça o seguinte:

1. Abra o console do IAM.
2. No painel de navegação, escolha Roles (Funções) ou Users (Usuários), dependendo da identidade do usuário.
3. Filtre a função ou o usuário usando o filtro de pesquisa.
4. Escolha a função ou o usuário.
5. Escolha a guia Permissions (Permissões).
6. Expanda a política de permissões para visualizar as permissões associadas ao usuário.
7. Certifique-se de que a política inclua ecs:your-event-name na lista Actions (Ações) e Allow (Permitir) para Effect (Efeito). Se a política não incluir esses parâmetros, atualize-a para incluir essas alterações. Ou crie uma nova política que permita a ação mencionada e anexe-a à função ou ao usuário do IAM. Para obter mais informações, Editar políticas gerenciadas pelo cliente (console).

ClientException

Esse erro é registrado quando o cliente do ECS especifica um identificador ou recurso que não é válido ou não existe. Por exemplo, se você tentar iniciar uma tarefa usando a API RunTask ou StartTask e indicar uma definição de tarefa incorreta, receberá este erro:

$ aws ecs run-task --cluster example-cluster --task-definition centos --region ap-southeast-2
An error occurred (ClientException) when calling the RunTask operation: TaskDefinition not found.

$ aws ecs start-task --cluster example-cluster --task-definition centos --container-instances 765936fadbdd46b5991a4bd70c2a43d4 --region ap-southeast-2
An error occurred (ClientException) when calling the StartTask operation: TaskDefinition not found.

Para evitá-lo, verifique se os recursos referenciados no comando, seu código ou chamadas de API existem e são válidos.

ClusterNotFoundException

Esse erro é registrado quando o cluster especificado não é encontrado.

Exemplo:

$ aws ecs run-task --task-definition CentOS --cluster example-cluster --region ap-southeast-2
An error occurred (ClusterNotFoundException) when calling the StartTask operation: Cluster not found.

Para evitar esse erro, verifique se o nome do cluster transmitido no comando, no código ou nas chamadas de API está correto. É possível executar o seguinte comando para listar os clusters do ECS existentes. Com a lista retornada, você pode verificar se o cluster mencionado na chamada de API existe.

$ aws ecs list-clusters --region example-region
{
    "clusterArns": [
        "arn:aws:ecs:ap-southeast-2:123456789012:cluster/my-cluster",
        "arn:aws:ecs:ap-southeast-2:123456789012:cluster/my-private-cluster"
    ]
}

InvalidParameterException

Esse erro é registrado quando o parâmetro transmitido no comando não é válido. Suponha que você tenha mencionado uma versão da definição de tarefa que não existe:

$ aws ecs run-task --task-definition CentOS:3 --cluster example-cluster --region ap-southeast-2

O erro é semelhante ao seguinte:

An error occurred (InvalidParameterException) when calling the RunTask operation: TaskDefinition not found.

Para evitá-lo, certifique-se de que os parâmetros transmitidos no comando sejam válidos.

ServerException

Esse erro é registrado quando há um erro de servidor relacionado à chamada de API. ServerException geralmente é causado devido ao código de erro HTTP 500. Essa exceção ocorre quando há um problema com o serviço do ECS na região da AWS. Esse erro geralmente é temporário, e as tentativas subsequentes de executar a API serão bem-sucedidas. No entanto, se o problema persistir por um longo período, entre em contato com o AWS Support.

ServiceNotActiveException

Esse erro ocorre quando o serviço do ECS que está sendo atualizado não está ativo. Verifique se o serviço do ECS que está sendo atualizado está presente no cluster do ECS e está no estado ativo.

Execute o seguinte comando da AWS Command Line Interface (AWS CLI) para listar todos os serviços no cluster:

$ aws ecs list-services --cluster example-cluster

Na saída, verifique se o serviço que está sendo atualizado é exibido.

Observação: se você receber erros ao executar comandos da AWS CLI, verifique se está usando a versão mais recente da AWS CLI.

Em seguida, execute o seguinte comando para verificar se o serviço está no estado ativo.

$ aws ecs describe-services --services example-service-name --cluster example-cluster

A saída pode ser semelhante à seguinte:

{
    "services": [{
        "serviceArn": "arn:aws:ecs:ap-southeast-2:111122223333:service/my-cluster/example-service",
        "serviceName": "example-service",
        "clusterArn": "arn:aws:ecs:ap-southeast-2:111122223333:cluster/example-cluster",
        "loadBalancers": [],
        "serviceRegistries": [],
        "status": "ACTIVE",
        ......
    }]
}

PlatformTaskDefinitionIncompatibilityException

Esse erro ocorre quando uma tarefa é iniciada em uma plataforma que não atende aos recursos exigidos na definição da tarefa. Suponha que você tente criar um serviço com um volume do Amazon EFS anexado na plataforma de versão 1.3.0:

$ aws ecs create-service \
    --cluster example-cluster \
    --task-definition Test-fargate-EFS \
    --launch-type FARGATE \
    --service-name example-service \
    --desired-count 1 \
    --network-configuration="awsvpcConfiguration={subnets=["subnet-ed7d31b5","subnet-833ef1cb"],securityGroups=["sg-eeb28aa1"]}" \
    --platform-version 1.3.0

Em seguida, você recebe o seguinte erro:

An error occurred (PlatformTaskDefinitionIncompatibilityException) when calling the CreateService operation: One or more of the requested capabilities are not supported.

Para resolver esse problema, use a versão da plataforma que oferece suporte aos requisitos de capacidade na definição de tarefa. Para obter informações sobre os recursos compatíveis nas várias versões da plataforma, consulte Versões da plataforma AWS Fargate.

PlatformUnknownException

Esse erro ocorre quando você especificar uma versão de plataforma desconhecida ou errada ao iniciar uma tarefa. Suponha que você forneça uma plataforma incorreta da versão 1.3 em vez da versão 1.3.0:

$ aws ecs create-service \
    --cluster example-cluster\
    --task-definition example-task \
    --launch-type FARGATE\
    --enable-execute-command \
    --service-name example-service\
    --desired-count 1 \
    --network-configuration="awsvpcConfiguration={subnets=["subnet-ed7d31b5","subnet-833ef1cb"],securityGroups=["sg-eeb28aa1"]}"\
    --platform-version 1.3

Em seguida, você recebe o seguinte erro:

An error occurred (PlatformUnknownException) when calling the CreateService operation: The specified platform does not exist.

Para obter mais informações, consulte Versões da plataforma Linux e Versões da plataforma Windows.

ServiceNotFoundException

Esse erro ocorre quando o serviço do ECS especificado no seu comando ou código não existe. Verifique se o nome do serviço no seu comando ou código está correto e se o serviço está presente no cluster.

Para visualizar todos os serviços do cluster, execute o seguinte comando:

$ aws ecs list-services --cluster example-cluster

UnsupportedFeatureException

Esse erro ocorre quando um recurso do ECS não está disponível em uma região específica. Por exemplo, o recurso do AWS Fargate pode não estar disponível imediatamente em uma região recém-lançada. Se uma tarefa do Fargate for iniciada nessa região, você receberá o erro UnsupportedFeatureException.

Problemas com a API da aplicação

Veja a seguir alguns dos erros HTTP 5xx mais comumente vistos que você pode receber ao acessar a aplicação hospedada dentro de uma tarefa do ECS:

500 - Internal Server Error: (Erro interno do servidor) Você recebe esse erro quando a aplicação encontra uma condição inesperada. Esse erro pode ocorrer devido à configuração incorreta da aplicação ou devido a um erro com a aplicação.

503 - Service Unavailable: (Serviço indisponível) Você recebe esse erro nas seguintes condições:

• A tarefa do ECS está passando por workload pesada e não consegue atender à solicitação.
• A aplicação em execução dentro da sua tarefa está fora do ar para manutenção.

Para solucionar esses erros, faça o seguinte:

Analise os logs da aplicação para as tarefas do ECS no Amazon CloudWatch Logs. Você pode encontrar informações sobre o grupo de logs na definição da tarefa. Cada tarefa é associada a um fluxo longo individual que contém os logs de aplicação da tarefa.

Para visualizar o grupo de registros e o fluxo de logs da sua tarefa, execute o seguinte comando:

$ aws ecs describe-task-definition —task-definition example-taskdefinition

A saída terá a seguinte aparência:

...
                "logConfiguration": {
                    "logDriver": "awslogs",
                    "options": {
                        "awslogs-group": "/ecs/example-task",
                        "awslogs-region": "ap-southeast-2",
                        "awslogs-stream-prefix": "ecs"
                    }
                }
...

---

Informações relacionadas

Razões de falhas em APIs