Como soluciono problemas ao passar variáveis de ambiente para minha tarefa do Amazon ECS?

Breve descrição

Ao passar uma variável de ambiente ou dados sigilosos para sua tarefa, você pode receber um dos seguintes erros com base na sua configuração.

AWS Secrets Manager

“Erro ResourceInitializationError” ou “Erro AccessDenied no Amazon Elastic Compute Cloud (Amazon EC2)”.

Para resolver esses problemas, consulte Como soluciono problemas relacionados ao AWS Secrets Manager no Amazon ECS?

Volumes do Amazon Elastic Block Store (Amazon EBS) ou sidecars

“O ECS não conseguiu assumir o perfil de infraestrutura do ECS configurada ‘arn:aws:iam: :111122223333:role/ecsinfrastructureRole’. Verifique se o perfil que está sendo aprovado tem a relação de confiança adequada com o Amazon ECS” ou “O ECS excedeu o tempo limite ao configurar o anexo do volume do EBS à sua tarefa.”

Para resolver esses problemas, consulte Motivos de status para a vinculação de volumes do Amazon EBS às tarefas do Amazon ECS.

Amazon Simple Storage Service (Amazon S3)

“ResourceInitializationError: failed to download env files: file download command: non empty error stream”.

Para resolver esse problema, conclua as etapas de resolução a seguir.

Parameter Store, um recurso do AWS Systems Manager

“Obtendo dados secretos do SSM Parameter Store na região: AccessDeniedException: Usuário: arn:aws:sts: :123456789:assumed-role/ecsExecutionRole/f512996041234a63ac354214 não está autorizado a executar: ssm:GetParameters no recurso: arn:aws:ssm:ap-south- 1:12345678:código de parâmetro/status: 400, id da solicitação: e46b40ee-0a38-46da-aedd-05f23a41e861”. Ou “ResourceInitializationError: unable to pull secrets or registry auth: execution resource retrieval failed: unable to retrieve secrets from ssm: service call has been retried 5 time(s): RequestCanceled”.

Para resolver esses problemas, conclua as seguintes etapas.

Observação: é uma prática recomendada de segurança armazenar dados sigilosos nos segredos do Secrets Manager ou nos parâmetros do Parameter Store.

Resolução

Observação: Se você receber erros ao executar comandos da AWS Command Line Interface (AWS CLI), consulte Solução de erros da AWS CLI. Além disso, verifique se você está usando a versão mais recente da AWS CLI.

Determine a causa do problema

Use o runbook AWSSupport-TroubleshootECSTaskFailedToStart na mesma região da AWS em que seus recursos de cluster do Amazon ECS estão localizados. Além disso, use o ID da tarefa que falhou mais recentemente. Se a tarefa com falha fizer parte do serviço Amazon ECS, use a tarefa que falhou mais recentemente no serviço. A tarefa com falha deve estar visível em ECS:DescribeTasks durante a execução da automação. Por padrão, as tarefas interrompidas do ECS ficam visíveis por 1 hora após entrarem no estado Interrompido.

Com base na saída da automação, use uma das seguintes etapas manuais de solução de problemas.

Seu perfil de execução de tarefas do Amazon ECS não tem as permissões de IAM necessárias

Se você estiver usando variáveis de ambiente dentro do Parameter Store ou do Secrets Manage, analise os eventos do AWS CloudTrail para as seguintes chamadas de API:

• GetParameters para Parameter Store
• GetSecretValue para Secrets Manager

Se você receber o erro AccessDenied para o perfil de execução da tarefa, deverá adicionar manualmente as permissões necessárias como uma política em linha com o perfil. Também é possível criar uma política gerenciada personalizada que você adiciona ao seu perfil de execução de tarefas do Amazon ECS.

Se você usar um bucket do S3 para armazenar a variável de ambiente como um arquivo .env, adicione as permissões necessárias para o Amazon S3 ao perfil de execução da tarefa.

Há problemas com sua configuração de rede

Se sua tarefa estiver em uma sub-rede privada, verifique as configurações a seguir:

• O grupo de segurança da tarefa ou serviço permite tráfego de saída na porta 443.
• Se você usa um gateway NAT, sua tarefa deve ter uma rota padrão para o gateway NAT.
• Suas tarefas usam os endpoints de nuvem privada virtual (VPC) necessários para Secrets Manager, Parameter Store ou Amazon S3.

Use o comando telnet para verificar a conectividade com o Systems Manager, Secrets Manager ou o endpoint Amazon S3.

Além disso, verifique as seguintes configurações de endpoint da VPC:

• O grupo de segurança do seu endpoint da VPC permite o tráfego de saída da tarefa ou do serviço na porta 443.
• A lista de controle de acesso à rede (ACL de rede) permite tráfego de saída na porta 443.
• Associe o endpoint da VPC à VPC correta.
• Você ativou os atributos de nomes de host DNS e resolução DNS da VPC.

