Uso de variables de entorno de AWS Lambda - AWS Lambda
Configuración de variables de entornoConfiguración de variables de entorno con la APIEscenario de ejemplo para variables de entornoRecuperar variables de entornoVariables definidas de entorno de tiempo de ejecuciónProteger variables de entornoCódigo de muestra y plantillas

Uso de variables de entorno de AWS Lambda

Puede usar variables de entorno para ajustar el comportamiento de su función sin actualizar el código. Una variable de entorno es un par de cadenas almacenadas en la configuración específica de la versión de una función. El tiempo de ejecución de Lambda hace que las variables de entorno estén disponibles para el código y establece variables de entorno adicionales que contienen información sobre la función y la solicitud de invocación.

nota

Para aumentar la seguridad de la base de datos, se recomienda utilizar AWS Secrets Manager en lugar de variables de entorno para almacenar las credenciales de la base de datos. Para obtener más información, consulte Configuración del acceso a la base de datos para una función de Lambda.

Las variables de entorno no se evalúan antes de la invocación de la función. Cualquier valor que defina se considera una cadena literal y no expandida. Realice la evaluación de variables en el código de función.

Configuración de variables de entorno

Las variables de entorno se definen en la versión no publicada de la función. Al publicar una versión, las variables de entorno se bloquean para esa versión junto con otra configuración específica de la versión.

Puede crear una variable de entorno para su función al definir una clave y un valor. Su función utiliza el nombre de la clave para recuperar el valor de la variable de entorno.

Para establecer variables de entorno en la consola de Lambda

  1. Abra la página de Functions (Funciones) en la consola de Lambda.

  2. Elija una función.

  3. Elija Configuración y, a continuación, elija Variables de entorno.

  4. En Environment variables (Variables de entorno), elija Edit (Editar).

  5. Elija Add environment variable (Añadir variable de entorno).

  6. Introduzca una clave y un valor.

    Requisitos

    • Las claves comienzan con una letra y tienen como mínimo dos caracteres.

    • Las claves solo contienen letras, números y guiones bajos (_).

    • Las llaves no están reservadas por Lambda.

    • El tamaño total de todas las variables de entorno no supera los 4 KB.

  7. Seleccione Save.

Configuración de variables de entorno con la API

Para administrar variables de entorno con la AWS CLI o el SDK de AWS, utilice las siguientes operaciones de la API.

En el ejemplo siguiente se establecen dos variables de entorno en una función denominada my-function.

aws lambda update-function-configuration --function-name my-function \
    --environment "Variables={BUCKET=my-bucket,KEY=file.txt}"

Cuando se aplican variables de entorno con el comando update-function-configuration, se remplaza todo el contenido de la Variables estructura. Para conservar las variables de entorno existentes al agregar una nueva, incluya todos los valores existentes en la solicitud.

Para obtener la configuración actual, use el comando get-function-configuration.

aws lambda get-function-configuration --function-name my-function

Debería ver los siguientes datos de salida:

{
    "FunctionName": "my-function",
    "FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
    "Runtime": "nodejs18.x",
    "Role": "arn:aws:iam::123456789012:role/lambda-role",
    "Environment": {
        "Variables": {
            "BUCKET": "my-bucket",
            "KEY": "file.txt"
        }
    },
    "RevisionId": "0894d3c1-2a3d-4d48-bf7f-abade99f3c15",
    ...
}

Para asegurarse de que los valores no cambian entre cuando lee la configuración y cuando la actualiza, puede pasar el ID de revisión del resultado de get-function-configuration como parámetro a update-function-configuration.

Para configurar la clave de cifrado de una función, establezca la opción KMSKeyARN.

aws lambda update-function-configuration --function-name my-function \
   --kms-key-arn arn:aws:kms:us-east-2:123456789012:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

Escenario de ejemplo para variables de entorno

Puede usar variables de entorno para personalizar el comportamiento de la función en su entorno de prueba y entorno de producción. Por ejemplo, puede crear dos funciones con el mismo código pero con configuración diferente. Una función se conecta a una base de datos de prueba y la otra se conecta a una base de datos de producción. En esta situación, se utilizan variables de entorno para indicar a la función el nombre de host y otros detalles de conexión para la base de datos.

