为 Elastic Beanstalk 环境变量获取密钥与参数

Elastic Beanstalk 可以在实例引导期间从 AWS Secrets Manager AWS Systems Manager 参数存储中提取值，并将其分配给环境变量以供应用程序使用。

以下要点总结了使用环境变量作为密钥的配置、同步与访问方式：

通过指定环境变量将存储的密钥和参数对应的 Amazon 资源名称（ARN）来配置存储密钥信息的环境变量。
在 Secrets Manager 或 Systems Manager Parameter Store 中更新或轮换密钥值后，您必须手动刷新环境变量。
密钥环境变量可用于 ebextension 容器命令和平台钩子。

支持的平台版本

2025 年 3 月 26 日当天或之后发布的平台版本支持配置为环境变量 AWS Secrets Manager 的机密和 AWS Systems Manager 参数存储参数。

注意

除基于 Docker 和 ECS 的 Docker 平台外，Amazon Linux 2 平台版本均不支持多行变量值。有关多行变量支持的更多信息，请参阅多行值。

定价

使用 Secrets Manager 和 Systems Manager Parameter Store 需支付标准费用。有关定价的更多信息，请参阅以下网站：

AWS Secrets Manager 定价
AWS Systems Manager 定价（从内容列表中选择参数存储）

对于应用程序通过环境变量引用的环境密钥，Elastic Beanstalk 不会收取额外费用。但 Elastic Beanstalk 代您向这些服务发起的 API 请求仍需支付标准费用。

将密钥配置为 Elastic Beanstalk 环境变量

您可以使用 Elastic Beanstalk 控制台、中的配置文件.ebextensions、 AWS CLI 和 AWS 软件开发工具包将密钥和参数配置为环境变量。

主题

先决条件
使用控制台
使用 .ebextensions 中的文件进行配置
使用进行配置 AWS CLI
使用进行配置 AWS SDK

先决条件

在设置环境变量以引用密钥之前，首先需要完成以下步骤。

配置环境变量前的通用准备工作

创建 Secrets Manager 密钥或 Parameter Store 参数来存储您的敏感数据。有关更多信息，请参阅下列两个主题或其中之一：
- 在使用 Secrets Manager 创建和检索密钥中创建密钥
- 在使用 Systems Manager Parameter Store 创建和检索参数中创建参数
为您环境的 EC2 实例设置所需的 IAM 权限以获取密钥和参数。有关更多信息，请参阅所需的 IAM 权限。

使用控制台

您可以通过 Elastic Beanstalk 控制台将密钥配置为环境变量。

通过 Elastic Beanstalk 控制台将密钥配置为环境变量

打开 E lastic Beanstalk 控制台，然后在区域列表中选择您的。 AWS 区域
在导航窗格中，选择 Environments（环境），然后从列表中选择环境的名称。
在导航窗格中，选择 Configuration（配置）。
在 Updates, monitoring, and logging（更新、监控和日志记录）配置类别中，选择 Edit（编辑）。
向下滚动到运行时环境变量。
选择添加环境变量。
对于来源，选择 Secrets Manager 或 SSM Parameter Store。

注意
有关下拉列表中纯文本选项的更多信息，请参阅配置环境属性（环境变量）。
对于环境变量名称，输入用于保存密钥或参数值的环境变量名称。
对于环境变量值，输入 Systems Manager Parameter Store 参数或 Secrets Manager 密钥的 ARN。在实例引导期间，Elastic Beanstalk 会将您在步骤 8 中输入的变量值初始化为存储在此 ARN 资源中的值。

控制台会验证您输入的值对您在步骤 7 中选择的存储是否是有效的 ARN 格式。但是，它不会验证 ARN 指定的资源是否存在，也不会验证您是否拥有访问该资源所需的 IAM 权限。
如需添加更多变量，请重复步骤 6 至步骤 9。
要保存更改，请选择页面底部的 Apply（应用）。

使用 .ebextensions 中的文件进行配置

您可以通过 Elastic Beanstalk 配置文件将密钥配置为环境变量。使用aws:elasticbeanstalk:application:environmentsecrets命名空间定义环境属性。

注意

Secrets Manager 会自动以 ARN 格式向密钥名称添加 6 个随机字符，以确保唯一性。

例。ebextensions/options.config 用于存储环境机密 (速记语法)


option_settings:
  aws:elasticbeanstalk:application:environmentsecrets:
    MY_SECRET: arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret-AbCd12
    MY_PARAMETER: arn:aws:ssm:us-east-1:111122223333:parameter/myparam

例。ebextensions/options.config 用于存储环境机密 (标准语法)


option_settings:
  - namespace: aws:elasticbeanstalk:application:environmentsecrets
    option_name: MY_SECRET
    value: arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret-AbCd12
  - namespace: aws:elasticbeanstalk:application:environmentsecrets
    option_name: MY_PARAMETER
    value: arn:aws:ssm:us-east-1:111122223333:parameter/myparam

