扩展的工作原理 Amazon 参数和密钥 Lambda 扩展环境变量使用 Amazon Systems ManagerParameter Store 和 Amazon Secrets Manager 扩展的示例命令 Amazon 参数和密钥 Lambda 扩展 ARN

在 Amazon Lambda 函数中使用 Parameter Store 参数

Parameter Store（Amazon Systems Manager 的一项功能）可提供安全的分层存储，用于配置数据管理和密钥管理。您可以将密码、数据库字符串、Amazon Machine Image (AMI) ID 和许可证代码等数据存储为参数值。

若要在不使用 SDK 的情况下在 Amazon Lambda 函数中使用 Parameter Store 中的参数，您可以使用 Amazon 参数和密钥 Lambda 扩展。此扩展会检索参数值，并将其缓存以供将来使用。使用 Lambda 扩展可以通过减少对 Parameter Store 的 API 调用次数来降低成本。使用扩展还可以降低延迟，因为检索缓存参数比从 Parameter Store 中检索参数更快。

Lambda 扩展是一个配套进程，增加了 Lambda 函数的功能。扩展类似于与 Lambda 调用并行的客户端。此并行客户端可以在其生命周期中的任何时刻与您的函数交互。有关更多信息，请参阅《Amazon Lambda 开发人员指南》中的Lambda 扩展 API。

Amazon 参数和密钥 Lambda 扩展同时适用于 Parameter Store 和 Amazon Secrets Manager。了解如何将 Lambda 扩展与 Secrets Manager 中的密钥一起使用，请参阅《Amazon Secrets Manager 用户指南》中的在 Amazon Lambda 函数中使用 Amazon Secrets Manager 密钥。

扩展的工作原理

在不使用 Lambda 扩展的情况下，若要在 Lambda 函数中使用参数，您必须通过与 Parameter Store 的 GetParameter API 操作集成来配置您的 Lambda 函数，以接收配置更新。

使用 Amazon 参数和密钥 Lambda 扩展时，扩展程序会从 Parameter Store 中检索参数值并将其存储在本地缓存中。然后，缓存值将用于进一步的调用，直到过期。缓存值会在超过其生存时间（TTL）后过期。您可以使用 SSM_PARAMETER_STORE_TTL 环境变量配置 TTL 值，如本主题下文所述。

如果配置的缓存 TTL 尚未到期，则使用缓存的参数值。如果已到期，则缓存的值将失效，并从 Parameter Store 中检索参数值。

此外，系统会检测常用的参数值并将其保存在缓存中，同时清除已过期或未使用的参数值。

实施详情

使用以下详细信息来帮助您配置 Amazon 参数和密钥 Lambda 扩展。

身份验证

为了对 Parameter Store 请求进行授权和身份验证，扩展程序将使用与运行 Lambda 函数本身相同的凭证。因此，用于运行函数的 Amazon Identity and Access Management（IAM）角色必须具有以下权限才能与 Parameter Store 交互：

ssm:GetParameter – 从 Parameter Store 中检索参数时需要
kms:Decrypt – 从 Parameter Store 中检索 SecureString 参数时需要

有关更多信息，请参阅《Amazon Lambda 开发人员指南》中的 Amazon Lambda 执行角色。

实例化

Lambda 会实例化与函数所需的并发级别相对应的单独实例。每个实例都是独立的，并维护自己的配置数据本地缓存。有关 Lambda 实例和并发的更多信息，请参阅《Amazon Lambda 开发人员指南》中的配置预留并发。

无 SDK 依赖项

Amazon 参数和密钥 Lambda 扩展程序独立于任何 Amazon SDK 语言库工作。无需 Amazon SDK 即可向 Parameter Store 发出 GET 请求。

Localhost 端口

在您的 GET 请求中使用 localhost。该扩展向 localhost 端口 2773 发出请求。无需指定外部或内部端点即可使用扩展。您可以通过设置环境变量 PARAMETERS_SECRETS_EXTENSION_HTTP_PORT 来配置端口。

