使用 Lambda 环境变量 - AWS Lambda

使用 Lambda 环境变量

您可以使用环境变量来调整函数的行为,而无需更新代码。环境变量是存储在函数的版本特定配置中的一对字符串。Lambda 运行时使环境变量可用于您的代码,并设置其他环境变量,这些变量包含有关函数和调用请求的信息。

注意

为了提高安全性,建议使用 AWS Secrets Manager 而非环境变量来存储数据库凭证和其他敏感信息,例如 API 密钥或授权令牌。有关更多信息,请参阅使用 AWS Secrets Manager 创建和管理密钥

环境变量不会在调用函数之前评估。您定义的任何值都将被视为文字字符串,且不会被展开。在函数代码中执行变量估算。

配置环境变量(控制台)

您可以在函数的未发布版本上定义环境变量。发布一个版本时,会锁定该版本的环境变量以及其他特定于版本的配置设置

您可以通过定义键和值为函数创建环境变量。您的函数使用键名来检索环境变量的值。

在 Lambda 控制台中设置环境变量
  1. 打开 Lamba 控制台的 Functions(函数)页面。

  2. 选择函数。

  3. 选择 Configuration(配置),然后选择 Environment variables(环境变量)。

  4. Environment variables(环境变量)下,选择 Edit(编辑)。

  5. 选择 Add environment variable (添加环境变量)

  6. 输入密钥和值。

    要求
    • 密钥以字母开头,并且至少为两个字符。

    • 键仅包含字母、数字和下划线字符 (_)。

    • Lambda 不会保留密钥。

    • 所有环境变量的总大小不超过 4 KB。

  7. 选择 Save(保存)。

在控制台代码编辑器中生成环境变量列表

您可以在 Lambda 代码编辑器中生成环境变量列表。这是在编码时快速引用环境变量的方法。

  1. 选择节点选项卡。

  2. 选择环境变量选项卡。

  3. 依次选择工具显示环境变量

在控制台代码编辑器中列出时,环境变量会保持加密状态。如果您为传输中的加密启用了加密帮助程序,这些设置则会保持不变。有关更多信息,请参阅 保护环境变量

环境变量列表是只读的,仅在 Lambda 控制台上可用。当您下载函数的.zip 文件存档时,此文件并不包括在内;您也无法通过上传此文件来添加环境变量。

配置环境变量(API)

要使用 AWS CLI 或 AWS 开发工具包管理环境变量,请使用以下 API 操作。

配置环境变量(AWS CLI)

以下示例在名为 my-function 的函数上设置两个环境变量。

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

使用 update-function-configuration 命令应用环境变量时,会替换 Variables 结构的整个内容。要在添加新环境变量时保留现有环境变量,请在请求中包含所有现有值。

要获取当前配置,请使用 get-function-configuration 命令。

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

您应看到以下输出:

{ "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", ... }

您可以将 get-function-configuration 输出中的修订版 ID 作为参数传递给 update-function-configuration。此举可确保这些值在您读取配置和更新配置之间不会发生变化。

要配置函数的加密密钥,请设置 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)

您可以使用 AWS Serverless Application Model 来为您的函数配置环境变量。更新 template.yaml 文件中的 EnvironmentVariables 属性,然后运行 sam deploy

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

环境变量的示例场景

您可以使用环境变量来自定义测试环境和生产环境中的函数行为。例如,您可以创建两个具有相同代码但不同配置的函数。一个函数连接到测试数据库,另一个函数连接到生产数据库。在这种情况下,您可以使用环境变量向函数传递数据库的主机名和其他连接详细信息。

以下示例说明如何将数据库主机和数据库名称定义为环境变量。

Lambda 控制台中的环境变量

如果希望测试环境生成比生产环境更多的调试信息,可以设置环境变量来配置测试环境使用更详细的日志记录或跟踪。

检索环境变量

要检索函数代码中的环境变量,请使用编程语言的标准方法。

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

在某些情况下,您可能需要使用以下格式:

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 通过静态加密来安全地存储环境变量。您可以配置 Lambda 以使用不同的加密密钥、在客户端加密环境变量值或使用 AWS Secrets Manager 在 AWS CloudFormation 模板中设置环境变量。

定义运行时环境变量

Lambda 运行时会在初始化过程中设置多个环境变量。大多数环境变量提供有关函数或运行时的信息。这些环境变量的键是预留 的,无法在函数配置中设置。

