Come posso risolvere i problemi relativi al passaggio delle variabili di ambiente alle attività Amazon ECS?

Breve descrizione

È possibile passare una variabile di ambiente all'interno di un’attività Amazon ECS in uno dei seguenti modi:

• Passaggio della variabile come oggetto environmentFiles all'interno di un bucket Amazon Simple Storage Service (Amazon S3).
• Archiviazione della variabile all'interno dell’Archivio dei parametri AWS Systems Manager.
• Archiviazione della variabile nella definizione dell'attività ECS.
• Archiviazione della variabile all'interno di AWS Secrets Manager.

Nota: Per una sicurezza ottimale, è consigliabile utilizzare Archivio dei parametri o Secrets Manager per archiviare i dati sensibili come variabile di ambiente. Durante il passaggio delle variabili di ambiente con uno dei metodi precedenti, è possibile visualizzare i seguenti errori:

Archivio dei parametri

"Fetching secret data from SSM Parameter Store in region: AccessDeniedException: User: arn:aws:sts::123456789:assumed-role/ecsExecutionRole/f512996041234a63ac354214 is not authorized to perform: ssm:GetParameters on resource: arn:aws:ssm:ap-south-1:12345678:parameter/status code: 400, request id: e46b40ee-0a38-46da-aedd-05f23a41e861"

-oppure-

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

Secrets Manager

"ResourceInitializationError error"

-oppure-

"AccessDenied error on Amazon Elastic Compute Cloud (Amazon EC2)"

Per risolvere questi errori, consulta Come posso risolvere i problemi relativi ai segreti di AWS Secrets Manager in Amazon ECS?

Amazon S3

"ResourceInitializationError: failed to download env files: file download command: non empty error stream"

I problemi riscontrati durante il passaggio delle variabili di ambiente alle attività Amazon ECS possono avere le seguenti cause:

• Il ruolo di esecuzione delle attività Amazon ECS non dispone delle autorizzazioni AWS Identity and Management (IAM) richieste.
• Ci sono problemi nella configurazione della rete.
• L'applicazione non è in grado di leggere la variabile di ambiente.
• Il formato della variabile nella definizione di container non è corretto.
• La variabile di ambiente non si aggiorna automaticamente.

Per risolvere gli errori relativi al mancato avvio di attività Amazon ECS, usa il runbook AWSSupport-TroubleshootECSTaskFailedToStart. Quindi, completa i passaggi corrispondenti per la risoluzione dei problemi.

Soluzione

Importante:

• Usa il runbook AWSSupport-TroubleshootECSTaskFailedToStart nella stessa regione AWS in cui si trovano le risorse del cluster ECS.
• Quando utilizzi il runbook, devi usare l'ID dell'ultima attività non riuscita. Se l'attività non riuscita fa parte di un servizio Amazon ECS, utilizza l'ultima attività non riuscita del servizio. L'attività non riuscita deve essere visibile in ECS:DescribeTasks durante l'automazione. Per impostazione predefinita, le attività ECS interrotte sono visibili per 1 ora dopo il passaggio allo stato Interrotta. L'utilizzo dell'ID dell’ultima attività non riuscita impedisce alla pulizia dello stato dell'attività di interrompere l'analisi durante l'automazione.

Per istruzioni su come avviare il runbook, consulta AWSSupport-TroubleshootECSTaskFailedToStart. In base all'output dell'automazione, utilizza una delle seguenti procedure manuali per la risoluzione dei problemi.

Il tuo ruolo di esecuzione dell’attività Amazon ECS non dispone delle autorizzazioni IAM richieste

Se utilizzi variabili di ambiente all'interno dell’Archivio dei parametri o di Secrets Manager, esamina gli eventi di AWS CloudTrail per una delle seguenti chiamate API:

GetParameters per Archivio dei parametri

-oppure-

GetSecretValue per Secrets Manager

Se noti l'errore AccessDenied per il ruolo di esecuzione delle attività negli eventi CloudTrail, aggiungi manualmente le autorizzazioni richieste come policy inline al ruolo IAM di esecuzione delle attività ECS. Puoi anche creare una policy gestita dal cliente e aggiungerla al ruolo di esecuzione delle attività ECS.

Se utilizzi Secrets Manager, includi le seguenti autorizzazioni per il ruolo di esecuzione delle attività:

{  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "kms:Decrypt"
      ],
      "Resource": [
        "arn:aws:secretsmanager:example-region:11112222333344445555:secret:example-secret",
        "arn:aws:kms:example-region:1111222233334444:key/example-key-id"
      ]
    }
  ]
}

Se utilizzi Archivio dei parametri, includi le seguenti autorizzazioni per il ruolo di esecuzione delle attività:

{  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameters",
        "secretsmanager:GetSecretValue",
        "kms:Decrypt"
      ],
      "Resource": [
        "arn:aws:ssm:example-region:1111222233334444:parameter/example-parameter",
        "arn:aws:secretsmanager:example-region:1111222233334444:secret:example-secret",
        "arn:aws:kms:example-region:1111222233334444:key/example-key-id"
      ]
    }
  ]
}

Puoi usare un bucket S3 per archiviare la variabile di ambiente come file .env. Tuttavia, devi aggiungere manualmente le seguenti autorizzazioni come policy inline al ruolo di esecuzione delle attività:

