Comment résoudre des problèmes liés à l’ajout de variables d’environnement à ma tâche Amazon ECS ?

Brève description

Lorsque vous transmettez une variable d'environnement ou des données sensibles dans votre tâche, l'une des erreurs suivantes peut s'afficher en fonction de votre configuration.

AWS Secrets Manager

« erreur ResourceInitializationError » ou « erreur AccessDenied on Amazon Elastic Compute Cloud (Amazon EC2) ».

Pour résoudre ces erreurs, consultez la section Comment résoudre les problèmes liés aux secrets AWS Secrets Manager dans Amazon ECS ?

Volumes ou sidecars Amazon Elastic Block Store (Amazon EBS)

« ECS was unable to assume the configured ECS Infrastructure Role 'arn:aws:iam::111122223333:role/ecsInfrastructureRole'. Please verify that the role being passed has the proper trust relationship with Amazon ECS" or "ECS timed out while configuring the EBS volume attachment to your Task. (ECS n'a pas pu endosser le rôle d'infrastructure ECS configuré 'arn:aws:iam::111122223333:role/ecsInfrastructureRole'. Vérifiez que le rôle transféré entretient une relation de confiance appropriée avec Amazon ECS » ou « ECS timed out while configuring the EBS volume attachment to your Task. » (ECS a expiré lors de la configuration de l’attachement de volume EBS à votre tâche.)

Pour résoudre ces problèmes, consultez la section Raisons du statut de l'attachement de volume Amazon EBS aux tâches Amazon ECS.

Amazon Simple Storage Service (Amazon S3)

« ResourceInitializationError: failed to download env files: file download command: non empty error stream » (ResourceInitializationError : échec de téléchargement des fichiers env : commande de téléchargement de fichier : flux d’erreur non vide).

Pour résoudre ce problème, suivez les étapes de résolution suivantes.

Parameter Store, une fonctionnalité d'AWS Systems Manager

« 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 » (Extraction de données secrètes depuis SSM Parameter Store dans la région : AccessDeniedException : L’utilisateur : arn:aws:sts::123456789:assumed-role/ecsExecutionRole/f512996041234a63ac354214 n’est pas autorisé à exécuter : ssm:GetParameters sur la ressource : arn:aws:ssm:ap-south-1:12345678:parameter/status code : 400, ID de requête : 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 » (ResourceInitializationError : impossible d’extraire les secrets ou l’authentification de registre : échec de l’extraction des ressources d’exécution : impossible d’extraire les secrets de ssm : l’appel de service a fait l’objet de 5 nouvelles tentatives : RequestCanceled).

Pour résoudre ces problèmes, effectuez les étapes de résolution suivantes.

Remarque : L'une des bonnes pratiques de sécurité consiste à stocker des données sensibles dans les secrets de Secrets Manager ou dans les paramètres de Parameter Store.

Résolution

Remarque : Si des erreurs surviennent lorsque vous exécutez des commandes de l'interface de la ligne de commande AWS (AWS CLI), consultez la section Résoudre des erreurs liées à l’AWS CLI. Vérifiez également que vous utilisez bien la version la plus récente de l’AWS CLI.

Déterminer la cause du problème

Utilisez le dossier d’exploitation AWSSupport-TroubleshootECSTaskFailedToStart dans la même région AWS où sont situées les ressources de votre cluster Amazon ECS. Utilisez également l'ID de tâche ayant échoué le plus récemment. Si la tâche ayant échoué fait partie du service Amazon ECS, utilisez la dernière tâche ayant échoué dans le service. La tâche ayant échoué doit être visible dans ECS:DescribeTasks pendant l’automatisation. Par défaut, les tâches ECS arrêtées restent visibles pendant 1 heure après être passées à l'état Arrêté.

En fonction des résultats de l'automatisation, utilisez l'une des étapes de dépannage manuel suivantes.

Votre rôle d’exécution de tâches Amazon ECS ne dispose pas des autorisations IAM requises

Si vous utilisez des variables d’environnement dans Parameter Store ou Secrets Manager, examinez les événements AWS CloudTrail pour les appels d’API suivants :

• GetParameters pour Parameter Store
• GetSecretValue pour Secrets Manager

Si l'erreur AccessDenied s'affiche pour le rôle d'exécution de la tâche, vous devez ajouter manuellement les autorisations requises en tant que politique en ligne au rôle. Vous pouvez également créer une politique gérée personnalisée que vous ajoutez à votre rôle d'exécution des tâches Amazon ECS.

Si vous utilisez un compartiment S3 pour stocker la variable d'environnement sous forme de fichier .env, ajoutez les autorisations requises pour Amazon S3 au rôle d'exécution de tâche.

Il existe des problèmes liés à votre configuration réseau

Si votre tâche ECS se trouve dans un sous-réseau privé, vérifiez les configurations suivantes :

• Le groupe de sécurité de la tâche ou du service autorise le trafic sortant sur le port 443.
• Si vous utilisez une passerelle NAT, votre tâche doit disposer d'une route par défaut vers la passerelle NAT.
• Vos tâches utilisent les points de terminaison du cloud privé virtuel (VPC) requis pour Secrets Manager, Parameter Store ou Amazon S3.

Utilisez la commande telnet pour vérifier la connectivité à System Manager, à Secrets Manager ou au point de terminaison Amazon S3.

Vérifiez également les configurations de point de terminaison de VPC suivantes :

• Le groupe de sécurité de votre point de terminaison de VPC autorise le trafic sortant de la tâche ou du service sur le port 443.
• La liste de contrôle d'accès réseau (ACL réseau) autorise le trafic sortant sur le port 443.
• Vous avez associé le point de terminaison de VPC au VPC approprié.
• Vous avez activé les noms d'hôte DNS et les attributs de VPC de résolution DNS.

Si votre tâche Amazon ECS se trouve dans un sous-réseau public, vérifiez les configurations suivantes :

• Vous avez activé une adresse IP publique pour la tâche.
• Le groupe de sécurité de votre VPC autorise l’accès sortant vers Internet via le port 443.
• L'ACL réseau autorise tout le trafic entrant et sortant entre les sous-réseaux et Internet.

Votre application ne peut pas lire la variable d'environnement

Pour vérifier si les variables d'environnement correctes sont renseignées dans votre conteneur de tâches, utilisez ECS Exec pour répertorier toutes les variables d'environnement de votre conteneur. Activez ECS Exec, puis exécutez la commande suivante pour interagir avec votre conteneur :

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

Remarque : Remplacez cluster-name par le nom de votre cluster, task-id par votre ID de tâche et container-name par le nom de votre conteneur.

Exemple de sortie :

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#

Exécutez ensuite la commande env pour répertorier toutes les variables d'environnement :

sh-5.2# env

Exemple de sortie :

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

Si vous utilisez le type de lancement Amazon EC2, vous pouvez également utiliser la commande d’exécution Docker pour interagir avec votre conteneur. Pour utiliser Docker exec, procédez comme suit :

1. Connectez-vous à l’instance de conteneur sur laquelle votre tâche est exécutée.

2. Exécutez la commande Docker suivante pour trouver l'ID du conteneur :

   docker container ps

3. Pour ouvrir le conteneur, exécutez la commande Docker suivante :

   docker exec -it example-container-id bash

   Remarque : Remplacez example-container-id par l'ID de votre conteneur. Sélectionnez également le shell en fonction du shell par défaut de votre conteneur.

4. Exécutez la commande env sur votre conteneur pour répertorier toutes les variables d'environnement.

Assurez-vous que les variables d'environnement que vous avez définies dans la définition de tâche ou dans le fichier .env figurent dans la liste des variables.

Le format de la variable est incorrect dans la définition du conteneur

Lorsque vous définissez des variables d'environnement dans la définition de conteneur, vous devez définir les variables d'environnement comme des objets de paire clé-valeur :

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

Vous devez également utiliser ce format lorsque vous définissez les variables d’environnement dans vos fichiers .env.

La tâche n'actualise pas automatiquement la variable d'environnement

La tâche n'actualise pas automatiquement les variables d'environnement de le conteneur exécuté que vous mettez à jour dans votre fichier .env ou votre secret.

Pour ajouter les variables d'environnement mises à jour à votre instance de conteneur, exécutez la commande update-service suivante :

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

Remarque : Remplacez example-cluster par le nom de votre cluster et example-service par le nom de votre service.

Si vous utilisez des variables d’environnement dans votre définition de conteneur, vous devez créer une nouvelle définition de tâche pour mettre à jour les variables d’environnement mises à jour. Exécutez ensuite la commande update-service suivante pour utiliser la nouvelle définition de tâche afin de créer une nouvelle tâche ou de mettre à jour votre service Amazon ECS :

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

Remarque : Remplacez example-cluster par le nom de votre cluster, example-service par le nom de votre service et family:revision par votre nouvelle définition de tâche.

Lorsque vous transmettez des variables d'environnement à votre tâche, Amazon ECS utilise les configurations suivantes :

• Les variables d'environnement qui utilisent le paramètre environnement dans une définition de conteneur ont priorité sur les variables d'un fichier d'environnement.
• Si vous spécifiez plusieurs fichiers d’environnement et qu’ils contiennent la même variable, ils sont traités dans l’ordre de saisie. Amazon ECS utilise la première valeur de la variable et ignore les valeurs suivantes des variables dupliquées. Il est recommandé d’utiliser des noms de variables uniques.
• Si vous spécifiez un fichier d'environnement en tant que remplacement de conteneur, Amazon ECS utilise ce fichier et ignore les autres fichiers d'environnement dans la définition de conteneur.
• Les variables d’environnement sont disponibles pour les processus PID 1 dans un conteneur issu du fichier /proc/1/environ. Si le conteneur exécute plusieurs processus ou des processus d’initialisation (tels qu’un script encapsuleur ou un superviseur), la variable d’environnement n’est pas disponible pour les processus non PID 1.

Informations connexes

Transmettre des données sensibles à un conteneur Amazon ECS