Trabajar con variables de entorno de 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, 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 Uso de secretos de AWS Secrets Manager en las funciones de AWS 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. Evalúe las variables en el código de la función.

Crear variables de entorno de Lambda

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 la pestaña 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. Desplácese hacia abajo hasta la sección VARIABLES DE ENTORNO del editor de código. Las variables de entorno existentes se muestran aquí:

   

3. Para crear nuevas variables de entorno, elija el signo más ( ):

   

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=amzn-s3-demo-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": "nodejs22.x",
    "Role": "arn:aws:iam::111122223333:role/lambda-role",
    "Environment": {
        "Variables": {
            "BUCKET": "amzn-s3-demo-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: nodejs22.x
      Architectures:
        - x86_64
      EphemeralStorage:
        Size: 10240
      Environment:
        Variables:
          BUCKET: amzn-s3-demo-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.

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.

Por ejemplo, en su entorno de prueba, puede establecer una variable de entorno con la clave LOG_LEVEL y un valor que indique un nivel de registro de depuración o rastreo. En el código de la función de Lambda, puede utilizar esta variable de entorno para establecer el nivel de registro.

Los siguientes ejemplos de código en Python y Node.js ilustran cómo puede hacerlo. En estos ejemplos se supone que la variable de entorno tiene un valor de DEBUG en Python o debug en Node.js.

Python

ejemplo Código de Python para establecer el nivel de registro

import os
import logging

# Initialize the logger
logger = logging.getLogger()

# Get the log level from the environment variable and default to INFO if not set
log_level = os.environ.get('LOG_LEVEL', 'INFO')

# Set the log level
logger.setLevel(log_level)

def lambda_handler(event, context):
    # Produce some example log outputs
    logger.debug('This is a log with detailed debug information - shown only in test environment')
    logger.info('This is a log with standard information - shown in production and test environments')
    

Node.js (ES module format)

ejemplo Código de Node.js para establecer el nivel de registro

En este ejemplo se utiliza la biblioteca de registro de winston. Use npm para agregar esta biblioteca al paquete de implementación de la función. Para obtener más información, consulte Creación de un paquete de despliegue .zip con dependencias.

import winston from 'winston';

// Initialize the logger using the log level from environment variables, defaulting to INFO if not set
const logger = winston.createLogger({
   level: process.env.LOG_LEVEL || 'info',
   format: winston.format.json(),
   transports: [new winston.transports.Console()]
});

export const handler = async (event) => {
   // Produce some example log outputs
   logger.debug('This is a log with detailed debug information - shown only in test environment');
   logger.info('This is a log with standard information - shown in production and test environment');
   
};

Recuperar variables de entorno Lambda

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 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 AWS SDK, consulte Región de AWS en la Guía de referencia de las herramientas y los AWS SDK.

• 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) 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/3.3.0:/opt/ruby/gems/3.3.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: (.NET) establezca esta variable para habilitar o deshabilitar optimizaciones específicas de tiempo de ejecución 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.