alibabacloud-kms-secret-manage

Alibaba Cloud KMS Secret 管理

此 Skill 提供 Alibaba Cloud Key Management Service（KMS）Secret 管理的核心功能，支持对 Secret 执行 CRUD 操作。

场景说明

KMS Secret 管理服务用于安全地存储、管理和访问敏感信息，例如：

• 数据库连接凭据
• API 密钥
• OAuth 令牌
• 证书私钥
• 其他需要安全存储的敏感数据

**架构：**Alibaba Cloud KMS Service + Secret 管理（Secrets Manager）

graph TB
    User[Application/User] --> KMS[KMS Secret Management]
    KMS --> Secret[Generic Secret]
    Secret --> V1[Version 1]
    Secret --> V2[Version 2]
    Secret --> VN[Version N]
    KMS --> Rotation[Rotation Secret]
    Rotation --> RDS[RDS Managed Secret]
    Rotation --> RAM[RAM Managed Secret]
    Rotation --> ECS[ECS Managed Secret]
    Rotation --> Redis[Redis Managed Secret]
    Rotation --> PolarDB[PolarDB Managed Secret]

---

环境设置

依赖项：Aliyun CLI。如果出现 command not found 错误，请参阅 references/cli-installation-guide.md 进行安装。

超时配置

为 CLI 命令设置适当的超时时间，避免命令挂起：

# Set timeout environment variables (in seconds)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30
export ALIBABA_CLOUD_READ_TIMEOUT=30

也可以使用命令行标志：

aliyun kms <action> --connect-timeout 30 --read-timeout 30 ...

推荐的超时值：

• 连接超时：30 秒
• 读取超时：30 秒

---

安全规则

• 禁止：读取、打印或显示 AK/SK 值
• 禁止：要求用户在对话中直接输入 AK/SK
• 敏感数据遮蔽：GetSecretValue 返回的 Secret 值默认会被遮蔽（例如 ***），仅在用户明确请求时以明文输出

---

RAM 权限要求

确保执行操作的用户具有以下 KMS 权限。详细策略请参阅 references/ram-policies.md。

最低权限（只读）：

kms:DescribeSecret, kms:ListSecrets, kms:GetSecretValue, kms:ListSecretVersionIds, kms:GetSecretPolicy

完整权限（读写）：

kms:CreateSecret, kms:DeleteSecret, kms:UpdateSecret, kms:DescribeSecret, 
kms:ListSecrets, kms:GetSecretValue, kms:PutSecretValue, kms:ListSecretVersionIds,
kms:UpdateSecretVersionStage, kms:UpdateSecretRotationPolicy, kms:RotateSecret,
kms:RestoreSecret, kms:SetSecretPolicy, kms:GetSecretPolicy,
kms:ListKmsInstances, kms:ListKeys, kms:CreateKey

---

核心工作流

1. 创建 Secret

创建 Secret 前，需要先获取 KMS 实例 ID 和加密密钥 ID，然后执行创建操作。

# Step 1: Get KMS Instance ID
aliyun kms ListKmsInstances --PageNumber 1 --PageSize 10 --region <region-id> --user-agent AlibabaCloud-Agent-Skills
# → Extract KmsInstances.KmsInstance[0].KmsInstanceId

# Step 2: Get Encryption Key ID
aliyun kms ListKeys --Filters '[{"Key":"KeySpec","Values":["Aliyun_AES_256"]},{"Key":"DKMSInstanceId","Values":["<instance-id>"]}]' --PageNumber 1 --PageSize 10 --region <region-id> --user-agent AlibabaCloud-Agent-Skills
# → Extract Keys.Key[0].KeyId

# Step 3: Create Secret (requires DKMSInstanceId and EncryptionKeyId)
aliyun kms CreateSecret --SecretName "<secret-name>" --SecretData "<secret-value>" --VersionId "<version-id>" --EncryptionKeyId "<key-id>" --DKMSInstanceId "<instance-id>" --region <region-id> --user-agent AlibabaCloud-Agent-Skills

---

2. 列出 Secret