En el ejemplo siguiente se muestra cómo definir el host de base de datos y el nombre de base de datos como variables de entorno.

Para establecer variables de entorno en la consola de Lambda.

Si desea que su entorno de prueba genere más información de depuración que el entorno de producción, puede establecer una variable de entorno para configurar su entorno de prueba para utilizar un registro más detallado o un seguimiento más detallado.

Recuperar variables de entorno

Para recuperar variables de entorno en el código de función, utilice el método estándar para el lenguaje de programación.

Node.js
let region = process.env.AWS_REGION
Python
import os
  region = os.environ['AWS_REGION']
nota

En algunos casos, es posible que deba usar el siguiente formato:

region = os.environ.get('AWS_REGION')
Ruby
region = ENV["AWS_REGION"]
Java
String region = System.getenv("AWS_REGION");
Go
var region = os.Getenv("AWS_REGION")
C#
string region = Environment.GetEnvironmentVariable("AWS_REGION");
PowerShell
$region = $env:AWS_REGION

Lambda almacena variables de entorno de forma segura cifrándolas en reposo. Puede configurar Lambda para que utilice una clave de cifrado diferente, cifrar valores de variables de entorno del lado del cliente o establezca variables de entorno en una plantilla de AWS CloudFormation con AWS Secrets Manager.

Variables definidas de entorno de tiempo de ejecución

Los tiempos de ejecución de Lambda establecen varias variables de entorno durante la inicialización. La mayoría de las variables de entorno proporcionan información sobre la función o el tiempo de ejecución. Las claves para estas variables de entorno están reservadas y no se pueden establecer en la configuración de la función.

Variables de entorno reservadas

  • _HANDLER: la localización del controlador configurada en la función.

  • _X_AMZN_TRACE_ID: el encabezado de rastreo de X-Ray. Esta variable de entorno no está definida para tiempos de ejecución personalizados (por ejemplo, tiempos de ejecución que utilicen los identificadores provided o provided.al2). Puede configurar _X_AMZN_TRACE_ID para tiempos de ejecución personalizados mediante el encabezado de respuesta Lambda-Runtime-Trace-Id de la Siguiente invocación.

  • AWS_REGION: la región de AWS donde se ejecuta la función de Lambda.

  • AWS_EXECUTION_ENV: identificador del tiempo de ejecución, precedido de AWS_Lambda_ (por ejemplo, AWS_Lambda_java8). Esta variable de entorno no está definida para tiempos de ejecución personalizados (por ejemplo, tiempos de ejecución que utilicen los identificadores provided o provided.al2).

  • AWS_LAMBDA_FUNCTION_NAME: el nombre de la función.

  • AWS_LAMBDA_FUNCTION_MEMORY_SIZE: la cantidad de memoria disponible para la función en MB.

  • AWS_LAMBDA_FUNCTION_VERSION: la versión de la función que se está ejecutando.

  • AWS_LAMBDA_INITIALIZATION_TYPE: el tipo de inicialización de la función, que es on-demand, provisioned-concurrency o snap-start. Para obtener información, consulte Administración de la simultaneidad aprovisionada de Lambda o Mejora del rendimiento de inicio con Lambda SnapStart.

  • AWS_LAMBDA_LOG_GROUP_NAME, AWS_LAMBDA_LOG_STREAM_NAME: el nombre del grupo Amazon CloudWatch Logs y flujo para la función.

  • AWS_ACCESS_KEY, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN: las claves de acceso obtenidas del rol de ejecución de la función.

  • AWS_LAMBDA_RUNTIME_API: (Tiempo de ejecución personalizado) El host y el puerto de la API de tiempo de ejecución.

  • LAMBDA_TASK_ROOT: la ruta al código de la función de Lambda.

  • LAMBDA_RUNTIME_DIR: la ruta a las bibliotecas de tiempos de ejecución.

Las siguientes variables de entorno adicionales no están reservadas y pueden ampliarse en la configuración de la función.

