本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 为 Elastic Beanstalk 环境变量获取密钥与参数
<a name="AWSHowTo.secrets.env-vars"></a>

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

以下要点总结了使用环境变量作为密钥的配置、同步与访问方式：
+ 通过为要存储的密钥和参数指定 Amazon 资源名称 (ARNs)，将您的环境变量配置为存储密钥。
+ 在 Secrets Manager 或 Systems Manager Parameter Store 中更新或轮换密钥值后，您必须手动刷新环境变量。
+ 密钥环境变量可用于 [ebextension](platforms-linux-extend.config-files.md) 容器命令和[平台钩子](platforms-linux-extend.hooks.md)。

**支持的平台版本**  
[2025 年 3 月 26 日](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2025-03-26-windows.html)当天或之后发布的平台版本支持配置为环境变量的 AWS Secrets Manager 密钥和 AWS Systems Manager 参数存储参数。

**注意**  
除基于 Docker 和 ECS 的 Docker 平台外，Amazon Linux 2 平台版本均不支持多行变量值。有关多行变量支持的更多信息，请参阅[多行值](#AWSHowTo.secrets.multiline)。

**Topics**
+ [

## 定价
](#AWSHowTo.secrets.pricing)
+ [

## 将密钥配置为 Elastic Beanstalk 环境变量
](#AWSHowTo.secrets.configure-env-vars)
+ [

## 从 Secrets Manager 密钥中提取 JSON 密钥
](#AWSHowTo.secrets.json)
+ [

## 将密钥与 Elastic Beanstalk 环境变量同步的最佳实践
](#AWSHowTo.secrets.rotating-secrets)
+ [

## Amazon Linux 2 环境变量中的多行值
](#AWSHowTo.secrets.multiline)

## 定价
<a name="AWSHowTo.secrets.pricing"></a>

使用 Secrets Manager 和 Systems Manager Parameter Store 需支付标准费用。有关定价的更多信息，请参阅以下网站：
+ [AWS Secrets Manager 定价](https://aws.amazon.com/secrets-manager/pricing)
+ [AWS Systems Manager 定价](https://aws.amazon.com/systems-manager/pricing/)（从内容列表*中选择 Parameter Store*）

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

## 将密钥配置为 Elastic Beanstalk 环境变量
<a name="AWSHowTo.secrets.configure-env-vars"></a>

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

**Topics**
+ [

### 先决条件
](#AWSHowTo.secrets.configure-env-vars.prerequisites)
+ [

### 使用控制台
](#AWSHowTo.secrets.configure-env-vars.console)
+ [

### 使用 .ebextensions 中的文件进行配置
](#AWSHowTo.secrets.configure-env-vars.config-file)
+ [

### 使用进行配置 AWS CLI
](#AWSHowTo.secrets.configure-env-vars.aws-cli)
+ [

### 使用 AWS SDK 进行配置
](#AWSHowTo.secrets.configure-env-vars.aws-sdk)

### 先决条件
<a name="AWSHowTo.secrets.configure-env-vars.prerequisites"></a>

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

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

1. 创建 Secrets Manager 密钥或 Parameter Store 参数来存储您的敏感数据。有关更多信息，请参阅下列两个主题或其中之一：
   + 在 [使用 Secrets Manager 创建和检索密钥](AWSHowTo.secrets.Secrets-Manager-and-Parameter-Store.md#AWSHowTo.secrets.Secrets-Manager) 中*创建密钥*
   + 在 [使用 Systems Manager Parameter Store 创建和检索参数](AWSHowTo.secrets.Secrets-Manager-and-Parameter-Store.md#AWSHowTo.secrets.SSM-parmameter-store) 中创建*参数*

1. 为您环境的 EC2 实例设置所需的 IAM 权限以获取密钥和参数。有关更多信息，请参阅 [所需的 IAM 权限](AWSHowTo.secrets.IAM-permissions.md)。

### 使用控制台
<a name="AWSHowTo.secrets.configure-env-vars.console"></a>

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

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

1. 打开 [Elastic Beanstalk](https://console.aws.amazon.com/elasticbeanstalk) 控制台，然后**在 “区域” 列表中，选择您**的。 AWS 区域

1. 在导航窗格中，选择 **Environments**（环境），然后从列表中选择环境的名称。

1. 在导航窗格中，选择 **Configuration**（配置）。

1. 在 **Updates, monitoring, and logging**（更新、监控和日志记录）配置类别中，选择 **Edit**（编辑）。

1. 向下滚动到**运行时环境变量**。

1. 选择**添加环境变量**。

1. 对于**来源**，选择 **Secrets Manager** 或 **SSM Parameter Store**。
**注意**  
有关下拉列表中**纯文本**选项的更多信息，请参阅[配置环境属性（环境变量）](environments-cfg-softwaresettings.md#environments-cfg-softwaresettings-console)。

1. 对于**环境变量名称**，输入用于保存密钥或参数值的环境变量名称。

1. 对于**环境变量值**，输入 Systems Manager Parameter Store 参数或 Secrets Manager 密钥的 ARN。在实例引导期间，Elastic Beanstalk 会将您在**步骤 8** 中输入的变量值初始化为存储在此 ARN 资源中的值。

   控制台会验证您输入的值对您在**步骤 7** 中选择的存储是否是有效的 ARN 格式。但是，它不会验证 ARN 指定的资源是否存在，也不会验证您是否拥有访问该资源[所需的 IAM 权限](AWSHowTo.secrets.IAM-permissions.md)。

1. 如需添加更多变量，请重复**步骤 6** 至**步骤 9**。

1. 要保存更改，请选择页面底部的 **Apply**（应用）。

### 使用 .ebextensions 中的文件进行配置
<a name="AWSHowTo.secrets.configure-env-vars.config-file"></a>

您可以通过 Elastic Beanstalk [配置文件](ebextensions.md)将密钥配置为环境变量。使用[aws:elasticbeanstalk:application:environmentsecrets](command-options-general.md#command-options-general-elasticbeanstalk-application-environmentsecrets)命名空间来定义环境属性。

**注意**  
Secrets Manager 会自动在 ARN 格式的机密名称中附加 6 个随机字符，以确保唯一性。

**Example ：用于环境密钥的 .ebextensions/options.config（[速记语法](ebextensions-optionsettings.md#ebextensions-optionsettings.title)）**  

```
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
```

**Example ：用于环境密钥的 .ebextensions/options.config（[标准语法](ebextensions-optionsettings.md#ebextensions-optionsettings.title)）**  

```
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
<a name="AWSHowTo.secrets.configure-env-vars.aws-cli"></a>

您可以使用 AWS 命令行界面 (AWS CLI) 将密钥配置为 Elastic Beanstalk 环境变量。本节提供包含 [aws:elasticbeanstalk:application:environmentsecrets](command-options-general.md#command-options-general-elasticbeanstalk-application-environmentsecrets) 命名空间 [create-environment](https://docs.aws.amazon.com/cli/latest/reference/elasticbeanstalk/create-environment.html) 和 [update-environment](https://docs.aws.amazon.com/cli/latest/reference/elasticbeanstalk/update-environment.html) 命令的示例。Elastic Beanstalk 为这些命令所引用的环境引导 EC2 实例时，它会使用获取的密钥和参数值来初始化环境变量。它分别 ARNs 从 Secrets Manager 和 Systems Manager 参数存储库中获取这些值。

 

以下两个示例使用 [create-environment](https://docs.aws.amazon.com/cli/latest/reference/elasticbeanstalk/create-environment.html) 命令分别添加一个密钥和一个参数，并将其配置为名为 `MY_SECRET` 和 `MY_PARAMETER` 的环境变量。

**Example ：使用 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` 文件来指定命名空间选项，而不是将其内联。

**Example ：使用 create-environment 命令将密钥配置为环境变量（`options.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**  

```
### 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](https://docs.aws.amazon.com/cli/latest/reference/elasticbeanstalk/update-environment.html) 命令会传递与 `create-environment` 命令语法相同的选项，既支持内联方式传入参数，也支持通过 `options.json` 文件进行配置。以下示例展示了使用与之前示例相同的 `options.json` 文件来执行命令。



**Example ：使用 update-environment 命令将密钥配置为环境变量（`options.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 进行配置
<a name="AWSHowTo.secrets.configure-env-vars.aws-sdk"></a>

您可以使用将密钥和参数配置为环境变量[AWS SDKs](https://docs.aws.amazon.com//code-library/)。与上一节中提到的`update-environment`和`create-environment` AWS CLI 命令类似，您可以使用[CreateEnvironment](https://docs.aws.amazon.com//elasticbeanstalk/latest/api/API_CreateEnvironment.html)和 [UpdateEnvironment](https://docs.aws.amazon.com//elasticbeanstalk/latest/api/API_UpdateEnvironment.html)API 操作。使用 `OptionSettings` 请求参数来指定 [aws:elasticbeanstalk:application:environmentsecrets](command-options-general.md#command-options-general-elasticbeanstalk-application-environmentsecrets) 命名空间的选项。

## 从 Secrets Manager 密钥中提取 JSON 密钥
<a name="AWSHowTo.secrets.json"></a>

[2026 年 1 月 13 日](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2026-01-13-al2023.html)当天或之后发布的平台版本支持通过在密钥 ARN 中附加冒号和 JSON 密钥名称来从 JSON 格式的 Secrets Manager 密钥中提取特定字段。这允许您引用密钥中的单个键值对，而不是整个密钥。

### 语法
<a name="AWSHowTo.secrets.json.syntax"></a>

要从密钥中提取特定的 JSON 密钥，`:json-key-name`请将其附加到密钥 ARN：

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

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

### 限制
<a name="AWSHowTo.secrets.json.limitations"></a>
+ 仅支持 Secrets Manager 密钥提取，**不**支持 Systems Manager 参数存储库参数。
+ 仅支持顶级 JSON 密钥。**不**支持嵌套密钥访问（例如`config.database.host`）和数组索引（例如`servers[0]`）。如果您需要访问嵌套值，请提取父对象并在应用程序代码中对其进行解析。使用顶级密钥访问的嵌套对象和数组将序列化回 JSON 格式。
+ JSON 密钥名称不能包含冒号 (`:`) 字符。在 ARN 语法中，冒号保留为分隔符。如果 JSON 密钥名称包含冒号，则仅使用第一个冒号之前的部分作为键名，而忽略冒号之后的任何字符。
+ ECS 托管 Docker 平台使用原生 ECS 语法来引用密钥。有关更多信息，请参阅亚马逊*弹性容器服务开发人员指南*[中的通过 Amazon ECS 环境变量传递 Secrets Manager 密钥](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/secrets-envvar-secrets-manager.html)。

### 示例
<a name="AWSHowTo.secrets.json.example"></a>

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

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

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

**Example 使用 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 环境变量同步的最佳实践
<a name="AWSHowTo.secrets.rotating-secrets"></a>

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

### 刷新环境变量
<a name="AWSHowTo.secrets.rotating-secrets.refresh-env-vars"></a>

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

### 管理自动扩缩对密钥同步的影响
<a name="AWSHowTo.secrets.rotating-secrets.as-effects"></a>

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

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

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

## Amazon Linux 2 环境变量中的多行值
<a name="AWSHowTo.secrets.multiline"></a>

*多行*值由多行文本组成，包含一个换行符。除基于 Docker 和 ECS 的 Docker 平台外，在 Amazon Linux 2 上运行的平台均不支持多行变量值

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



针对多行值问题，可参考以下替代方法或解决方案：
+ 从 Amazon Linux 2 环境升级到 Amazon Linux 2023。有关更多信息，请参阅 [从 Amazon Linux 2 迁移到 Amazon Linux 2023](using-features.migration-al.generic.from-al2.md)。
+ 从密钥值中删除换行符。方案一：将值进行 Base64 编码，然后存入密钥存储。应用程序从环境密钥变量获取值后，需执行解码将值还原为原始格式。
+ 设计应用程序代码，使其可以直接从 Secrets Manager 或 Systems Manager Parameter Store 检索数据。有关更多信息，请参阅[使用 Secrets Manager](AWSHowTo.secrets.Secrets-Manager-and-Parameter-Store.md#AWSHowTo.secrets.Secrets-Manager)中的*检索密钥*或[使用 Systems Manager Parameter Store](AWSHowTo.secrets.Secrets-Manager-and-Parameter-Store.md#AWSHowTo.secrets.SSM-parmameter-store)中的*检索参数*。