{  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::example-bucket/example-folder/example-env-file"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::example-bucket"
      ]
    }
  ]
}

Ci sono problemi nella configurazione della rete

Se l’attività ECS si trova in una sottorete privata, verifica i seguenti aspetti:

• Assicurati che il gruppo di sicurezza per l'attività o il servizio consenta il traffico in uscita sulla porta 443.
• Se utilizzi un endpoint VPC, assicurati che la lista di controllo degli accessi (ACL) alla rete consenta il traffico in uscita sulla porta 443.
• Verifica la connettività a Systems Manager/Secrets Manager e all'endpoint Amazon S3. A tale scopo, utilizza il comando telnet.
• Se utilizzi un gateway NAT, assicurati che l’attività abbia un percorso predefinito verso il gateway NAT.
• Definisci gli endpoint VPC per le attività. Verifica di disporre degli endpoint VPC necessari per Secrets Manager/Systems Manager Archivio dei parametri e Amazon S3.

Se utilizzi un endpoint VPC, verifica i seguenti aspetti:

• Il gruppo di sicurezza per l'endpoint VPC consente il traffico in uscita dall'attività o dal servizio sulla porta 443.
• Associa l'endpoint VPC al VPC corretto.
• Attiva gli attributi VPC enableDnsHostnames e enableDnsSupport.

Se l’attività ECS si trova in una sottorete pubblica, verifica i seguenti aspetti:

• È necessario attivare un indirizzo IP pubblico per l'attività.
• Assicurati che il gruppo di sicurezza del VPC abbia accesso in uscita sulla porta 443 a Internet.
• La configurazione dell’ACL di rete consente a tutto il traffico di entrare e uscire dalle sottoreti verso Internet.

L'applicazione non è in grado di leggere la variabile di ambiente

Per verificare se sono state inserite le variabili di ambiente corrette all'interno del container delle attività, procedi come segue:

1. Elenca tutte le variabili di ambiente esposte all'interno del container.
2. Verifica che questo elenco includa le variabili di ambiente che hai definito nella definizione dell'attività o nel file .env in S3.

Se utilizzi i tipi di avvio Amazon EC2 o AWS Fargate, è consigliabile utilizzare la funzionalità ECS Exec. Puoi usare questa funzionalità per eseguire comandi o inviare una shell a un container in esecuzione su un'istanza Amazon EC2 o Fargate. Dopo aver abilitato questa funzionalità, esegui il seguente comando per interagire con il container:

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

Se utilizzi il tipo di avvio Amazon EC2, puoi anche utilizzare il comando Docker exec per interagire con il container. In questo caso, completa i seguenti passaggi: Connettiti all'istanza di container in cui è in esecuzione l'attività. Quindi, esegui il seguente comando Docker per trovare l'ID container del container dell’attività:

docker container ps

Per interagire con il container, esegui quanto segue

docker exec -it example-container-id bash

Nota: Seleziona la shell in base alla shell predefinita del container.

Dopo aver stabilito la connessione con il container, esegui il comando env sul container per ottenere l'elenco completo delle variabili di ambiente. Esamina questo elenco per accertarti che le variabili di ambiente definite nella definizione dell'attività o nel file .env siano presenti.

Il formato della variabile nella definizione del container non è corretto

Le variabili di ambiente all'interno della definizione del container devono essere definite come oggetti KeyValuePair:

"environment": [{    "name": "foo",
    "value": "bar"
}]

Assicurati di utilizzare questo formato anche quando definisci le variabili di ambiente nei file .env.

La variabile di ambiente non si aggiorna automaticamente

Quando aggiorni la variabile di ambiente nel file .env, la variabile non si aggiorna automaticamente nel container in esecuzione.
Per inserire i valori aggiornati delle variabili di ambiente nell’attività, aggiorna il servizio eseguendo il seguente comando:

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

Se utilizzi variabili di ambiente nella definizione del container, devi creare una nuova definizione dell’attività per aggiornare le variabili di ambiente aggiornate. Con questa nuova definizione dell’attività, puoi creare una nuova attività o aggiornare il servizio ECS:

`aws ecs update-service --cluster example-cluster --service example-service --task-definition <family:revision>`;

Nota: Considera i seguenti aspetti durante il passaggio delle variabili di ambiente all’attività:

• Le variabili di ambiente specificate con il parametro ambiente in una definizione di container hanno la precedenza sulle variabili contenute in un file di ambiente.
• Se vengono specificati più file di ambiente che contengono la stessa variabile, questi vengono elaborati nell'ordine di immissione. Viene utilizzato il primo valore della variabile, mentre i valori successivi delle variabili duplicate vengono ignorati. È consigliabile utilizzare nomi univoci per le variabili.
• Se viene specificato un file di ambiente in sostituzione del container, viene utilizzato il file. Qualsiasi altro file di ambiente specificato in una definizione di container viene ignorato.
• Le variabili di ambiente sono disponibili per i processi PID 1 in un container del file /proc/1/environ. Se il container esegue più processi o processi di inizializzazione, come script wrapper o supervisord, la variabile di ambiente non è disponibile per i processi non PID 1.

Informazioni correlate

Passing environment variables to a container