Se sua tarefa do Amazon ECS estiver em uma sub-rede pública, verifique as seguintes configurações:

• Você ativou um endereço IP público para a tarefa.
• O grupo de segurança da sua VPC permite acesso externo à Internet na porta 443.
• A ACL de rede permite todo o tráfego de entrada e saída entre as sub-redes e a Internet.

Sua aplicação não consegue ler a variável de ambiente

Para verificar se as variáveis de ambiente corretas são preenchidas em seu contêiner de tarefas, use o ECS Exec para listar todas as variáveis de ambiente em seu contêiner. Ative o ECS Exec e execute o seguinte comando para interagir com seu contêiner:

aws ecs execute-command --cluster cluster-name \
    --task task-id \
    --container container-name \
    --interactive \
    --command "/bin/sh"  

Observação: substitua cluster-name pelo nome do cluster, task-id pelo ID da tarefa e container-name pelo nome do contêiner.

Exemplo de saída:

The Session Manager plugin was installed successfully. Use the AWS CLI to start a session.


Starting session with SessionId: ecs-execute-command-hlei32fctyur2bn63rhe2uraaq
sh-5.2#

Em seguida, execute o comando env para listar todas as variáveis de ambiente:

sh-5.2# env

Exemplo de saída:

sh-5.2# env
AWS_EXECUTION_ENV=AWS_ECS_FARGATE
AWS_DEFAULT_REGION=us-east-1
AWS_REGION=us-east-1
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
_=/usr/bin/env

Se você usar o tipo de inicialização do Amazon EC2, também é possível usar o comando Docker exec para interagir com seu contêiner. Para usar o Docker exec, conclua as etapas a seguir:

1. Conecte-se à instância de contêiner em que sua tarefa está sendo executada.

2. Execute o seguinte comando do Docker para encontrar o ID do contêiner:

   docker container ps

3. Para abrir o contêiner, execute o seguinte comando do Docker:

   docker exec -it example-container-id bash

   Observação: substitua example-container-id pelo ID do contêiner. Além disso, selecione o shell com base no shell padrão do seu contêiner.

4. Execute o comando env em seu contêiner para listar todas as variáveis de ambiente.

Certifique-se de que as variáveis de ambiente que você definiu na definição da tarefa ou no arquivo .env estejam na lista de variáveis.

O formato da variável na definição do contêiner está incorreto

Ao definir variáveis de ambiente na definição do contêiner, você deve definir as variáveis de ambiente como objetos de par de valores-chave:

"environment": [
    {
        "name": "variable",    
        "value": "value"
    }
]

Certifique-se de usar esse formato ao definir também as variáveis de ambiente em seus arquivos .env.

A tarefa não atualiza automaticamente a variável de ambiente

A tarefa não atualiza automaticamente as variáveis de ambiente em seu contêiner em execução que você atualiza em seu arquivo .env ou segredo.

Para adicionar as variáveis ambientais atualizadas à sua instância de contêiner, execute o seguinte comando update-service:

aws ecs update-service --cluster example-cluster --service example-service --force-new-deployment

Observação: substitua example-cluster pelo nome do seu cluster e example-service pelo nome do seu serviço.

Se você usar variáveis de ambiente em sua definição de contêiner, deverá criar uma nova definição de tarefa para atualizar as variáveis de ambiente. Em seguida, execute o seguinte comando update-service para usar a nova definição de tarefa para criar uma nova tarefa ou atualizar seu serviço Amazon ECS:

aws ecs update-service --cluster example-cluster --service example-service --task-definition family:revision

Observação: substitua example-cluster pelo nome do cluster, example-service pelo nome do serviço e family:revision pela nova definição de tarefa.

Quando você passa variáveis de ambiente para sua tarefa, o Amazon ECS usa as configurações a seguir:

• As variáveis de ambiente que usam o parâmetro de ambiente em uma definição de contêiner têm precedência sobre as variáveis em um arquivo de ambiente.
• Se você especificar vários arquivos de ambiente e eles usarem a mesma variável, eles serão processados na ordem de entrada. O Amazon ECS usa o primeiro valor da variável e ignora os valores subsequentes das variáveis duplicadas. É uma prática recomendada usar nomes de variáveis exclusivos.
• Se você especificar um arquivo de ambiente como uma substituição de contêiner, o Amazon ECS usará esse arquivo e ignorará outros arquivos de ambiente na definição do contêiner.
• As variáveis de ambiente estão disponíveis para os processos do PID 1 em um contêiner do arquivo /proc/1/environ. Se o contêiner executar vários processos ou processos de inicialização, como wrapper script ou supervisord, a variável de ambiente não estará disponível para processos não PID 1.

Informações relacionadas

Passar dados sigilosos para um contêiner do Amazon ECS