使用进行配置 AWS CLI

您可以使用 AWS 命令行接口 (AWS CLI) 将密钥配置为 Elastic Beanstalk 环境变量。本节提供包含 aws:elasticbeanstalk:application:environmentsecrets 命名空间 create-environment 和 update-environment 命令的示例。Elastic Beanstalk 为这些命令所引用的环境引导 EC2 实例时，它会使用获取的密钥和参数值来初始化环境变量。它从 Secrets Manager 和 Systems Manager Parameter Store 相应的 ARN 中获取这些值。

以下两个示例使用 create-environment 命令分别添加一个密钥和一个参数，并将其配置为名为 MY_SECRET 和 MY_PARAMETER 的环境变量。

例：使用 create-environment 命令将密钥配置为环境变量（内联命名空间选项）


aws elasticbeanstalk create-environment \
--region us-east-1 \
--application-name my-app \
--environment-name my-env \
--platform-arn "arn:aws:elasticbeanstalk:::platform/Node.js 24 running on 64bit Amazon Linux 2023" \
--option-settings \
Namespace=aws:autoscaling:launchconfiguration,OptionName=IamInstanceProfile,Value=aws-elasticbeanstalk-ec2-role \
Namespace=aws:elasticbeanstalk:application:environmentsecrets,OptionName=MY_SECRET,Value=arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret-AbCd12 \
Namespace=aws:elasticbeanstalk:application:environmentsecrets,OptionName=MY_PARAMETER,Value=arn:aws:ssm:us-east-1:111122223333:parameter/myparam

作为替代方法，请使用 options.json 文件来指定命名空间选项，而不是将其内联。

例创建环境的密钥配置为环境变量（中的命名空间选项） `选项.json` 文件）


aws elasticbeanstalk create-environment \
--region us-east-1 \
--application-name my-app \
--environment-name my-env \
--platform-arn "arn:aws:elasticbeanstalk:::platform/Node.js 24 running on 64bit Amazon Linux 2023" \
--option-settings file://options.json

例


### example options.json ###
[
  {
    "Namespace": "aws:autoscaling:launchconfiguration",
    "OptionName": "IamInstanceProfile",
    "Value": "aws-elasticbeanstalk-ec2-role"
  },
  {
    "Namespace": "aws:elasticbeanstalk:application:environmentsecrets",
    "OptionName": "MY_SECRET",
    "Value": "arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret-AbCd12"
  },
  {
    "Namespace": "aws:elasticbeanstalk:application:environmentsecrets",
    "OptionName": "MY_PARAMETER",
    "Value": "arn:aws:ssm:us-east-1:111122223333:parameter/myparam"
  }
]

下一个示例配置名为 MY_SECRET 和 MY_PARAMETER 的环境变量，以存储现有环境的密钥和参数。update-environment 命令会传递与 create-environment 命令语法相同的选项，既支持内联方式传入参数，也支持通过 options.json 文件进行配置。以下示例展示了使用与之前示例相同的 options.json 文件来执行命令。

例将机密配置为环境变量的更新环境（中的命名空间选项） `选项.json` 文件）


aws elasticbeanstalk update-environment \
--region us-east-1 \
--application-name my-app \
--environment-name my-env \
--platform-arn "arn:aws:elasticbeanstalk:::platform/Node.js 24 running on 64bit Amazon Linux 2023" \
--option-settings file://options.json

使用进行配置 AWS SDK

通过 AWS SDK 将密钥或参数配置为环境变量。与上一节中提到的update-environment和create-environment AWS CLI 命令类似，您可以使用CreateEnvironment和 UpdateEnvironment API 操作。使用 OptionSettings 请求参数来指定 aws:elasticbeanstalk:application:environmentsecrets 命名空间的选项。

从密钥管理器密钥中提取 JSON 密钥

2026 年 1 月 13 日当天或之后发布的平台版本支持通过向 JSON-formatted 机密 ARN 附加冒号和 JSON 密钥名称来从密钥管理器密钥中提取特定字段。这允许您引用密钥中的单个密钥值对，而不是整个密钥。

语法

要从密钥中提取特定的 JSON 密钥，请在密钥 AR :json-key-name N 后面追加：


arn:aws:secretsmanager:region:account:secret:secret-name-XXXXXX:json-key-name

JSON 密钥提取可以使用与常规环境密钥相同的方法进行配置：控制台、中的配置文件.ebextensions、 AWS CLI 或 AWS SDK。

限制

