AWS Secrets Manager

AWS Secrets Manager helps protect access to applications, services, and IT resources. Store, retrieve, and automatically rotate credentials, API keys, and other secrets.

AWS Secrets Manager 有助于保护对应用程序、服务和IT资源的访问。可用于存储、检索并自动轮转凭据、API密钥和其他密钥。

Core Concepts

核心概念

Secrets

密钥

Encrypted data stored in Secrets Manager. Can contain:

Database credentials
API keys
OAuth tokens
Any key-value pairs (up to 64 KB)

存储在Secrets Manager中的加密数据，可包含：

数据库凭据
API密钥
OAuth令牌
任意键值对（最大64 KB）

Versions

版本

Each secret can have multiple versions:

AWSCURRENT: Current active version
AWSPENDING: Version being rotated to
AWSPREVIOUS: Previous version

每个密钥可拥有多个版本：

AWSCURRENT：当前活跃版本
AWSPENDING：待轮转的版本
AWSPREVIOUS：上一版本

Rotation

轮转

Automatic credential rotation using Lambda functions. Built-in support for:

Amazon RDS
Amazon Redshift
Amazon DocumentDB
Custom secrets

使用Lambda函数实现凭据自动轮转，内置支持：

Amazon RDS
Amazon Redshift
Amazon DocumentDB
自定义密钥

Common Patterns

常见模式

Create a Secret

创建密钥

AWS CLI:

bash

undefined

AWS CLI：

bash

undefined

Create secret with JSON

aws secretsmanager create-secret
--name prod/myapp/database
--description "Production database credentials"
--secret-string '{"username":"admin","password":"MySecurePassword123!","host":"mydb.cluster-xyz.us-east-1.rds.amazonaws.com","port":5432,"database":"myapp"}'

Create secret with binary data

aws secretsmanager create-secret
--name prod/myapp/certificate
--secret-binary fileb://certificate.pem


**boto3:**

```python
import boto3
import json

secrets = boto3.client('secretsmanager')

response = secrets.create_secret(
    Name='prod/myapp/database',
    Description='Production database credentials',
    SecretString=json.dumps({
        'username': 'admin',
        'password': 'MySecurePassword123!',
        'host': 'mydb.cluster-xyz.us-east-1.rds.amazonaws.com',
        'port': 5432,
        'database': 'myapp'
    }),
    Tags=[
        {'Key': 'Environment', 'Value': 'production'},
        {'Key': 'Application', 'Value': 'myapp'}
    ]
)

aws secretsmanager create-secret
--name prod/myapp/certificate
--secret-binary fileb://certificate.pem


**boto3：**

```python
import boto3
import json

secrets = boto3.client('secretsmanager')

response = secrets.create_secret(
    Name='prod/myapp/database',
    Description='Production database credentials',
    SecretString=json.dumps({
        'username': 'admin',
        'password': 'MySecurePassword123!',
        'host': 'mydb.cluster-xyz.us-east-1.rds.amazonaws.com',
        'port': 5432,
        'database': 'myapp'
    }),
    Tags=[
        {'Key': 'Environment', 'Value': 'production'},
        {'Key': 'Application', 'Value': 'myapp'}
    ]
)

Retrieve a Secret

检索密钥

python

import boto3
import json

secrets = boto3.client('secretsmanager')

def get_secret(secret_name):
    response = secrets.get_secret_value(SecretId=secret_name)

    if 'SecretString' in response:
        return json.loads(response['SecretString'])
    else:
        import base64
        return base64.b64decode(response['SecretBinary'])

python

import boto3
import json

secrets = boto3.client('secretsmanager')

def get_secret(secret_name):
    response = secrets.get_secret_value(SecretId=secret_name)

    if 'SecretString' in response:
        return json.loads(response['SecretString'])
    else:
        import base64
        return base64.b64decode(response['SecretBinary'])

Usage

credentials = get_secret('prod/myapp/database') db_password = credentials['password']

undefined

credentials = get_secret('prod/myapp/database') db_password = credentials['password']

undefined

Caching Secrets

缓存密钥

python

from aws_secretsmanager_caching import SecretCache, SecretCacheConfig

python

from aws_secretsmanager_caching import SecretCache, SecretCacheConfig

Configure cache

cache_config = SecretCacheConfig( max_cache_size=100, secret_refresh_interval=3600, secret_version_stage_refresh_interval=3600 )

cache = SecretCache(config=cache_config)

def get_cached_secret(secret_name): secret = cache.get_secret_string(secret_name) return json.loads(secret)

undefined

cache_config = SecretCacheConfig( max_cache_size=100, secret_refresh_interval=3600, secret_version_stage_refresh_interval=3600 )

cache = SecretCache(config=cache_config)

def get_cached_secret(secret_name): secret = cache.get_secret_string(secret_name) return json.loads(secret)

undefined

Update a Secret

更新密钥

bash

undefined

bash

undefined

Update secret value

aws secretsmanager update-secret
--secret-id prod/myapp/database
--secret-string '{"username":"admin","password":"NewPassword456!"}'

Put new version with staging labels