例如，在 Python 中，您的 GET URL 可能与以下示例类似。


parameter_url = ('http://localhost:' + port + '/systemsmanager/parameters/get/?name=' + ssm_parameter_path)

TTL 到期之前参数值的更改

扩展程序不会检测对参数值所做的更改，也不会在 TTL 到期之前执行自动刷新操作。如果您更改参数值，则在缓存下次刷新之前，使用缓存参数值的操作可能会失败。如果您预计参数值会频繁更改，我们建议设置较短的 TTL 值。

标头要求

若要从扩展缓存中检索参数，则 GET 请求的标头必须包含 X-Aws-Parameters-Secrets-Token 引用。将令牌设置为 AWS_SESSION_TOKEN，Lambda 为所有正在运行的函数提供此令牌。使用此标头表示调用方在 Lambda 环境中。

示例

以下 Python 示例演示了检索缓存参数值的基本请求。


import urllib.request
import os
import json

aws_session_token = os.environ.get('AWS_SESSION_TOKEN')

def lambda_handler(event, context):
    # Retrieve /my/parameter from Parameter Store using extension cache
    req = urllib.request.Request('http://localhost:2773/systemsmanager/parameters/get?name=%2Fmy%2Fparameter')
    req.add_header('X-Aws-Parameters-Secrets-Token', aws_session_token)
    config = urllib.request.urlopen(req).read()

    return json.loads(config)

ARM 支持

对于支持 x86_64 和 x86 架构的所有相同 Amazon Web Services 区域，此扩展不支持其中的 ARM 架构。

有关扩展 ARN 的完整列表，请参阅 Amazon 参数和密钥 Lambda 扩展 ARN。

日志记录

Lambda 使用 Amazon CloudWatch Logs 记录有关扩展的执行信息以及函数。默认情况下，扩展将最少量的信息记录到 CloudWatch。若要记录更多详细信息，请将环境变量 PARAMETERS_SECRETS_EXTENSION_LOG_LEVEL 设置为 DEBUG。

将扩展添加到 Lambda 函数

若要使用 Amazon 参数和密钥 Lambda 扩展，您需要将扩展作为层添加到 Lambda 函数。

使用以下方法之一将扩展添加到函数。

Amazon Web Services Management Console（添加层选项）

通过 https://console.aws.amazon.com/lambda/ 打开 Amazon Lambda 控制台。
选择您的函数。在 Layers（层）区域中，选择 Add a layer（添加层）。
在选择层区域中，选择 Amazon 层选项。
在 Amazon 层中，选择 Amazon-Parameters-and-Secrets-Lambda-Extension，选择版本，然后选择添加。

Amazon Web Services Management Console（指定 ARN 选项）

通过 https://console.aws.amazon.com/lambda/ 打开 Amazon Lambda 控制台。
选择您的函数。在 Layers（层）区域中，选择 Add a layer（添加层）。
在 Choose a layer（选择层）区域中，选择 Specify an ARN（指定 ARN）选项。
对于 Specify an ARN（指定 ARN），输入 Amazon Web Services 区域和架构的扩展 ARN，然后选择 Add（添加）。

Amazon Command Line Interface

在 Amazon CLI 中运行以下命令。将每个示例资源占位符替换为您自己的信息。


aws lambda update-function-configuration \
    --function-name function-name \
    --layers layer-ARN

相关信息

将层与 Lambda 函数结合使用

配置扩展（.zip 文件存档）

Amazon 参数和密钥 Lambda 扩展环境变量

您可以通过更改以下环境变量配置扩展。若要查看当前设置，请将 PARAMETERS_SECRETS_EXTENSION_LOG_LEVEL 设置为 DEBUG。有关更多信息，请参阅《Amazon Lambda 开发者指南》中的使用 Amazon Lambda 环境变量。

注意

