本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 擷取 Elastic Beanstalk 環境變數的秘密和參數 Elastic Beanstalk 可以在執行個體引導期間從 AWS Secrets Manager 和 AWS Systems Manager 參數存放區擷取值，並將其指派給環境變數，以供應用程式使用。 下列要點摘要說明使用環境變數做為秘密的組態、同步和存取： + 透過為要存放的秘密和參數指定 Amazon Resource Name (ARNs)，設定您的環境變數來存放秘密。 + 在 Secrets Manager 或 Systems Manager 參數存放區中更新或輪換秘密值時，您必須手動重新整理環境變數。 + 秘密環境變數可用於 [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) ## 定價 使用 Secrets Manager 和 Systems Manager 參數存放區需支付標準費用。如需定價的詳細資訊，請參閱下列網站： + [AWS Secrets Manager 定價](https://aws.amazon.com/secrets-manager/pricing) + [AWS Systems Manager 定價](https://aws.amazon.com/systems-manager/pricing/) （從內容清單中選取*參數存放區*) Elastic Beanstalk 不會向您的應用程式收取透過環境變數參考環境秘密的費用。不過，標準費用確實適用於 Elastic Beanstalk 代表您對這些服務提出的請求。 ## 將秘密設定為 Elastic Beanstalk 環境變數 您可以使用 Elastic Beanstalk 主控台、 中的組態檔案、CLI `.ebextensions` AWS 和 AWS SDK，將秘密和參數設定為環境變數。 **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) ### 先決條件 您必須先完成下列步驟，才能設定環境變數來參考秘密。 **環境變數組態之前的一般程序** 1. 建立 Secrets Manager 秘密或參數存放區參數，以存放您的敏感資料。如需詳細資訊，請參閱下列其中一個或兩個主題： + 在 *中建立秘密* [使用 Secrets Manager 建立和擷取秘密](AWSHowTo.secrets.Secrets-Manager-and-Parameter-Store.md#AWSHowTo.secrets.Secrets-Manager) + 在 中*建立參數* [使用 Systems Manager 參數存放區建立和擷取參數](AWSHowTo.secrets.Secrets-Manager-and-Parameter-Store.md#AWSHowTo.secrets.SSM-parmameter-store) 1. 為環境的 EC2 執行個體設定必要的 IAM 許可，以擷取秘密和參數。如需詳細資訊，請參閱[所需的 IAM 許可](AWSHowTo.secrets.IAM-permissions.md)。 ### 使用主控台 您可以使用 Elastic Beanstalk 主控台將秘密設定為環境變數。 **在 Elastic Beanstalk 主控台中將秘密設定為環境變數** 1. 開啟 [Elastic Beanstalk 主控台](https://console.aws.amazon.com/elasticbeanstalk)，然後在**區域**清單中選取您的 AWS 區域。 1. 在導覽窗格中，選擇**環境**，然後在清單中選擇您環境的名稱。 1. 在導覽窗格中，選擇**組態**。 1. 在**更新、監控和日誌記錄**組態類別中，選擇**編輯**。 1. 向下捲動至**執行期環境變數**。 1. 選取**新增環境變數**。 1. 針對**來源**選取 **Secrets Manager** 或 **SSM 參數存放區**。 **注意** 如需下拉式清單中**純文字**選項的詳細資訊，請參閱 [設定環境屬性 (環境變數)](environments-cfg-softwaresettings.md#environments-cfg-softwaresettings-console)。 1. 針對**環境變數名稱**，輸入環境變數的名稱，以保留秘密或參數值。 1. 對於**環境變數值**，輸入 Systems Manager 參數存放區參數的 ARN 或 Secrets Manager 秘密。在執行個體引導期間，Elastic Beanstalk 會將您在**步驟 8** 中輸入的變數值啟動為此 ARN 資源中存放的值。 主控台會驗證您輸入的值是否為您在**步驟 7** 中選取之存放區的有效 ARN 格式。不過，它不會驗證 ARN 指定的資源是否存在，或者您是否具有存取該資源[所需的 IAM 許可](AWSHowTo.secrets.IAM-permissions.md)。 1. 如果您需要新增更多變數，請重複步驟 **6** 到**步驟 9**。 1. 若要儲存變更，請選擇頁面底部的**儲存變更**。 ### 在 .ebextensions 中使用檔案的組態 您可以使用 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 您可以使用 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 執行個體時，它會使用擷取的秘密和參數值初始化環境變數。它會從 Secrets Manager 和 Systems Manager 參數存放區的個別 ARNs 擷取這些值。 下列兩個範例使用 [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 的組態 您可以使用 [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 金鑰 [2026 年 1 月 13](https://docs.aws.amazon.com/elasticbeanstalk/latest/relnotes/release-2026-01-13-al2023.html) 日當天或之後發行的平台版本支援透過將冒號和 JSON 金鑰名稱附加至秘密 ARN，從 JSON 格式的 Secrets Manager 秘密擷取特定欄位。這可讓您參考秘密中的個別鍵值對，而不是整個秘密。 ### 語法 若要從秘密中擷取特定 JSON 金鑰，請附加`:json-key-name`至秘密 ARN： ``` arn:aws:secretsmanager:region:account:secret:secret-name-XXXXXX:json-key-name ``` 您可以使用與一般環境秘密相同的方法來設定 JSON 金鑰擷取：主控台、、`.ebextensions` AWS CLI 或 AWS SDKs 中的組態檔案。 ### 限制 + JSON 金鑰擷取僅支援 Secrets Manager 秘密，**不支援** Systems Manager 參數存放區參數。 + 僅支援最上層 JSON 金鑰。**不支援**巢狀金鑰存取 （例如 `config.database.host`) 和陣列索引 （例如 `servers[0]`)。如果您需要存取巢狀值，請擷取父物件，並在應用程式程式碼中剖析。使用頂層金鑰存取的巢狀物件和陣列會序列化回 JSON 格式。 + JSON 金鑰名稱不能包含冒號 (`:`) 字元。顏色在 ARN 語法中保留為分隔符號。如果 JSON 金鑰名稱包含冒號，則只會使用第一個冒號之前的部分做為金鑰名稱，並忽略冒號之後的任何字元。 + ECS 受管 Docker 平台使用原生 ECS 語法來參考秘密。如需詳細資訊，請參閱《[Amazon Elastic Container Service 開發人員指南》中的透過 Amazon ECS 環境變數傳遞 Secrets Manager 秘密](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/secrets-envvar-secrets-manager.html)。 ** ### 範例 下列範例示範如何從 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 環境變數同步的最佳實務 本主題建議應用程式的最佳實務，以搭配 Secrets Manager 或 Systems Manager 參數存放區使用環境秘密。如果秘密存放區資料已更新或輪換，您的 Elastic Beanstalk 應用程式就不會自動收到更新的值。Elastic Beanstalk 只會在執行個體引導時將秘密提取至環境變數。 ### 重新整理您的環境變數 若要觸發 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/)。 ### 管理對秘密同步的自動擴展效果 如果在秘密存放區更新後發生橫向擴展事件或執行個體替換，則出現的新執行個體將具有來自 Secrets Manager 或 Systems Manager 參數存放區的最新秘密值。即使尚未重新整理環境中的所有其他執行個體來擷取新的秘密，也會發生此類事件。 **重要** 您必須確保您的應用程式能夠為相同的環境變數使用兩個不同的秘密值。這可容納 Secrets Manager 或 Systems Manager 參數存放區中發生秘密更新的事件，後面接著您環境中的橫向擴展或執行個體替換，而其他執行個體正在等待環境變數重新整理。在重新整理的等待期間，並非所有環境執行個體都會具有與秘密存放區環境變數相同的值。 這類使用案例的範例是資料庫登入資料輪換。當擴展事件遵循登入資料輪換時，新引導的執行個體所參考的環境秘密會包含更新的資料庫登入資料。不過，現有執行個體參考的環境秘密會保留舊值，直到 `UpdateEnvironment`或 `RestartAppServer`操作重新整理為止。 ## Amazon Linux 2 環境變數中的多行值 *多行*值由多行組成，並包含換行字元。除了 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 參數存放區擷取資料。如需詳細資訊，請參閱*在 中擷取秘密*[使用 Secrets Manager](AWSHowTo.secrets.Secrets-Manager-and-Parameter-Store.md#AWSHowTo.secrets.Secrets-Manager)或*擷取參數* [使用 Systems Manager 參數存放區](AWSHowTo.secrets.Secrets-Manager-and-Parameter-Store.md#AWSHowTo.secrets.SSM-parmameter-store)。