aws secretsmanager put-secret-value
--secret-id prod/myapp/database
--secret-string '{"username":"admin","password":"NewPassword456!"}'
--version-stages AWSCURRENT

undefined

aws secretsmanager put-secret-value
--secret-id prod/myapp/database
--secret-string '{"username":"admin","password":"NewPassword456!"}'
--version-stages AWSCURRENT

undefined

Enable Rotation for RDS

为RDS启用轮转

bash

aws secretsmanager rotate-secret \
  --secret-id prod/myapp/database \
  --rotation-lambda-arn arn:aws:lambda:us-east-1:123456789012:function:SecretsManagerRDSPostgreSQLRotation \
  --rotation-rules AutomaticallyAfterDays=30

bash

aws secretsmanager rotate-secret \
  --secret-id prod/myapp/database \
  --rotation-lambda-arn arn:aws:lambda:us-east-1:123456789012:function:SecretsManagerRDSPostgreSQLRotation \
  --rotation-rules AutomaticallyAfterDays=30

Create Secret with Rotation

创建带轮转的密钥

bash

undefined

bash

undefined

Use CloudFormation for RDS secret with rotation

aws cloudformation deploy
--template-file rds-secret.yaml
--stack-name rds-secret


```yaml

aws cloudformation deploy
--template-file rds-secret.yaml
--stack-name rds-secret


```yaml

rds-secret.yaml

AWSTemplateFormatVersion: '2010-09-09' Resources: DBSecret: Type: AWS::SecretsManager::Secret Properties: Name: prod/myapp/database GenerateSecretString: SecretStringTemplate: '{"username": "admin"}' GenerateStringKey: password PasswordLength: 32 ExcludeCharacters: '"@/'

DBSecretRotation: Type: AWS::SecretsManager::RotationSchedule Properties: SecretId: !Ref DBSecret RotationLambdaARN: !GetAtt RotationLambda.Arn RotationRules: AutomaticallyAfterDays: 30

undefined

AWSTemplateFormatVersion: '2010-09-09' Resources: DBSecret: Type: AWS::SecretsManager::Secret Properties: Name: prod/myapp/database GenerateSecretString: SecretStringTemplate: '{"username": "admin"}' GenerateStringKey: password PasswordLength: 32 ExcludeCharacters: '"@/'

DBSecretRotation: Type: AWS::SecretsManager::RotationSchedule Properties: SecretId: !Ref DBSecret RotationLambdaARN: !GetAtt RotationLambda.Arn RotationRules: AutomaticallyAfterDays: 30

undefined

Use in Lambda with Extension

在Lambda中结合扩展使用

python

import json
import urllib.request

def handler(event, context):
    # Use AWS Parameters and Secrets Lambda Extension
    secrets_port = 2773
    secret_name = 'prod/myapp/database'

    url = f'http://localhost:{secrets_port}/secretsmanager/get?secretId={secret_name}'
    headers = {'X-Aws-Parameters-Secrets-Token': os.environ['AWS_SESSION_TOKEN']}

    request = urllib.request.Request(url, headers=headers)
    response = urllib.request.urlopen(request)
    secret = json.loads(response.read())['SecretString']

    credentials = json.loads(secret)
    return credentials

python

import json
import urllib.request

def handler(event, context):
    # Use AWS Parameters and Secrets Lambda Extension
    secrets_port = 2773
    secret_name = 'prod/myapp/database'

    url = f'http://localhost:{secrets_port}/secretsmanager/get?secretId={secret_name}'
    headers = {'X-Aws-Parameters-Secrets-Token': os.environ['AWS_SESSION_TOKEN']}

    request = urllib.request.Request(url, headers=headers)
    response = urllib.request.urlopen(request)
    secret = json.loads(response.read())['SecretString']

    credentials = json.loads(secret)
    return credentials

CLI Reference

CLI参考

Secret Management

密钥管理

Command	Description
`aws secretsmanager create-secret`	Create secret
`aws secretsmanager describe-secret`	Get secret metadata
`aws secretsmanager get-secret-value`	Retrieve secret value
`aws secretsmanager update-secret`	Update secret
`aws secretsmanager delete-secret`	Delete secret
`aws secretsmanager restore-secret`	Restore deleted secret
`aws secretsmanager list-secrets`	List secrets

命令	描述
`aws secretsmanager create-secret`	创建密钥
`aws secretsmanager describe-secret`	获取密钥元数据
`aws secretsmanager get-secret-value`	检索密钥值
`aws secretsmanager update-secret`	更新密钥
`aws secretsmanager delete-secret`	删除密钥
`aws secretsmanager restore-secret`	恢复已删除密钥
`aws secretsmanager list-secrets`	列出密钥

Versions

版本

Command	Description
`aws secretsmanager put-secret-value`	Add new version
`aws secretsmanager list-secret-version-ids`	List versions
`aws secretsmanager update-secret-version-stage`	Move staging labels

命令	描述
`aws secretsmanager put-secret-value`	添加新版本
`aws secretsmanager list-secret-version-ids`	列出版本
`aws secretsmanager update-secret-version-stage`	移动阶段标签

Rotation

轮转