Amazon Lambda 将关于 Lambda 扩展和 Lambda 函数的操作详细信息记录在 Amazon CloudWatch Logs 中。

环境变量	详细信息	必需	有效值	默认值
`SSM_PARAMETER_STORE_TIMEOUT_MILLIS`	对 Parameter Store 的请求超时（以毫秒为单位）。值为 0（零）表示没有超时。	不支持	所有整数	0（零）
`SECRETS_MANAGER_TIMEOUT_MILLIS`	对 Secrets Manager 的请求超时（以毫秒为单位）。值为 0（零）表示没有超时。	不支持	所有整数	0（零）
`SSM_PARAMETER_STORE_TTL`	缓存中参数在失效前的最长有效生命周期（以秒为单位）。值为 0（零）表示应绕过缓存。如果 `PARAMETERS_SECRETS_EXTENSION_CACHE_SIZE` 的值为 0（零），则忽略此变量。	不支持	0（零）到 300 秒（五分钟）	300 秒（五分钟）
`SECRETS_MANAGER_TTL`	缓存中密钥在失效前的最长有效生命周期（以秒为单位）。值为 0（零）表示已绕过缓存。如果 `PARAMETERS_SECRETS_EXTENSION_CACHE_SIZE` 的值为 0（零），则忽略此变量。	不支持	0（零）到 300 秒（五分钟）	300 秒（5 分钟）
`PARAMETERS_SECRETS_EXTENSION_CACHE_ENABLED`	确定是否已启用扩展缓存。有效值：`TRUE \| FALSE`	不支持	TRUE \| FALSE	TRUE
`PARAMETERS_SECRETS_EXTENSION_CACHE_SIZE`	缓存的最大大小（以项目数为单位）。值为 0（零）表示已绕过缓存。如果两个缓存 TTL 值都为 0（零），则忽略此变量。	不支持	0（零）到 1000	1000
`PARAMETERS_SECRETS_EXTENSION_HTTP_PORT`	本地 HTTP 服务器的端口。	不支持	1-65535	2773
`PARAMETERS_SECRETS_EXTENSION_MAX_CONNECTIONS`	扩展用于向 Parameter Store 或 Secrets Manager 发出请求的 HTTP 客户端的最大连接数。这是 Secrets Manager 客户端和 Parameter Store 客户端与后端服务建立的连接数的各客户端配置。	不支持	最小值为 1；无最大值限制。	3
`PARAMETERS_SECRETS_EXTENSION_LOG_LEVEL`	扩展日志中报告的详细信息级别。我们建议您在设置和测试扩展时使用 `DEBUG` 以获取有关缓存配置最详细的信息。 Lambda 操作的日志会自动推送到关联的 Logs 日志组。	不支持	`DEBUG \| WARN \| ERROR \| NONE \| INFO`	`INFO`

使用 Amazon Systems ManagerParameter Store 和 Amazon Secrets Manager 扩展的示例命令

本节中的示例演示了与 Amazon Systems Manager Parameter Store 和 Amazon Secrets Manager 扩展搭配使用的 API 操作。

Parameter Store 的示例命令

Lambda 扩展对 GetParameter API 操作使用只读访问权限。

若要调用此操作，请进行类似于以下示例的 HTTP GET 调用。


GET http://localhost:port/systemsmanager/parameters/get?name=parameter-path&version=version&label=label&withDecryption={true|false}

在此示例中，parameter-path 表示完整的参数名称，如果参数是层次结构的一部分，则其表示参数路径。版本和标签是可与 GetParameter 操作一起使用的选择器。此命令格式提供对标准参数层中参数的访问权限。

注意

使用 GET 调用时，必须针对 HTTP 对参数值进行编码，以保留特殊字符。例如，对可转换为 URL 一部分的字符进行编码（如 %2Fa%2Fb%2Fc），而不要将层次结构路径进行格式化（如 /a/b/c）。


