Uso de 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 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 Uso de AWS Lambda con Amazon RDS.

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.

Configuración de variables de entorno (consola)

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. Elija 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 Proteger variables de entorno.

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.

Configuración de variables de entorno (API)

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

• UpdateFunctionConfiguration

• GetFunctionConfiguration

• CreateFunction

Configuración de variables de entorno (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=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:111122223333:function:my-function",
    "Runtime": "nodejs20.x",
    "Role": "arn:aws:iam::111122223333:role/lambda-role",
    "Environment": {
        "Variables": {
            "BUCKET": "my-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

Configuración de variables de entorno (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: my-bucket
          KEY: file.txt
      # Other function properties...

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.

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 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 las empresas emergentes 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.

• 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 Uso de AWS Lambda con Amazon RDS.

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 de AWS. Si este comportamiento predeterminado se ajusta a su flujo de trabajo, no tiene que configurar nada más. Lambda crea la Clave administrada de 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 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 AWS Key Management ServiceGuía para desarrolladores de .

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

   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 en la barra de navegación izquierda.

   4. En la sección Variables de entorno, elija Editar.

   5. Expanda Configuración de cifrado.

3. (Opcional) Habilite las funciones auxiliares de cifrado de la consola para que utilicen el cifrado del cliente a fin de proteger los datos en tránsito.

   1. En Cifrado en tránsito, elija 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 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 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. Para ver un ejemplo, elija Fragmento para descifrar secretos.

4. (Opcional) Especifique su clave administrada por el cliente para el cifrado en reposo.

   1. Elija Use una clave maestra del cliente.

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

5. Elija Guardar.

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:111122223333:key/3be10e2d-xmpl-4be4-bc9d-0405a71945cc"
        }
    ]
}

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 Relational Database Service (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.