Como soluciono erros comuns com chamadas de API no Amazon ECS?
Quero solucionar erros comuns com chamadas de API no Amazon Elastic Container Service (Amazon ECS).
Breve descrição
Os seguintes erros podem fazer com que uma chamada de API do Amazon ECS falhe:
- "AccessDeniedException"
- "ClientException"
- "ClusterNotFoundException"
- "InvalidParameterException"
- "ServerException"
- "ServiceNotActiveException"
- "PlatformTaskDefinitionIncompatibilityException"
- "PlatformUnknownException"
- "ServiceNotFoundException"
- "UnsupportedFeatureException"
As aplicações executadas dentro de suas tarefas do Amazon ECS também podem fazer com que sua chamada de API do Amazon ECS falhe.
Resolução
Observação: se você receber mensagens de erros ao executar comandos da AWS Command Line Interface (AWS CLI), consulte Solução de problemas da AWS CLI. Além disso, verifique se você está usando a versão mais recente da AWS CLI.
Localize um erro de chamada de API
Quando ocorre atividade no Amazon ECS, o AWS CloudTrail registra sua solicitação de API como um evento no Histórico de eventos.
Para visualizar seu Histórico de eventos do AWS CloudTrail e localizar o erro da API, conclua as seguintes etapas:
- Abra o console do CloudTrail.
- No painel de navegação, selecione Histórico de eventos.
- Clique no ícone de engrenagem.
- Em Selecionar colunas visíveis, clique em Código de erro. Em seguida, selecione Confirmar.
- Na página Histórico de eventos, em Atributos de pesquisa, clique em Nome do evento.
- Em Insira um nome de evento, insira a ação que falhou.
Observação: se você não souber o nome do evento, acesse a página Histórico de eventos. Em Atributos de pesquisa, selecione Origem do evento. Em Insira uma origem de evento, selecione ecs.amazonaws.com para filtrar todos os eventos relacionados ao seu serviço do ECS. - Na lista de resultados, selecione os eventos com códigos de erro sobre os quais você deseja saber mais.
Observação: também é possível usar o Amazon Athena para consultar logs do CloudTrail em busca de eventos por código de erro.
Resolva um erro de chamada de API
Realize as seguintes ações com base no erro recebido.
AccessDeniedException
Se seu usuário ou perfil do AWS Identity and Access Management (AWS IAM) não tiver as permissões necessárias, você receberá um erro "AccessDeniedException". O exemplo de erro a seguir indica que o usuário arn:aws:sts::123456789012:assumed-role/test-role/test-session não tem as permissões necessárias para realizar a ação CreateCluster:
"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: CreateCluster on resource: * because no identity-based policy allows the ecs:CreateCluster action"
Para adicionar a permissão apropriada à política de permissão da identidade do IAM, conclua as seguintes etapas:
- Abra o console do IAM.
- No painel de navegação, clique em Perfis, Grupos de usuário ou Usuários com base na identidade do IAM.
- Use o filtro de pesquisa para filtrar as opções de perfil ou usuário. Em seguida, selecione a identidade do IAM que você deseja visualizar.
- Clique na guia Permissões.
- Para visualizar as permissões associadas à identidade do IAM, expanda a política de permissões.
- Na política de permissões, adicione ecs:your-event-name à lista Ações. Em seguida, selecione Permitir ou Efeito. Ou crie uma nova política que permita ecs:your-event-name e anexe a política ao perfil ou usuário do IAM. Para obter mais informações, consulte Edição de políticas gerenciadas pelo cliente (console).
É possível usar o simulador de políticas do IAM para testar uma política que não está anexada a um usuário, grupo de usuários ou perfil do IAM.
ClientException
Se seu cliente do ECS especificar um identificador ou recurso que não é válido ou não existe, você receberá um erro "ClientException". O exemplo de erro a seguir indica que o comando RunTask se refere a uma TaskDefinition que não é válida:
"An error occurred (ClientException) when calling the RunTask operation: TaskDefinition not found."
Verifique se você faz referência aos recursos corretos no comando, nas chamadas de API e no seu código.
ClusterNotFoundException
Se o Amazon ECS não conseguir encontrar o cluster que você especificou em uma operação, você receberá um erro "ClusterNotFoundException". O exemplo de erro a seguir indica que o Amazon ECS não consegue encontrar o cluster que você especificou na operação StartTask:
"An error occurred (ClusterNotFoundException) when calling the StartTask operation: Cluster not found."
Verifique se você faz referência ao nome correto do cluster no comando, nas chamadas de API e no seu código.
Para listar todos os seus clusters atuais do ECS, execute o comando list-clusters da AWS CLI:
aws ecs list-clusters --region example_region
Observação: substitua example_region pela sua região da AWS.
Em seguida, verifique se o cluster ao qual você faz referência na chamada de API existe.
InvalidParameterException
Se um parâmetro inserido em um comando não for válido e a versão da definição da tarefa não existir, você receberá o seguinte erro:
"An error occurred (InvalidParameterException) when calling the RunTask operation: TaskDefinition not found."
O exemplo de comando RunTask a seguir inclui que a definição da tarefa CentOS:3 não existe:
aws ecs run-task --task-definition CentOS:3 --cluster example_cluster --region ap-southeast-2
Observação: no exemplo anterior, substitua example_cluster pelo nome do seu cluster.
O exemplo de erro a seguir corresponde ao comando RunTask anterior:
"An error occurred (InvalidParameterException) when calling the RunTask operation: TaskDefinition not found."
Verifique se os parâmetros em seu comando são válidos.
ServerException
Se um servidor estiver inativo quando você fizer uma chamada de API, você receberá um erro "ServerException". Se você receber esse erro em todas as chamadas de API, o serviço da AWS não está disponível.
Os erros ServerException geralmente são temporários. Espere e faça a chamada de API novamente. Se o problema persistir, entre em contato com o AWS Support e forneça as seguintes informações:
- Forneça o carimbo de data/hora que corresponde ao erro.
- Se você usar a linha de comandos, forneça o comando que retorna o erro.
- Se você usa uma linguagem de programação ou infraestrutura como ferramentas de código que usam o AWS SDK, forneça o bloco de código que retorna o erro.
- Se você usar o Console de gerenciamento da AWS, forneça a URL da página do Console de gerenciamento da AWS e a ação que retorna o erro.
ServiceNotActiveException
Se você atualizar um serviço do Amazon ECS que está inativo, receberá um erro "ServiceNotActiveException". Verifique se o serviço do ECS que você deseja atualizar está no seu cluster do ECS e no estado ATIVO.
Para listar todos os serviços em um cluster, execute o comando list-clusters da AWS CLI:
aws ecs list-services --cluster example_cluster
Observação: substitua example_cluster pelo nome do seu cluster.
Verifique se a saída do comando contém o serviço que você deseja atualizar. Em seguida, execute o comando describe-services para verificar se o serviço está no estado ATIVO:
aws ecs describe-services --services example_service_name --cluster example_cluster
Observação: substitua example_service_name e example_cluster por seus valores.
O exemplo de saída a seguir indica que example-service está no estado ATIVO:
{ "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", ...... }] }
Se seu serviço não estiver no estado ATIVO, verifique se o valor do Número de tarefas do seu serviço do Amazon ECS é maior que zero. Também é possível executar o comando update-service da AWS CLI para atualizar seu valor de Número de tarefas para 1:
aws ecs update-service --cluster example_cluster_name --service example_service_name --desired-count 1
Observação: substitua example_cluster_name e example_service_name por seus valores. É possível definir o valor de contagem desejado para um número maior que zero.
Em seguida, no console do ECS, verifique se seu estado de definição de tarefa está ATIVO. Também é possível executar o comando describe-task-definition:
aws ecs describe-task-definition --task-definition example_taskdefinition
Observação: substitua example_taskdefinition pela sua definição de tarefa.
Verifique seus logs do CloudWatch para ver se há falhas de serviço ou análises de rede que correspondam ao seu erro ServiceNotActiveException.
PlatformTaskDefinitionIncompatibilityException
Se você executar uma tarefa em uma plataforma que não atenda aos recursos necessários da definição da tarefa, receberá um erro "PlatformTaskDefinitionIncompatibilityException". No exemplo de erro a seguir, a versão 1.3.0 da plataforma não oferece suporte aos requisitos do comando create-service da AWS CLI:
"An error occurred (PlatformTaskDefinitionIncompatibilityException) when calling the CreateService operation: One or more of the requested capabilities are not supported."
O exemplo de comando create-service a seguir cria um serviço com um volume do Amazon Elastic File System (Amazon EFS) anexado à versão 1.3.0 da plataforma:
aws ecs create-service \ --cluster example_cluster \ --task-definition example_taskdefinition \ --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
Verifique se a versão da sua plataforma AWS Fargate oferece suporte aos recursos que sua definição de tarefa exige.
PlatformUnknownException
Se você especificar uma versão de plataforma desconhecida ou incorreta ao executar uma tarefa, receberá um erro "PlatformUnknownException". O exemplo de erro a seguir indica que a versão da plataforma especificada em uma operação de criação de serviço não está correta:
"An error occurred (PlatformUnknownException) when calling the CreateService operation: The specified platform does not exist."
O exemplo de comando create-service a seguir contém a versão 1.3 incorreta da plataforma, em vez da versão correta 1.3.0:
aws ecs create-service \ --cluster example_cluster\ --task-definition example_taskdefinition \ --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
Verifique se a versão da plataforma que você especifica ao executar uma tarefa está correta. Para obter mais informações, consulte Versões da plataforma do Fargate para o Amazon ECS e Log de alterações da versão da plataforma Windows para o Fargate.
ServiceNotFoundException
O erro "ServiceNotFoundException" ocorre quando o serviço especificado do ECS não existe em seu comando ou código. Verifique se o nome do serviço em seu comando ou código está correto e, em seguida, confirme se o serviço está no cluster. Para visualizar todos os serviços no cluster, execute o comando list-clusters da AWS CLI:
aws ecs list-services --cluster example_cluster
Observação: substitua example_cluster pelo seu cluster.
UnsupportedFeatureException
O erro "UnsupportedFeatureException" ocorre quando você inicia uma tarefa do Fargate em uma região da AWS em que o Fargate não oferece suporte ao seu contêiner. Para obter mais informações, consulte Regiões com suporte para Amazon ECS no AWS Fargate.
Solucionar problemas de API em aplicações
É possível receber as seguintes respostas comuns do código de status HTTP 5## ao acessar a aplicação hospedada em uma tarefa do ECS:
- Um erro "HTTP 500 - Internal server" ocorre se uma aplicação encontra uma condição inesperada, como um erro. Ou, se você configurar incorretamente uma aplicação, receberá esse erro.
- Um erro "HTTP 503 - Service unavailable" ocorre se uma tarefa do ECS tiver um workload pesado. Ou, se a aplicação dentro da sua tarefa estiver inativa para manutenção, você receberá esse erro.
Analise os logs da aplicação em suas tarefas do ECS no Amazon CloudWatch Logs. Cada definição de tarefa corresponde a um fluxo de logs que contém o log da aplicação da tarefa. Para visualizar informações sobre o grupo de logs e o fluxo de logs da sua definição de tarefa, execute o comando describe-task-definition:
aws ecs describe-task-definition --task-definition example_taskdefinition
Observação: substitua example_task_definition pela sua definição de tarefa.
Informações relacionadas
- Tópicos
- Containers
- Idioma
- Português