Variables de entorno sin reserva

  • LANG: configuración regional del tiempo de ejecución (en_US.UTF-8).

  • PATH: ruta de ejecución (/usr/local/bin:/usr/bin/:/bin:/opt/bin).

  • LD_LIBRARY_PATH: ruta de la biblioteca del sistema (/lib64:/usr/lib64:$LAMBDA_RUNTIME_DIR:$LAMBDA_RUNTIME_DIR/lib:$LAMBDA_TASK_ROOT:$LAMBDA_TASK_ROOT/lib:/opt/lib).

  • NODE_PATH: (Node.js) La ruta de la biblioteca Node.js (/opt/nodejs/node12/node_modules/:/opt/nodejs/node_modules:$LAMBDA_RUNTIME_DIR/node_modules).

  • PYTHONPATH: (Python 2.7, 3.6, 3.8) La ruta de la biblioteca de Python ($LAMBDA_RUNTIME_DIR).

  • GEM_PATH: (Ruby) La ruta de la biblioteca Ruby ($LAMBDA_TASK_ROOT/vendor/bundle/ruby/2.5.0:/opt/ruby/gems/2.5.0).

  • AWS_XRAY_CONTEXT_MISSING: para el seguimiento de X-Ray, Lambda establece esto en LOG_ERROR para evitar arrojar errores de tiempo de ejecución desde el SDK de X-Ray.

  • AWS_XRAY_DAEMON_ADDRESS: para el rastreo de X-Ray, la dirección IP y el puerto del daemon de X-Ray.

  • AWS_LAMBDA_DOTNET_PREJIT: para el tiempo de ejecución de.NET 3.1, establezca esta variable para habilitar o deshabilitar optimizaciones específicas de tiempo de ejecución de.NET 3.1. Los valores incluyen always, never, y provisioned-concurrency. Para obtener información, consulte Configuración de concurrencia aprovisionada.

  • TZ: la zona horaria del entorno (UTC). El entorno de ejecución utiliza NTP para sincronizar el reloj del sistema.

Los valores de muestra presentados reflejan los últimos tiempos de ejecución. La presencia de variables específicas o sus valores pueden variar en tiempos de ejecución anteriores.

Proteger variables de entorno

A fin de proteger las variables de entorno, puede utilizar el cifrado en el servidor para proteger los datos en reposo y el cifrado del lado del cliente para proteger los datos en tránsito.

nota

Para aumentar la seguridad de la base de datos, se recomienda utilizar AWS Secrets Manager en lugar de variables de entorno para almacenar las credenciales de la base de datos. Para obtener más información, consulte Configuración del acceso a la base de datos para una función de Lambda.

Seguridad en reposo

Lambda siempre proporciona cifrado en el servidor en reposo con una AWS KMS key. De forma predeterminada, Lambda utiliza una Clave administrada por AWS. Si este comportamiento predeterminado se ajusta a su flujo de trabajo, no tiene que configurar nada más. Lambda crea la Clave administrada por AWS en su cuenta y administra sus permisos. AWS no le cobrará por el uso de esta clave.

Si lo prefiere, puede proporcionar una clave administrada por el cliente de AWS KMS en su lugar. Puede hacerlo para tener control sobre la rotación de la clave de KMS o para cumplir con los requisitos de su organización para administrar claves de KMS. Cuando usa una clave administrada por el usuario, solo los usuarios de su cuenta con acceso a la clave de KMS pueden ver o administrar las variables de entorno de la función.

Las claves administradas por el cliente ocasionan cargos de AWS KMS estándar. Para obtener más información, consulte Precios de AWS Key Management Service.

Seguridad en tránsito

Para mayor seguridad, puede habilitar las funciones auxiliares del cifrado en tránsito, de modo que garantiza que las variables de entorno se cifren en el lado del cliente para su protección en tránsito.