预留环境变量
  • _HANDLER – 函数上配置的处理程序位置。

  • _X_AMZN_TRACE_IDX-Ray 跟踪标头。此环境变量会随着每次调用发生变化。

    • 此环境变量不是为仅限操作系统的运行时系统(provided 运行时系统系列)定义的。您可以使用来自 下一个调用Lambda-Runtime-Trace-Id 响应标头设置用于自定义运行时的 _X_AMZN_TRACE_ID

    • 对于 Java 运行时系统版本 17 及更高版本,不使用此环境变量。相反,Lambda 将把跟踪信息存储在 com.amazonaws.xray.traceHeader 系统属性中。

  • AWS_DEFAULT_REGION – 执行 Lambda 函数的默认 AWS 区域。

  • AWS_REGION – 执行 Lambda 函数的 AWS 区域。如果定义了该值,该值将会覆盖 AWS_DEFAULT_REGION

    • 有关在 AWS SDK 中使用 AWS 区域 环境变量的更多信息,请参阅《AWS SDK 和工具参考指南》中的 AWS 区域

  • AWS_EXECUTION_ENV运行时标识符,前缀为 AWS_Lambda_(例如 AWS_Lambda_java8)。此环境变量不是为仅限操作系统的运行时系统(provided 运行时系统系列)定义的。

  • AWS_LAMBDA_FUNCTION_NAME – 函数的名称。

  • AWS_LAMBDA_FUNCTION_MEMORY_SIZE – 对函数可用的内存量(以 MB 为单位)。

  • AWS_LAMBDA_FUNCTION_VERSION – 要执行的函数的版本。

  • AWS_LAMBDA_INITIALIZATION_TYPE – 函数的初始化类型,即 on-demandprovisioned-concurrencysnap-start。有关信息,请参阅配置预置并发使用 Lambda SnapStart 提高启动性能

  • AWS_LAMBDA_LOG_GROUP_NAMEAWS_LAMBDA_LOG_STREAM_NAME – Amazon CloudWatch Logs 组和函数的流名称。AWS_LAMBDA_LOG_GROUP_NAMEAWS_LAMBDA_LOG_STREAM_NAME 环境变量在 Lambda SnapStart 函数中不可用。

  • AWS_ACCESS_KEYAWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEYAWS_SESSION_TOKEN – 从函数的执行角色中获取的访问密钥。

  • AWS_LAMBDA_RUNTIME_API –(自定义运行时运行时 API 的主机和端口。

  • LAMBDA_TASK_ROOT – Lambda 函数代码的路径。

  • LAMBDA_RUNTIME_DIR – 运行时库的路径。

以下附加环境变量并非预留,可以在函数配置中扩展。

非预留环境变量
  • LANG – 运行时的区域设置 (en_US.UTF-8)。

  • PATH – 执行路径 (/usr/local/bin:/usr/bin/:/bin:/opt/bin)。

  • LD_LIBRARY_PATH – 系统库路径 (/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) Node.js 库路径 (/opt/nodejs/node12/node_modules/:/opt/nodejs/node_modules:$LAMBDA_RUNTIME_DIR/node_modules)。

  • PYTHONPATH –(Python 2.7、3.6、3.8)Python 库路径 ($LAMBDA_RUNTIME_DIR)。

  • GEM_PATH –(Ruby)Ruby 库路径 ($LAMBDA_TASK_ROOT/vendor/bundle/ruby/2.5.0:/opt/ruby/gems/2.5.0)。

  • AWS_XRAY_CONTEXT_MISSING – 对于 X-Ray 跟踪,Lambda 会将其设置为 LOG_ERROR,以避免从 X-Ray 开发工具包引发运行时错误。

  • AWS_XRAY_DAEMON_ADDRESS – 对于 X-Ray 跟踪,X-Ray 进程守护程序的 IP 地址和端口。

  • AWS_LAMBDA_DOTNET_PREJIT:对于 .NET 6 和 NET 7 运行时系统,请将此变量设置为启用或禁用 .NET 特定的运行时系统优化。值包括 alwaysneverprovisioned-concurrency。有关更多信息,请参阅 配置预配置并发

  • TZ – 环境的时区 (UTC)。执行环境使用 NTP 同步系统时钟。

显示的示例值反映了最新的运行时。特定变量或其值是否存在会因早先的运行时而异。

保护环境变量

为保护环境变量的安全,您可以使用服务器端加密来保护静态数据,并可以使用客户端加密来保护传输中的数据。

注意

为了提高数据库的安全性,建议您使用 AWS Secrets Manager 而不是环境变量来存储数据库凭证。有关更多信息,请参阅 将 AWS Lambda 与 Amazon RDS 结合使用

静态安全

Lambda 始终使用 AWS KMS key 提供服务器端静态加密。默认情况下,Lambda 使用 AWS 托管式密钥。如果此默认行为适合您的工作流,您无需设置任何其他内容。Lambda 将在账户中创建 AWS 托管式密钥,并为您管理其权限。AWS不会向您收取使用此密钥的费用。

如果您愿意,可以提供 AWS KMS 客户托管式密钥。这样做可能是为了控制 KMS 密钥的轮换,或者是为了满足组织管理 KMS 密钥的要求。当您使用客户托管式密钥时,只有您账户中有权访问 KMS 密钥的用户才能查看或管理函数上的环境变量。

客户托管式密钥产生标准 AWS KMS 费用。有关更多信息,请参阅AWS Key Management Service 定价

传输过程中的安全

为了提高安全性,您可以为传输中加密启用帮助程序,这样可以确保环境变量在客户端加密,以便在传输过程中提供保护。

为环境变量配置加密
  1. 使用 AWS Key Management Service(AWS KMS)创建任意客户托管式密钥,供 Lambda 用于服务器端和客户端加密。有关更多信息,请参阅 AWS Key Management Service 开发人员指南中的创建密钥

  2. 使用 Lambda 控制台,导航到 Edit environment variables (编辑环境变量) 页面。

    1. 打开 Lamba 控制台的 Functions(函数)页面。

    2. 选择函数。

    3. 选择 Configuration (配置),然后从左侧导航栏选择 Environment variables (环境变量)

    4. Environment variables (环境变量) 部分中,选择 Edit (编辑)

    5. 展开 Encryption configuration (加密配置)

  3. (可选)启用控制台加密帮助程序,以使用客户端加密来保护传输中数据。

    1. Encryption in transit (传输中加密) 下,选择 Enable helpers for encryption in transit (为传输中加密启用帮助程序)

    2. 对于要为其启用控制台加密帮助程序的每个环境变量,选择环境变量旁的 Encrypt(加密)。

    3. 在要传输中加密的 AWS KMS key 下,选择在此过程开始时创建的客户托管式密钥。

    4. 选择 Execution role policy (执行角色策略)并复制策略。此策略授予函数执行角色解密环境变量的权限。

      保存此策略以便在此过程的最后一步中使用。

    5. 将代码添加到解密环境变量的函数中。选择解密密钥代码段来查看示例。

  4. (可选)为静态加密指定您的客户托管密钥。

    1. 选择 Use a customer master key (使用客户主密钥)

    2. 选择在此过程开始时创建的客户托管式密钥。

  5. 选择 Save(保存)。

  6. 设置权限。

    如果您使用带有服务器端加密的客户托管密钥,请将权限授予您希望能查看或管理函数上的环境变量的任何用户或角色。有关更多信息,请参阅 管理服务器端加密 KMS 密钥的权限

    如果您为传输中的安全性启用客户端加密,您的函数需要调用 kms:Decrypt API 操作的权限。将之前在此过程中保存的策略添加到函数的执行角色

管理服务器端加密 KMS 密钥的权限

您的用户或函数的执行角色不需要 AWS KMS 权限,即可使用默认加密密钥。要使用客户托管式密钥,您需要具有使用密钥的权限。Lambda 使用您的权限在密钥上创建授权。Lambda 可将其用于加密。

  • kms:ListAliases – 在 Lambda 控制台中查看密钥。

  • kms:CreateGrantkms:Encrypt – 在函数上配置客户托管式密钥。

  • kms:Decrypt – 查看和管理使用客户托管式密钥加密的环境变量。

您可以从您的 AWS 账户 或从密钥的基于资源的权限策略获取这些权限。ListAliasesLambda 的托管策略提供。密钥策略将剩余权限授予密钥用户组中的用户。

没有 Decrypt 权限的用户仍然可以管理函数,但无法在 Lambda 控制台中查看或管理环境变量。要防止用户查看环境变量,请向用户的权限添加一条语句,该语句拒绝访问默认密钥、客户托管式密钥或所有密钥。

例 IAM policy – 按密钥 ARN 拒绝访问
{ "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" } ] }
在 Lambda 控制台中没有解密权限的用户的错误消息。

有关托管密钥权限的详细信息,请参阅《AWS Key Management Service 开发人员指南》中的使用 AWS KMS 的密钥策略

示例代码和模板

本指南 GitHub 存储库中的示例应用程序演示了在函数代码和 AWS CloudFormation 模板中使用环境变量的情况。

示例应用程序
  • Blank 函数 – 创建一个基本函数,显示日志记录、环境变量、AWS X-Ray 跟踪、层、单元测试和 AWS 开发工具包的使用情况。

  • RDS MySQL:在一个模板中使用存储在 Secrets Manager 中的密码创建 VPC 和 Amazon Relational Database Service(Amazon RDS)数据库实例。在应用程序模板中,从 VPC 堆栈导入数据库详细信息,从 Secrets Manager 读取密码,然后将所有连接配置传递给环境变量中的函数。