JSON 密钥提取仅支持密钥管理器密钥，不支持系统管理器参数存储参数。
仅支持顶级 JSON 密钥。不支持嵌套密钥访问（例如，config.database.host）和数组索引（例如，servers[0]）。如果您需要访问嵌套值，请提取父对象并在应用程序代码中对其进行解析。使用顶级密钥访问的嵌套对象和数组将序列化回 JSON 格式。
JSON 密钥名称不能包含冒号 (:) 字符。冒号在 ARN 语法中保留为分隔符。如果 JSON 密钥名称包含冒号，则仅使用第一个冒号之前的部分作为密钥名称，冒号后面的所有字符都将被忽略。
ECS 托管的 Docker 平台使用原生 ECS 语法来引用密钥。有关更多信息，请参阅《亚马逊弹性容器服务开发人员指南》中的通过 Amaz on ECS 环境变量传递密钥管理器密钥。

示例

以下示例演示如何从 JSON 密钥中提取不同的值类型。鉴于这个秘密：


{
  "stringKey": "value1",
  "numberKey": 42,
  "objectKey": {
    "nested": "data"
  },
  "arrayKey": ["item1", "item2"]
}

你可以在以下位置配置提取.ebextensions：

例带有 JSON 密钥提取的.ebextensions


option_settings:
  aws:elasticbeanstalk:application:environmentsecrets:
    STRING_VAR: arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret-AbCd12:stringKey
    NUMBER_VAR: arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret-AbCd12:numberKey
    OBJECT_VAR: arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret-AbCd12:objectKey
    ARRAY_VAR: arn:aws:secretsmanager:us-east-1:111122223333:secret:mysecret-AbCd12:arrayKey

这会导致以下环境变量：

STRING_VAR=value1
NUMBER_VAR=42
OBJECT_VAR={"nested":"data"}
ARRAY_VAR=["item1","item2"]

将密钥与 Elastic Beanstalk 环境变量同步的最佳实践

本主题为您推荐在应用程序中将环境密钥与 Secrets Manager 或 Systems Manager Parameter Store 配合使用时的最佳实践。如果密钥存储数据更新或轮换，您的 Elastic Beanstalk 应用程序将不会自动接收更新后的值。Elastic Beanstalk 仅会在实例引导时将密钥提取到环境变量中。

刷新环境变量

要触发您的 Elastic Beanstalk 环境从密钥存储中重新获取密钥的最新值，建议您运行 UpdateEnvironment 或 RestartAppServer 操作。您可以通过 Elastic Beanstalk 控制台、 AWS CLI或 Elastic Beanstalk API 运行这些操作。有关更多信息，请参阅 Elastic Beanstalk 的AWS CLI 示例或《AWS Elastic Beanstalk API 参考》。https://docs.aws.amazon.com/elasticbeanstalk/latest/api/

管理自动扩缩对密钥同步的影响

如果在密钥存储更新后发生横向扩展事件或实例替换，则出现的新实例将具有来自 Secrets Manager 或 Systems Manager Parameter Store 的最新密钥值。即使并非环境中的所有其他实例都已刷新以检索新密钥，也可能发生此类事件。

重要

必须确保您的应用程序能够处理同一环境变量对应两个不同密钥值的情况。这种设计旨在应对以下场景：当 Secrets Manager 或 Systems Manager Parameter Store 中的密钥完成更新后，您的环境可能正在进行横向扩展或实例替换，而其他实例的环境变量尚未刷新。在此刷新等待期间，并非环境中所有实例的密钥存储环境变量都会具有相同的值。

这种应用场景的一个例子就是数据库凭证轮换。当凭证轮换之后出现横向扩展事件时，新引导的实例引用的环境密钥包含更新后的数据库凭证。但是，现有实例引用的环境密钥会保留旧值，直到通过 UpdateEnvironment 或 RestartAppServer 操作刷新。

Amazon Linux 2 环境变量中的多行值

多行值由多行文本组成，包含一个换行符。除了 Docker 和 Doc ECS-based ker 平台外，在 Amazon Linux 2 上运行的平台不支持环境变量的多行值

注意

如果 Elastic Beanstalk 检测到多行值，将导致相关环境部署失败。

针对多行值问题，可参考以下替代方法或解决方案：

从 Amazon Linux 2 环境升级到 Amazon Linux 2023。有关更多信息，请参阅从 Amazon Linux 2 迁移到 Amazon Linux 2023。
从密钥值中删除换行符。方案一：将值进行 Base64 编码，然后存入密钥存储。应用程序从环境密钥变量获取值后，需执行解码将值还原为原始格式。
设计应用程序代码，使其可以直接从 Secrets Manager 或 Systems Manager Parameter Store 检索数据。有关更多信息，请参阅使用 Secrets Manager中的检索密钥或使用 Systems Manager Parameter Store中的检索参数。

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

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

文档惯例

Secrets Manager 和 Systems Manager Parameter Store

所需的 IAM 权限