Command	Description
`aws secretsmanager rotate-secret`	Configure/trigger rotation
`aws secretsmanager cancel-rotate-secret`	Cancel rotation

命令	描述
`aws secretsmanager rotate-secret`	配置/触发轮转
`aws secretsmanager cancel-rotate-secret`	取消轮转

Best Practices

最佳实践

Secret Organization

密钥组织

Use hierarchical names:
```
environment/application/secret-type
```
Tag secrets for organization and cost allocation
Separate by environment (dev, staging, prod)

使用分层命名：
```
环境/应用程序/密钥类型
```
为密钥添加标签，便于组织和成本分配
按环境分离（开发、预发布、生产）

Security

安全

Use resource policies to control access
Enable encryption with customer-managed KMS keys
Rotate secrets regularly (30-90 days)
Audit access with CloudTrail
Use VPC endpoints for private access

使用资源策略控制访问
启用加密，使用客户管理的KMS密钥
定期轮转密钥（30-90天）
通过CloudTrail审计访问
使用VPC端点实现私有访问

Access Control

访问控制

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/*",
      "Condition": {
        "StringEquals": {
          "secretsmanager:ResourceTag/Environment": "production"
        }
      }
    }
  ]
}

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/*",
      "Condition": {
        "StringEquals": {
          "secretsmanager:ResourceTag/Environment": "production"
        }
      }
    }
  ]
}

Application Integration

应用集成

Cache secrets to reduce API calls
Handle rotation gracefully (retry with new credentials)
Use Lambda extension for faster access
Never log secrets

缓存密钥以减少API调用
优雅处理轮转（使用新凭据重试）
使用Lambda扩展加快访问速度
切勿记录密钥

Troubleshooting

故障排除

AccessDeniedException

Causes:

IAM policy missing
```
secretsmanager:GetSecretValue
```
Resource policy denying access
KMS key policy missing permissions

Debug:

bash

undefined

原因：

IAM策略缺少
```
secretsmanager:GetSecretValue
```
权限
资源策略拒绝访问
KMS密钥策略缺少权限

调试：

bash

undefined

Check secret resource policy

aws secretsmanager get-resource-policy --secret-id my-secret

Check IAM permissions

aws iam simulate-principal-policy
--policy-source-arn arn:aws:iam::123456789012:role/my-role
--action-names secretsmanager:GetSecretValue
--resource-arns arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret

undefined

aws iam simulate-principal-policy
--policy-source-arn arn:aws:iam::123456789012:role/my-role
--action-names secretsmanager:GetSecretValue
--resource-arns arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret

undefined

Rotation Failed

轮转失败

Debug:

bash

undefined

调试：

bash

undefined

Check rotation status

aws secretsmanager describe-secret --secret-id my-secret

Check Lambda logs

aws logs filter-log-events
--log-group-name /aws/lambda/SecretsManagerRotation
--filter-pattern "ERROR"


**Common causes:**
- Lambda timeout (increase to 30+ seconds)
- Network connectivity (VPC configuration)
- Database connection issues
- Wrong secret format

aws logs filter-log-events
--log-group-name /aws/lambda/SecretsManagerRotation
--filter-pattern "ERROR"


**常见原因：**
- Lambda超时（增加至30秒以上）
- 网络连接问题（VPC配置）
- 数据库连接问题
- 密钥格式错误

Secret Not Found

密钥未找到

bash

undefined

bash

undefined

List secrets to find correct name

aws secretsmanager list-secrets
--filters Key=name,Values=myapp

Check if deleted (within recovery window)

aws secretsmanager list-secrets
--include-planned-deletion

undefined

aws secretsmanager list-secrets
--include-planned-deletion

undefined

secrets-manager

Original

Translation

AWS Secrets Manager

AWS Secrets Manager

Table of Contents

目录

Core Concepts

核心概念

Secrets

密钥

Versions

版本

Rotation

轮转

Common Patterns

常见模式

Create a Secret

创建密钥

Create secret with JSON

Create secret with JSON

Create secret with binary data

Create secret with binary data

Retrieve a Secret

检索密钥

Usage

Usage

Caching Secrets

缓存密钥

Configure cache

Configure cache

Update a Secret

更新密钥

Update secret value

Update secret value

Put new version with staging labels

Put new version with staging labels

Enable Rotation for RDS

为RDS启用轮转

Create Secret with Rotation

创建带轮转的密钥

Use CloudFormation for RDS secret with rotation

Use CloudFormation for RDS secret with rotation

rds-secret.yaml

rds-secret.yaml

Use in Lambda with Extension

在Lambda中结合扩展使用

CLI Reference

CLI参考

Secret Management

密钥管理

Versions

版本

Rotation

轮转

Best Practices

最佳实践

Secret Organization

密钥组织

Security

安全

Access Control

访问控制

Application Integration

应用集成

Troubleshooting

故障排除

AccessDeniedException

AccessDeniedException

Check secret resource policy

Check secret resource policy

Check IAM permissions

Check IAM permissions

Rotation Failed

轮转失败

Check rotation status

Check rotation status

Check Lambda logs

Check Lambda logs

Secret Not Found