¿Cómo soluciono los problemas al transferir variables de entorno a mi tarea de Amazon ECS?

Descripción corta

Puede transferir una variable de entorno dentro de su tarea de Amazon ECS de una de las siguientes maneras:

• Transfiera la variable como un objeto environmentFiles dentro de un bucket de Amazon Simple Storage Service (Amazon S3).
• Almacene la variable en AWS Systems Manager Parameter Store.
• Almacene la variable en la definición de la tarea de ECS.
• Guarde la variable en AWS Secrets Manager.

Nota: se recomienda utilizar Parameter Store o Secrets Manager para almacenar la información confidencial como una variable de entorno.

Al transferir las variables de entorno según uno de los métodos anteriores, es posible que se produzcan los siguientes errores:

Parameter Store:

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 (Obteniendo datos del secreto desde SSM Parameter Store en la región: AccessDeniedException: Usuario: arn:aws:sts::123456789:assumed-role/ecsExecutionRole/f512996041234a63ac354214 no autorizado para ejecutar: ssm:GetParameters sobre el recurso: rn:aws:ssm:ap-south-1:12345678:parameter/status código: 400, id de solicitud: e46b40ee-0a38-46da-aedd-05f23a41e861)

o

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: no se pueden extraer secretos ni la autenticación del registro: error en la recuperación de recursos de ejecución: no se pueden recuperar los secretos de ssm: la llamada de servicio se ha reintentado 5 veces: RequestCanceled)

Secrets Manager:

Error ResourceInitialization

o

Error de AccessDenied en Amazon Elastic Compute Cloud (EC2)

Para resolver estos errores, consulte ¿Cómo soluciono los problemas relacionados con los secretos de AWS Secrets Manager en Amazon ECS?

Simple Storage Service (Amazon S3):

ResourceInitializationError: failed to download env files: file download command: non empty error stream (ResourceInitializationError: no se pudieron descargar los archivos env: comando de descarga de archivos: transmisión de error no vacía)

Es posible que tenga problemas al transferir variables de entorno a sus tareas de Amazon ECS debido a las siguientes razones:

• Su rol de ejecución de tareas de Amazon ECS no tiene los permisos requeridos de AWS Identity and Management (IAM).
• Hay problemas con la configuración de la red.
• La aplicación no puede leer la variable de entorno.
• El formato de la variable en la definición del contenedor es incorrecto.
• La variable de entorno no se actualiza automáticamente.

Resolución

Su rol de ejecución de tareas de Amazon ECS no tiene los permisos de IAM requeridos

Si utiliza variables de entorno dentro de Parameter Store o Secrets Manager, revise los eventos de AWS CloudTrail para cualquiera de las siguientes llamadas a la API:

GetParameters, en el caso de Parameter Store

o

GetSecretValue, en el caso de Secrets Manager

Si observa el error AccessDenied para el rol de ejecución de tareas en los eventos de CloudTrail, agregue manualmente los permisos requeridos como una política en línea a su rol de IAM de ejecución de tareas de ECS. También puede crear una política administrada por el cliente y agregarla a su rol de ejecución de tareas de ECS.

Si usa Secrets Manager, incluya los siguientes permisos para el rol de ejecución de tareas:

{
  "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"
      ]
    }
  ]
}

Si utiliza Parameter Store, incluya los siguientes permisos para su rol de ejecución de tareas:

{
  "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"
      ]
    }
  ]
}

Para usar un bucket de S3 con el objetivo de almacenar la variable de entorno como un archivo .env, agregue manualmente los siguientes permisos como una política insertada para el rol de ejecución de tareas:

{
  "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"
      ]
    }
  ]
}

Hay problemas con la configuración de la red

Si la tarea de ECS se encuentra en una subred privada, verifique lo siguiente:

• Asegúrese de que el grupo de seguridad de la tarea o el servicio permita el tráfico de salida en el puerto 443.
• Si usa un punto de conexión de VPC, asegúrese de que la ACL de red permita el tráfico de salida en el puerto 443.
• Compruebe la conectividad con Systems Manager/Secrets Manager y el punto de conexión de Simple Storage Service (Amazon S3) mediante el comando telnet.
• Si utiliza una puerta de enlace NAT, asegúrese de que su tarea tenga una ruta predeterminada a la puerta de enlace NAT.
• Asegúrese de haber definido los puntos de conexión de VPC para sus tareas. Si definió los puntos de conexión de VPC, asegúrese de tener los puntos de conexión de VPC necesarios para Secrets Manager/Systems Manager Parameter Store y S3.
• Si utiliza un punto de conexión de VPC, asegúrese de lo siguiente:

• El grupo de seguridad del punto de conexión de VPC permite la salida del tráfico de la tarea o el servicio en el puerto 443.
• El punto de conexión de VPC está asociado a la VPC correcta.
• Los atributos de la VPC enableDnsHostnames y enableDnsSupport están activados.

Si la tarea de ECS se encuentra en una subred pública, verifique lo siguiente:

• Asegúrese de que la tarea tenga habilitada una dirección IP pública.
• Asegúrese de que el grupo de seguridad de la VPC tenga acceso saliente a Internet en el puerto 443.
• Asegúrese de que la configuración de ACL de red permita que todo el tráfico entre y salga de las subredes a Internet.

La aplicación no puede leer la variable de entorno

Para comprobar si las variables de entorno correctas se rellenan dentro del contenedor de tareas, haga lo siguiente:

1. Enumere todas las variables de entorno que se exponen dentro del contenedor.
2. Compruebe que esta lista incluye las variables de entorno que definió en la definición de la tarea o en el archivo .env en S3.

Si utiliza los tipos de lanzamiento de Amazon EC2 o AWS Fargate, se recomienda utilizar la característica ECS Exec. Puede utilizar esta característica para ejecutar comandos en un contenedor que se ejecuta en una instancia de Amazon EC2 o Fargate. Después de habilitar esta característica, ejecute el siguiente comando para interactuar con el contenedor.

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

Si utiliza el tipo de lanzamiento de Amazon EC2, también puede usar el comando exec de Docker para interactuar con su contenedor. En ese caso, haga lo siguiente:

Conéctese a la instancia de contenedor en la que se ejecuta la tarea. A continuación, ejecute el siguiente comando de Docker para encontrar el ID de contenedor de su contenedor de tareas.

docker container ps

Ejecute el siguiente comando para interactuar con el contenedor:

docker exec -it example-container-id bash

Nota: seleccione el shell de acuerdo con el shell predeterminado de su contenedor.

Después de establecer la conexión con el contenedor, ejecute el comando env en su contenedor para obtener la lista completa de las variables de su entorno. Revise esta lista para asegurarse de que las variables de entorno que definió en la definición de tarea o en el archivo .env estén presentes.

El formato de la variable en la definición del contenedor es incorrecto

Cuando defina variables de entorno dentro de la definición de contenedor, asegúrese de definir las variables de entorno como objetos KeyValuePair de forma similar a la siguiente:

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

Asegúrese de usar este formato cuando defina también las variables de entorno en sus archivos .env.

La variable de entorno no se actualiza automáticamente

Cuando actualiza la variable de entorno en el archivo .env, la variable no se actualiza automáticamente en el contenedor en ejecución.

Para inyectar los valores actualizados de las variables de entorno en su tarea, actualice el servicio mediante la ejecución del siguiente comando:

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

Si utiliza variables de entorno en la definición de contenedor, debe crear una nueva definición de tarea para actualizar las variables de entorno actualizadas. Con esta nueva definición de tarea, puede crear una nueva tarea o actualizar su servicio ECS.

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

Nota:

Tenga en cuenta lo siguiente cuando transfiera variables de entorno a su tarea:

• Si hay variables de entorno especificadas mediante el parámetro environment (entorno) en una definición de contenedor, estas tienen prioridad sobre las variables contenidas en un archivo de entorno.
• Si se especifican varios archivos de entorno y contienen la misma variable, se procesan en el orden de entrada. Se usa el primer valor de la variable y se ignoran los valores posteriores de las variables duplicadas. Se recomienda utilizar nombres de variables únicos.
• Si se especifica un archivo de entorno como anulación del contenedor, se utilizará el archivo. Se ignorarán todos los demás archivos de entorno especificados en una definición de contenedor.
• Las variables de entorno están disponibles para los procesos PID 1 en un contenedor desde el archivo /proc/1/environ. Si el contenedor ejecuta varios procesos o procesos de inicio, como el script contenedor, el script de inicio o supervisord, la variable de entorno no estará disponible para los procesos que no sean PID 1.

---

Información relacionada

Especificación de variables de entorno