Utilice variables de entorno Lambda para configurar valores en el código

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, se recomienda utilizar AWS Secrets Manager en lugar de variables de entorno para almacenar las credenciales de la base de datos y otra información confidencial, como claves de API o tokens de autorización. Para obtener más información, consulte Cree y administre secretos con AWS Secrets Manager.

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. Evalúe las variables en el código de la función.

Puede configurar las variables de entorno en Lambda mediante la consola de Lambda, la AWS Command Line Interface (AWS CLI), AWS Serverless Application Model (AWS SAM) o con un AWS SDK.

Console

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 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 Variables de entorno, elija 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 Guardar.

Para generar una lista de variables de entorno en el editor de código de la consola

Puede generar una lista de variables de entorno en el editor de código de Lambda. Esta es una forma rápida de hacer referencia a las variables de entorno mientras se codifica.

1. Elija la pestaña Código.

2. Seleccione la pestaña Variables de entorno.

3. Elija Herramientas, Mostrar variables de entorno.

Las variables de entorno permanecen cifradas cuando aparecen en el editor de código de la consola. Si habilitó los ayudantes de cifrado para el cifrado en tránsito, esa configuración permanecerá sin cambios. Para obtener más información, consulte Asegurar las variables de entorno Lambda.

La lista de variables de entorno es de solo lectura y de uso exclusivo en la consola de Lambda. Este archivo no se incluye al descargar el archivo .zip de la función y no puede agregar variables de entorno al cargar este archivo.

AWS CLI

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=DOC-EXAMPLE-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:111122223333:function:my-function",
    "Runtime": "nodejs20.x",
    "Role": "arn:aws:iam::111122223333:role/lambda-role",
    "Environment": {
        "Variables": {
            "BUCKET": "DOC-EXAMPLE-BUCKET",
            "KEY": "file.txt"
        }
    },
    "RevisionId": "0894d3c1-2a3d-4d48-bf7f-abade99f3c15",
    ...
}

Puede pasar el ID de revisión de la salida de get-function-configuration como parámetro a update-function-configuration. Esto garantiza que los valores no cambien entre el momento en que lee la configuración y el momento en que la actualiza.

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:111122223333:key/055efbb4-xmpl-4336-ba9c-538c7d31f599

AWS SAM

Puede utilizar AWS Serverless Application Model para configurar las variables de entorno de la función. Actualice las propiedades Environment y Variables del archivo template.yaml y, a continuación, ejecute sam deploy.

ejemplo template.yaml

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: An AWS Serverless Application Model template describing your function.
Resources:
  my-function:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: .
      Description: ''
      MemorySize: 128
      Timeout: 120
      Handler: index.handler
      Runtime: nodejs18.x
      Architectures:
        - x86_64
      EphemeralStorage:
        Size: 10240
      Environment:
        Variables:
          BUCKET: DOC-EXAMPLE-BUCKET
          KEY: file.txt
      # Other function properties...

AWS SDKs

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

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

Para obtener más información, consulte la documentación del SDK de AWS para el lenguaje de programación preferido.

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 cambia con cada invocación.

  • Esta variable de entorno no está definida para los tiempos de ejecución exclusivos del sistema operativo (la familia de tiempos de ejecución provided). 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.

  • En las versiones 17 y posteriores de Java Runtime no se utiliza esta variable de entorno. En su lugar, Lambda almacena la información de rastreo en la propiedad del sistema com.amazonaws.xray.traceHeader.

• AWS_DEFAULT_REGION: la Región de AWS predeterminada donde se ejecuta la función de Lambda.

• AWS_REGION: la Región de AWS donde se ejecuta la función de Lambda. Si se define, este valor anula la AWS_DEFAULT_REGION.

  • Para obtener más información sobre cómo usar las variables de entorno de la Región de AWS con los SDK de AWS, consulte Región de AWS en la Guía de referencia de las herramientas y los SDK de AWS.

• 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 los tiempos de ejecución exclusivos del sistema operativo (la familia de tiempos de ejecución de provided).

• 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 de Registros de Amazon CloudWatch y flujo para la función. Las variables de entorno AWS_LAMBDA_LOG_GROUP_NAME y AWS_LAMBDA_LOG_STREAM_NAME no están disponibles en las funciones de Lambda SnapStart.

• 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 (/var/lang/lib:/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 los tiempos de ejecución de .NET 6 y .NET 7, establezca esta variable para habilitar o deshabilitar optimizaciones de tiempos de ejecución específicos de .NET. Los valores incluyen always, never, y provisioned-concurrency. Para obtener más información, consulte Configuración de simultaneidad aprovisionada para una función.

• 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.

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, utiliza variables de entorno para pasar el nombre de host y otros detalles de conexión de la base de datos a la función.

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.

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.