Configuración del cifrado de las variables de entorno

  1. Use AWS Key Management Service (AWS KMS) a fin de crear claves administradas por el cliente para que Lambda las utilice para el cifrado del lado del cliente y del servidor. Para obtener más información, consulte Creación de claves en la Guía para desarrolladores de AWS Key Management Service.

  2. Mediante la consola de Lambda, vaya a la página Edit environment variables (Editar variables de entorno).

    1. Abra la página de Functions (Funciones) en la consola de Lambda.

    2. Elija una función.

    3. Elija Configuration (Configuración) y, a continuación, elija Environment variables (Variables de entorno) en la barra de navegación izquierda.

    4. En la sección Environment variables (Variables de entorno), elija Edit (Editar).

    5. Expanda Encryption configuration (Configuración de cifrado).

  3. También puede habilitar las funciones auxiliares de cifrado de la consola para que utilicen el cifrado del lado del cliente a fin de proteger los datos en tránsito.

    1. En Encryption in transit (Cifrado en tránsito), elija Enable helpers for encryption in transit (Activar funciones auxiliares para el cifrado en tránsito).

    2. Para cada variable de entorno para la que desee habilitar las funciones auxiliares de cifrado de la consola, elija Encrypt (Cifrar) junto a la variable de entorno.

    3. En la AWS KMS key para el cifrado en tránsito, elija una clave administrada por el cliente que haya creado al principio de este procedimiento.

    4. Elija Execution role policy (Política de rol de ejecución) y copie la política. Esta política concede permiso al rol de ejecución de la función para descifrar las variables de entorno.

      Guarde esta política para usarla en el último paso de este procedimiento.

    5. Agregue el código a la función que descifre las variables de entorno. Elija Decrypt secrets snippet (Fragmento para descifrar secretos) para ver un ejemplo.

  4. También puede especificar su clave administrada por el cliente para el cifrado en reposo.

    1. Elija Use a customer master key (Use una clave maestra del cliente).

    2. Elija una clave administrada por el cliente que haya creado al principio de este procedimiento.

  5. Seleccione Save.

  6. Configure los permisos.

    Si está utilizando una clave administrada por el cliente con cifrado en el servidor, conceda permisos a cualquier usuario o rol que desee que pueda ver o administrar variables de entorno en la función. Para obtener más información, consulte Administración de permisos para la clave de KMS de cifrado en el servidor.

    Si habilita el cifrado del lado del cliente para la seguridad en tránsito, su función necesita permiso para llamar a la operación de la API kms:Decrypt. Agregue la política que guardó anteriormente en este procedimiento al rol de ejecución de la función.

Administración de permisos para la clave de KMS de cifrado en el servidor

No se requieren permisos de AWS KMS para el usuario o el rol de ejecución de la función para utilizar la clave de cifrado predeterminada. Para utilizar una clave administrada por el cliente, necesita permisos de uso de la clave. Lambda usa sus permisos para crear una concesión en la clave. Esto permite a Lambda usarlo para el cifrado.

  • kms:ListAliases: para ver las teclas en la consola de Lambda.

  • kms:CreateGrant, kms:Encrypt: para configurar una clave administrada por el cliente en una función.

  • kms:Decrypt: para ver y administrar variables de entorno cifradas con una clave administrada por el cliente.

Puede obtener estos permisos de su Cuenta de AWS o de la política de permisos basada en recursos de una clave. ListAliases surge de las políticas administradas en Lambda. Las políticas clave conceden los permisos restantes a los usuarios del grupo Usuarios clave .

Los usuarios sin permisos Decrypt todavía pueden administrar funciones, pero no pueden ver variables de entorno ni administrarlas en la consola de Lambda. Para evitar que un usuario vea variables de entorno, añada una instrucción a los permisos del usuario que deniegue el acceso a la clave predeterminada, a una clave administrada por el cliente o a todas las claves.

ejemplo Política de IAM: denegar acceso por ARN de clave
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Deny",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": "arn:aws:kms:us-east-2:123456789012:key/3be10e2d-xmpl-4be4-bc9d-0405a71945cc"
        }
    ]
}
Mensaje de error para el usuario sin permisos de descifrado en la consola de Lambda.

Para obtener información detallada sobre la administración de permisos de clave, consulte Uso de políticas de claves en AWS KMS en la Guía para desarrolladores de AWS Key Management Service.

Código de muestra y plantillas

Las aplicaciones de ejemplo en el repositorio de GitHub de esta guía demuestran el uso de variables de entorno en el código de función y en plantillas de AWS CloudFormation.

Aplicaciones de muestra

  • Función en blanco: cree una función básica que muestre el uso del registro, las variables de entorno, el seguimiento de AWS X-Ray, las capas, las pruebas de unidad y el SDK de AWS.

  • RDS MySQL: cree una VPC y una instancia de base de datos de Amazon RDS en una plantilla, con una contraseña almacenada en Secrets Manager. En la plantilla de aplicación, importe los detalles de la base de datos de la pila de VPC, lea la contraseña de Secrets Manager y pase toda la configuración de conexión a la función en variables de entorno.