Transmisión de secretos de Secrets Manager a través de variables de entorno de Amazon ECS - Amazon Elastic Container Service
Cree el secreto de AWS Secrets ManagerAdición de la variable de entorno a la definición del contenedor

Transmisión de secretos de Secrets Manager a través de variables de entorno de Amazon ECS

Cuando introduce un secreto como una variable de entorno, puede especificar el contenido completo de un secreto, una clave JSON específica dentro de un secreto. Este proceso ayuda a controlar la información confidencial expuesta al contenedor. Para obtener más información sobre el control de versiones secreto, consulte ¿Qué hay en un secreto de Secrets Manager? en la Guía del usuario de AWS Secrets Manager.

Al utilizar una variable de entorno para introducir un secreto de Secrets Manager en un contenedor, se debe tener en cuenta lo siguiente.

  • Los datos confidenciales se inyectan en el contenedor al iniciar el contenedor. Si el secreto se actualiza posteriormente o se rota, el contenedor no recibirá automáticamente el valor actualizado. Debe lanzar una nueva tarea o, si su tarea forma parte de un servicio, puede actualizar el servicio y utilizar la opción Force new deployment (Forzar nueva implementación) para forzar que el servicio lance una nueva tarea.

  • Las aplicaciones que se ejecutan en el contenedor, los registros del contenedor y las herramientas de depuración tienen acceso a las variables de entorno.

  • Para las tareas de Amazon ECS alojadas en AWS Fargate, tenga en cuenta lo siguiente:

    • Para introducir el contenido completo de un secreto como variable de entorno o en una configuración de registro, debe usar la versión 1.3.0 de la plataforma o una posterior. Para obtener más información, consulta Versiones de la plataforma Fargate para Amazon ECS.

    • Para introducir una versión o clave JSON específica de un secreto como variable de entorno o en una configuración de registro, debe usar la versión 1.4.0 o posterior (Linux) o 1.0.0 (Windows) de la plataforma. Para obtener más información, consulta Versiones de la plataforma Fargate para Amazon ECS.

  • Para las tareas de Amazon ECS alojadas en EC2, se debe tener en cuenta lo siguiente:

    • Para introducir un secreto utilizando una versión o clave JSON específica de un secreto, la instancia de contenedor debe tener la versión 1.37.0 del agente de contenedor o una posterior. No obstante, recomendamos utilizar la versión del agente de contenedor más reciente. Para obtener información sobre la comprobación de la versión del agente y la actualización a la versión más reciente, consulte Actualización del agente de contenedor de Amazon ECS.

      Para introducir el contenido completo de un secreto como variable de entorno o un secreto en una configuración de registro, la instancia de contenedor debe tener la versión 1.22.0 del agente de contenedor o una posterior.

  • Utilice los puntos de conexión de VPC de interfaz para mejorar los controles de seguridad y conectarse a Secrets Manager a través de una subred privada. Debe crear los puntos de conexión de VPC de interfaz para Secrets Manager. Para obtener información sobre el punto de conexión de VPC, consulte Crear puntos de conexión de VPC en la Guía del usuario de AWS Secrets Manager. Para obtener más información sobre el uso de Secrets Manager y Amazon VPC, consulte How to connect to Secrets Manager service within a Amazon VPC.

  • Para las tareas de Windows configuradas para utilizar el controlador de registros awslogs, debe también establecer la variable de entorno ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE en la instancia del contenedor. Utilice la siguiente sintaxis:

    <powershell>
[Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
Initialize-ECSAgent -Cluster <cluster name> -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]'
</powershell>

  • En la definición de tareas se debe utilizar un rol de ejecución de tareas con los permisos adicionales para Secrets Manager. Para obtener más información, consulte Rol de IAM de ejecución de tareas de Amazon ECS.

Cree el secreto de AWS Secrets Manager

Puede utilizar la consola de Secrets Manager para crear un secreto con su información confidencial. Para obtener más información, consulte Crear un secreto de AWS Secrets Manager en la Guía del usuario de AWS Secrets Manager.

Adición de la variable de entorno a la definición del contenedor

Dentro de la definición de contenedor, puede especificar lo siguiente:

  • El objeto secrets que contiene el nombre de la variable de entorno que se va a establecer en el contenedor

  • Nombre de recurso de Amazon (ARN) del secreto de Secrets Manager

  • Parámetros adicionales que contienen información confidencial que se debe presentar al contenedor

En el ejemplo siguiente, se muestra la sintaxis completa que se debe especificar para el secreto de Secrets Manager.

arn:aws:secretsmanager:region:aws_account_id:secret:secret-name:json-key:version-stage:version-id

En la siguiente sección se describen los parámetros adicionales. Estos parámetros son opcionales, pero si no los utiliza, debe incluir los dos puntos y coma : para utilizar los valores predeterminados. A continuación se ofrecen ejemplos para obtener más contexto.

json-key

Especifica el nombre de la clave en un par clave-valor con el valor que desea establecer como valor de variable de entorno. Solo se admiten valores en formato JSON. Si no especifica una clave JSON, se usa el contenido completo del secreto.

