获取 Secrets Manager 中的密钥或密钥值 - Amazon CloudFormation
最佳实践注意事项权限引用模式示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

获取 Secrets Manager 中的密钥或密钥值

Secrets Manager 是一项便于您安全存储和管理密钥的服务，例如数据库凭证、密码和第三方 API 密钥等。使用 Secrets Manager，您可以集中存储和控制对这些密钥的访问，以便使用对 Secrets Manager 的 API 调用来替换代码中的硬编码凭证（包括密码），以编程方式检索密钥。有关更多信息，请参阅《Amazon Secrets Manager 用户指南》中的什么是 Amazon Secrets Manager？。

要在 CloudFormation 模板中使用 Secrets Manager 中存储的全部密钥或密钥值，请使用 secretsmanager 动态引用。

最佳实践

在 CloudFormation 模板中使用 Secrets Manager 动态引用时，请遵循以下最佳实践：

  • 对 CloudFormation 模板使用无版本引用：将凭证存储在 Secrets Manager 中并使用动态引用而不指定 version-stage 或 version-id 参数，以支持正确的密钥轮换工作流程。

  • 利用自动轮换：使用 Secrets Manager 的自动轮换功能，结合无版本动态引用进行凭证管理。这可以确保您的凭证得到定期更新，而无需更改模板。有关更多信息，请参阅轮换 Amazon Secrets Manager 密钥。

  • 谨慎使用带版本引用：仅为测试或回滚等特定场景指定显式的 version-stage 或 version-id 参数。

注意事项

使用 secretsmanager 动态引用时，需要记住以下重要注意事项：

  • CloudFormation 不会追踪之前的部署中使用了哪个版本的密钥。在实现动态引用之前，请认真规划您的密钥管理策略。尽量使用无版本引用，以利用自动密钥轮换功能。在更改动态引用配置时（例如从无版本动态引用改换为带版本动态引用，反之亦然）时，监控和验证资源更新。

  • 仅更新 Secrets Manager 中的密钥值不会自动触发 CloudFormation 检索新值。CloudFormation 仅在创建或更新资源修改包含动态引用的资源时检索密钥值。

    例如，假设您的模板包含 AWS::RDS::DBInstance 资源，其中 MasterPassword 属性设置为 Secrets Manager 动态引用。使用此模板创建堆栈后，需要在 Secrets Manager 中更新密钥值。但是，MasterPassword 属性保留了旧密码值。

    要应用新密钥值，需修改 CloudFormation 模板中的 AWS::RDS::DBInstance 资源并执行堆栈更新。

    为避免将来执行这种手动过程，可考虑使用 Secrets Manager 自动轮换密钥。

  • 自定义资源中目前不支持对安全值的动态引用，例如 secretsmanager。

  • secretsmanager 动态引用可用于所有资源属性。使用 secretsmanager 动态引用表示 Secrets Manager 和 CloudFormation 日志均不应保留任何已解析的密钥值。但是，密钥值可能会显示在正在其资源中使用的服务中。检查您的使用情况，以避免泄露密钥数据。

权限

要指定存储在 Secrets Manager 中的密钥，您必须有权为该密钥调用 GetSecretValue。

引用模式

要在 CloudFormation 模板中引用 Secrets Manager 密钥，请使用以下 secretsmanager 引用模式。

{{resolve:secretsmanager:secret-id:secret-string:json-key:version-stage:version-id}}
secret-id

密钥的名称或 ARN。

要访问您的 Amazon Web Services 账户中的密钥，只需指定密钥名称即可。要访问其他 Amazon Web Services 账户中的密钥，请指定密钥的完整 ARN。

必需。

secret-string

SecretString 是唯一受支持的值。默认值为 SecretString。

json-key

要检索其值的键值对的键名称。如果您不指定 json-key，CloudFormation 会检索整个密钥文本。

此分段不得包含冒号字符 ( : )。

version-stage

要使用的密钥版本的暂存标签。Secrets Manager 在轮换过程中使用暂存标注来跟踪不同的版本。如果您使用 version-stage，则不要指定 version-id。如果您既未指定 version-stage，也未指定 version-id，则原定设置将为 AWSCURRENT 版本。

此分段不得包含冒号字符 ( : )。

version-id

要使用的密钥版本的唯一标识符。如果指定 version-id，则不要指定 version-stage。如果您既未指定 version-stage，也未指定 version-id，则原定设置将为 AWSCURRENT 版本。

此分段不得包含冒号字符 ( : )。

示例

从密钥中检索用户名和密码值

以下 AWS::RDS::DBInstance 示例检索在 MySecret 密钥中存储的用户名和密码值。此示例展示了无版本动态引用的推荐模式，该模式自动使用 AWSCURRENT 版本且支持 Secrets Manager 轮换工作流程，而无需更改模板。

JSON

{
    "MyRDSInstance": {
        "Type": "AWS::RDS::DBInstance",
        "Properties": {
            "DBName": "MyRDSInstance",
            "AllocatedStorage": "20",
            "DBInstanceClass": "db.t2.micro",
            "Engine": "mysql",
            "MasterUsername": "{{resolve:secretsmanager:MySecret:SecretString:username}}",
            "MasterUserPassword": "{{resolve:secretsmanager:MySecret:SecretString:password}}"
        }
    }
}

YAML

  MyRDSInstance:
    Type: AWS::RDS::DBInstance
    Properties:
      DBName: MyRDSInstance
      AllocatedStorage: '20'
      DBInstanceClass: db.t2.micro
      Engine: mysql
      MasterUsername: '{{resolve:secretsmanager:MySecret:SecretString:username}}'
      MasterUserPassword: '{{resolve:secretsmanager:MySecret:SecretString:password}}'

检索整个 SecretString

以下动态引用检索 MySecret 的 SecretString。

{{resolve:secretsmanager:MySecret}}

或者：

{{resolve:secretsmanager:MySecret::::}}

从密钥的特定版本中检索值

以下动态引用检索 MySecret 的 AWSPREVIOUS 版本的 password 值。

{{resolve:secretsmanager:MySecret:SecretString:password:AWSPREVIOUS}}

从另一个 Amazon Web Services 账户检索密钥

以下动态引用检索另一个 Amazon Web Services 账户中的 MySecret 的 SecretString。您必须指定完整的密钥 ARN 才能访问其他 Amazon Web Services 账户中的密钥。

{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret}}

以下动态引用检索另一个 Amazon Web Services 账户中的 MySecret 的 password 值。您必须指定完整的密钥 ARN 才能访问其他 Amazon Web Services 账户中的密钥。

{{resolve:secretsmanager:arn:aws:secretsmanager:us-west-2:123456789012:secret:MySecret:SecretString:password}}