GET http://localhost:port/systemsmanager/parameters/get/?name=MyParameter&version=5

若要调用层次结构中的参数，请进行类似于以下示例的 HTTP GET 调用。


GET http://localhost:port/systemsmanager/parameters/get?name=%2Fa%2Fb%2F&label=release

若要调用公用（全局）参数，请进行类似于以下示例的 HTTP GET 调用。


GET http://localhost:port/systemsmanager/parameters/get/?name=%2Faws%2Fservice%20list%2F…

若要使用 Parameter Store 引用对 Secrets Manager 密钥进行 HTTP GET 调用，请进行类似于以下示例的 HTTP GET 调用。


GET http://localhost:port/systemsmanager/parameters/get?name=%2Faws%2Freference%2Fsecretsmanager%2F…

若要使用参数的 Amazon 资源名称（ARN）进行调用，请进行类似于以下示例的 HTTP GET 调用。


GET http://localhost:port/systemsmanager/parameters/get?name=arn:aws:ssm:us-east-1:123456789012:parameter/MyParameter

若要进行的调用将访问已解密的 SecureString 参数，请进行类似于以下示例的 HTTP GET 调用。


GET http://localhost:port/systemsmanager/parameters/get?name=MyParameter&withDecryption=true

您可以通过省略 withDecryption 或将其明确设置为 false 来指定未解密的参数。您还可以指定版本或标签，但不能同时指定两者。如果同时指定版本和标签，则仅使用置于 URL 中问号（?）之后的第一个字符。

Amazon 参数和密钥 Lambda 扩展 ARN

下表提供了支持架构和区域的扩展 ARN。

x86_64 和 x86 架构的扩展 ARN