version-stage

Especifica la etiqueta de ensayo de la versión de un secreto que desea utilizar. Si se especifica una etiqueta de ensayo de versión, no se puede especificar un ID de versión. Si no se especifica ninguna etapa de versión, el comportamiento predeterminado consiste en recuperar el secreto con la etiqueta de ensayo AWSCURRENT.

Las etiquetas de ensayo se utilizan para realizar un seguimiento de las distintas versiones de un secreto cuando se actualizan o rotan. Cada versión de un secreto tiene una o varias etiquetas de ensayo y un ID. Para obtener más información, consulte Términos y conceptos clave para AWS Secrets Manager en la Guía del usuario de AWS Secrets Manager.

version-id

Especifica el identificador único de la versión del secreto que desea utilizar. Si se especifica un ID de versión, no se puede especificar una etiqueta de ensayo de versión. Si no se especifica ningún ID de versión, el comportamiento predeterminado consiste en recuperar el secreto con la etiqueta de ensayo AWSCURRENT.

Los ID de versión se utilizan para realizar un seguimiento de las distintas versiones de un secreto cuando se actualizan o rotan. Cada versión de un secreto tiene un ID. Para obtener más información, consulte Términos y conceptos clave para AWS Secrets Manager en la Guía del usuario de AWS Secrets Manager.

Definiciones de contenedor de ejemplo

En los siguientes ejemplos, se muestran las formas en las que se pueden referenciar secretos de Secrets Manager en las definiciones de contenedor.

ejemplo hacer referencia a un secreto completo

A continuación, se incluye un fragmento de código de una definición de tarea que muestra el formato cuando se referencia el texto completo de un secreto de Secrets Manager.

{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
    }]
  }]
}

Para acceder al valor de este secreto desde el contenedor, deberá llamar a $environment_variable_name.

ejemplo referencia de secretos completos

A continuación, se incluye un fragmento de código de una definición de tarea que muestra el formato cuando se referencia el texto completo de múltiples secretos de Secrets Manager.

{
  "containerDefinitions": [{
     "secrets": [
      {
        "name": "environment_variable_name1",
         "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
      },
      {
        "name": "environment_variable_name2",
         "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-abcdef"
      },
      {
        "name": "environment_variable_name3",
        "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-ABCDEF"
      }
    ]
  }]
}

Para acceder al valor de este secreto desde el contenedor, deberá llamar a $environment_variable_name1, $environment_variable_name2 y $environment_variable_name13.

ejemplo hacer referencia a una clave específica dentro de un secreto

A continuación se muestra un ejemplo de salida de un comando get-secret-value que muestra el contenido de un secreto junto con la etiqueta de ensayo de versión y el ID de versión asociados con ella.

{
    "ARN": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf",
    "Name": "appauthexample",
    "VersionId": "871d9eca-18aa-46a9-8785-981ddEXAMPLE",
    "SecretString": "{\"username1\":\"password1\",\"username2\":\"password2\",\"username3\":\"password3\"}",
    "VersionStages": [
        "AWSCURRENT"
    ],
    "CreatedDate": 1581968848.921
}

Haga referencia a una clave específica de la salida anterior en una definición de contenedor especificando el nombre de clave al final del ARN.

{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1::"
    }]
  }]
}
ejemplo hacer referencia a una versión de secreto específica

A continuación se muestra una salida de ejemplo de un comando describe-secret que muestra el contenido sin cifrar de un secreto junto con los metadatos de todas las versiones del secreto.

{
    "ARN": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf",
    "Name": "appauthexample",
    "Description": "Example of a secret containing application authorization data.",
    "RotationEnabled": false,
    "LastChangedDate": 1581968848.926,
    "LastAccessedDate": 1581897600.0,
    "Tags": [],
    "VersionIdsToStages": {
        "871d9eca-18aa-46a9-8785-981ddEXAMPLE": [
            "AWSCURRENT"
        ],
        "9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE": [
            "AWSPREVIOUS"
        ]
    }
}

Haga referencia a una etiqueta de ensayo de versión específica de la salida anterior en una definición de contenedor especificando el nombre de clave al final del ARN.

{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf::AWSPREVIOUS:"
    }]
  }]
}

Haga referencia a un ID de versión específico de la salida anterior en una definición de contenedor especificando el nombre de clave al final del ARN.

{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:::9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE"
    }]
  }]
}
ejemplo hacer referencia a una clave específica y una etiqueta de ensayo de versión de un secreto

A continuación se muestra cómo hacer referencia tanto a una clave específica dentro de un secreto como a una etiqueta de ensayo de versión específica.

{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1:AWSPREVIOUS:"
    }]
  }]
}

Para especificar una clave y un ID de versión específicos, utilice la sintaxis siguiente.

{
  "containerDefinitions": [{
    "secrets": [{
      "name": "environment_variable_name",
      "valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1::9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE"
    }]
  }]
}

Para obtener información sobre cómo crear una definición de tareas con el secreto especificado en una variable de entorno, consulte Creación de una definición de tareas de Amazon ECS mediante la consola.