aliyun kms ListSecrets --region <region-id> --user-agent AlibabaCloud-Agent-Skills

---

3. 获取 Secret 值

安全策略：

• 如果用户未明确请求 Secret 值：仅提供 CLI 命令或 Python 代码脚本。不要执行。
• 如果用户明确请求获取、检索或显示 Secret 值：先提供命令或脚本，再在用户确认后执行。

CLI 命令：

aliyun kms GetSecretValue --SecretName "<secret-name>" --region <region-id> --user-agent AlibabaCloud-Agent-Skills

Python SDK 示例：

from alibabacloud_tea_openapi.client import Client as OpenApiClient
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_tea_util import models as util_models

credential = CredentialClient()
config = open_api_models.Config(credential=credential)
config.endpoint = 'kms.<region-id>.aliyuncs.com'
client = OpenApiClient(config)

params = open_api_models.Params(
    action='GetSecretValue',
    version='2016-01-20',
    protocol='HTTPS',
    method='POST',
    auth_type='AK',
    style='RPC',
    pathname='/',
    req_body_type='json',
    body_type='json'
)

body = {'SecretName': '<secret-name>'}
runtime = util_models.RuntimeOptions()
request = open_api_models.OpenApiRequest(body=body)
response = client.call_api(params, request, runtime)
print(response.body)

注意：

• 仅在用户明确确认后执行检索操作
• Secret 值包含敏感信息，应谨慎处理
• 务必提醒用户在安全环境中执行（私密终端、不共享屏幕、不记录日志）

---

4. 删除 Secret

删除前检查（安全要求）：

强制删除 Secret 前，务必确认其存在，并检查它是否仍在使用：

# Step 1: Describe the secret to verify existence and check metadata
aliyun kms DescribeSecret --SecretName "<secret-name>" --region <region-id> --user-agent AlibabaCloud-Agent-Skills
# → Check SecretName, CreateTime, and other metadata to confirm this is the correct secret

如果 DescribeSecret 返回错误（未找到 Secret）：

• 停止操作并告知用户：“Secret 不存在，无需删除”

如果 DescribeSecret 成功：

• 检查 Secret 元数据
• 继续强制删除前，先与用户确认

# Step 2: Force delete (immediate deletion, cannot be recovered)
aliyun kms DeleteSecret --SecretName "<secret-name>" --ForceDeleteWithoutRecovery true --region <region-id> --user-agent AlibabaCloud-Agent-Skills

幂等性：如果返回 Forbidden.ResourceNotFound 错误，表示 Secret 不存在，应视为删除成功并继续后续操作。

---

5. 更新 Secret 值

aliyun kms PutSecretValue --SecretName "<secret-name>" --SecretData "<new-secret-value>" --VersionId "<new-version-id>" --region <region-id> --user-agent AlibabaCloud-Agent-Skills

---

6. 描述 Secret

aliyun kms DescribeSecret --SecretName "<secret-name>" --region <region-id> --user-agent AlibabaCloud-Agent-Skills

---

7. 列出 Secret 版本

aliyun kms ListSecretVersionIds --SecretName "<secret-name>" --IncludeDeprecated true --region <region-id> --user-agent AlibabaCloud-Agent-Skills

---

8. 配置轮换策略

aliyun kms UpdateSecretRotationPolicy --SecretName "<secret-name>" --EnableAutomaticRotation true --RotationInterval 7d --region <region-id> --user-agent AlibabaCloud-Agent-Skills

---

9. 恢复已删除的 Secret

aliyun kms RestoreSecret --SecretName "<secret-name>" --region <region-id> --user-agent AlibabaCloud-Agent-Skills

幂等性：如果返回 Rejected.ResourceInUse 错误，表示 Secret 已恢复或并未删除，应视为恢复成功并继续后续操作。

---

高级功能

有关托管凭据和其他高级功能，请参阅 references/managed-credentials.md。

---

Reference Links

Document	Description
references/related-apis.md	API detailed description
references/ram-policies.md	RAM permission policies
references/managed-credentials.md	Managed credentials guide