区域	ARN
美国东部（俄亥俄）	`arn:aws:lambda:us-east-2:590474943231:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
美国东部（弗吉尼亚州北部）	`arn:aws:lambda:us-east-1:177933569100:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
美国西部（北加利福尼亚）	`arn:aws:lambda:us-west-1:997803712105:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
美国西部（俄勒冈州）	`arn:aws:lambda:us-west-2:345057560386:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
非洲（开普敦）	`arn:aws:lambda:af-south-1:317013901791:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
亚太地区（香港）	`arn:aws:lambda:ap-east-1:768336418462:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
亚太地区（海得拉巴）区域	`arn:aws:lambda:ap-south-2:070087711984:layer:AWS-Parameters-and-Secrets-Lambda-Extension:8`
亚太地区（雅加达）	`arn:aws:lambda:ap-southeast-3:490737872127:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
亚太地区（墨尔本）	`arn:aws:lambda:ap-southeast-4:090732460067:layer:AWS-Parameters-and-Secrets-Lambda-Extension:1`
亚太地区（孟买）	`arn:aws:lambda:ap-south-1:176022468876:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
亚太地区（大阪）	`arn:aws:lambda:ap-northeast-3:576959938190:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
亚太地区（首尔）	`arn:aws:lambda:ap-northeast-2:738900069198:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
亚太地区（新加坡）	`arn:aws:lambda:ap-southeast-1:044395824272:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
亚太地区（悉尼）	`arn:aws:lambda:ap-southeast-2:665172237481:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
亚太地区（东京）	`arn:aws:lambda:ap-northeast-1:133490724326:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
加拿大（中部）	`arn:aws:lambda:ca-central-1:200266452380:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
加拿大西部（卡尔加里）	`arn:aws:lambda:ca-west-1:243964427225:layer:AWS-Parameters-and-Secrets-Lambda-Extension:1`
中国（北京）	`arn:aws-cn:lambda:cn-north-1:287114880934:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
中国（宁夏）	`arn:aws-cn:lambda:cn-northwest-1:287310001119:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
欧洲地区（法兰克福）	`arn:aws:lambda:eu-central-1:187925254637:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
欧洲地区（爱尔兰）	`arn:aws:lambda:eu-west-1:015030872274:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
欧洲地区（伦敦）	`arn:aws:lambda:eu-west-2:133256977650:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
欧洲地区（米兰）	`arn:aws:lambda:eu-south-1:325218067255:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
欧洲地区（巴黎）	`arn:aws:lambda:eu-west-3:780235371811:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
欧洲地区（西班牙）区域	`arn:aws:lambda:eu-south-2:524103009944:layer:AWS-Parameters-and-Secrets-Lambda-Extension:8`
欧洲地区（斯德哥尔摩）	`arn:aws:lambda:eu-north-1:427196147048:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
以色列（特拉维夫）	`arn:aws:lambda:il-central-1:148806536434:layer:AWS-Parameters-and-Secrets-Lambda-Extension:1`
欧洲（苏黎世）	`arn:aws:lambda:eu-central-2:772501565639:layer:AWS-Parameters-and-Secrets-Lambda-Extension:8`
中东（巴林）	`arn:aws:lambda:me-south-1:832021897121:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
中东（阿联酋）	`arn:aws:lambda:me-central-1:858974508948:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
南美洲（圣保罗）	`arn:aws:lambda:sa-east-1:933737806257:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
Amazon GovCloud（美国东部）	`arn:aws-us-gov:lambda:us-gov-east-1:129776340158:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`
Amazon GovCloud（美国西部）	`arn:aws-us-gov:lambda:us-gov-west-1:127562683043:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11`

ARM64 和 Mac with Apple silicon 架构的扩展 ARN

区域	ARN
美国东部（俄亥俄）	`arn:aws:lambda:us-east-2:590474943231:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:11`
美国东部（弗吉尼亚州北部）	`arn:aws:lambda:us-east-1:177933569100:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:11`
美国西部（北加利福尼亚）区域	`arn:aws:lambda:us-west-1:997803712105:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`
US West（Oregon）	`arn:aws:lambda:us-west-2:345057560386:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:11`
非洲（开普敦）区域	`arn:aws:lambda:af-south-1:317013901791:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`
亚太地区（香港）区域	`arn:aws:lambda:ap-east-1:768336418462:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`
亚太地区（雅加达）区域	`arn:aws:lambda:ap-southeast-3:490737872127:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`
亚太地区（孟买）	`arn:aws:lambda:ap-south-1:176022468876:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:11`
亚太地区（大阪）	`arn:aws:lambda:ap-northeast-3:576959938190:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`
亚太地区（首尔）区域	`arn:aws:lambda:ap-northeast-2:738900069198:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`
亚太地区（新加坡）	`arn:aws:lambda:ap-southeast-1:044395824272:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:11`
亚太地区（悉尼）	`arn:aws:lambda:ap-southeast-2:665172237481:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:11`
亚太地区（东京）	`arn:aws:lambda:ap-northeast-1:133490724326:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:11`
加拿大（中部）区域	`arn:aws:lambda:ca-central-1:200266452380:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`
欧洲地区（法兰克福）	`arn:aws:lambda:eu-central-1:187925254637:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:11`
欧洲地区（爱尔兰）	`arn:aws:lambda:eu-west-1:015030872274:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:11`
欧洲地区（伦敦）	`arn:aws:lambda:eu-west-2:133256977650:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:11`
欧洲地区（米兰）	`arn:aws:lambda:eu-south-1:325218067255:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`
欧洲地区（巴黎）区域	`arn:aws:lambda:eu-west-3:780235371811:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`
欧洲地区（斯德哥尔摩）区域	`arn:aws:lambda:eu-north-1:427196147048:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`
中东（巴林）区域	`arn:aws:lambda:me-south-1:832021897121:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`
南美洲（圣保罗）区域	`arn:aws:lambda:sa-east-1:933737806257:layer:AWS-Parameters-and-Secrets-Lambda-Extension-Arm64:8`

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

通过 Parameter Store 参数引用 Amazon Secrets Manager 密钥

与其他产品和服务的集成