alibabacloud-kms-secret-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Alibaba Cloud KMS Secret Management

Alibaba Cloud KMS 凭据管理

This Skill provides core functionality for Alibaba Cloud Key Management Service (KMS) secret management, supporting CRUD operations on secrets.

本Skill提供Alibaba Cloud Key Management Service（KMS）凭据管理的核心功能，支持对凭据的增删改查（CRUD）操作。

Scenario Description

场景说明

KMS Secret Management service is used to securely store, manage, and access sensitive information, such as:

Database connection credentials
API keys
OAuth tokens
Certificate private keys
Other sensitive data requiring secure storage

Architecture: Alibaba Cloud KMS Service + Secret Management (Secrets Manager)

mermaid

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]

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

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

架构： Alibaba Cloud KMS 服务 + 凭据管理（Secrets Manager）

mermaid

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]

Environment Setup

环境搭建

Dependency: Aliyun CLI. If
command not found
error occurs, refer to references/cli-installation-guide.md for installation.

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

Timeout Configuration

超时配置

Set appropriate timeouts for CLI commands to avoid hanging:

bash

undefined

为CLI命令设置合理的超时时间避免执行挂起：

bash

undefined

Set timeout environment variables (in seconds)

export ALIBABA_CLOUD_CONNECT_TIMEOUT=30 export ALIBABA_CLOUD_READ_TIMEOUT=30


Or use command-line flags:
```bash
aliyun kms <action> --connect-timeout 30 --read-timeout 30 ...

Recommended timeout values:

Connection timeout: 30 seconds
Read timeout: 30 seconds

export ALIBABA_CLOUD_CONNECT_TIMEOUT=30 export ALIBABA_CLOUD_READ_TIMEOUT=30


或者使用命令行参数：
```bash
aliyun kms <action> --connect-timeout 30 --read-timeout 30 ...

推荐超时值：

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

Security Rules

安全规则

Prohibited: Reading, printing, or displaying AK/SK values

Prohibited: Requiring users to directly input AK/SK in conversation
Sensitive Data Masking: Secret values returned by GetSecretValue are masked by default (e.g.,
***
), only output in plaintext when user explicitly requests

禁止：读取、打印或展示AK/SK值

禁止：要求用户在对话中直接输入AK/SK
敏感数据脱敏：GetSecretValue接口返回的凭据值默认会脱敏（例如
***
），仅在用户明确要求时才输出明文

RAM Permission Requirements

RAM权限要求

Ensure the executing user has the following KMS permissions. For detailed policies, see references/ram-policies.md.

Minimum Permissions (Read-Only):

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

Full Permissions (Read-Write):

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

确保执行操作的用户拥有以下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

Core Workflows

核心工作流

1. Create Secret

1. 创建凭据

Creating a secret requires obtaining the KMS instance ID and encryption key ID first, then executing the creation.

bash

undefined

创建凭据需要先获取KMS实例ID和加密密钥ID，再执行创建操作。

bash

undefined

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. List Secrets

2. 列出凭据

bash

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

bash

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

3. Get Secret Value

3. 获取凭据值

Security Policy:

If user does NOT explicitly request the secret value: Only provide the CLI command or Python code script. DO NOT execute.

If user explicitly requests to get/retrieve/show the secret value: Provide the command/script first, then execute after user confirms.

CLI Command:

bash

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

Python SDK Example:

python

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)

Note:

Only execute the retrieval after user explicitly confirms

The secret value contains sensitive information that should be handled with care

Always remind user to execute in a secure environment (private terminal, no screen sharing, no logging)

安全策略:

如果用户未明确要求获取凭据值：仅提供CLI命令或Python代码脚本，请勿执行。

如果用户明确要求获取/检索/展示凭据值：先提供命令/脚本，待用户确认后再执行。

CLI命令：

bash

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

Python SDK示例：

python

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)

注意:

仅在用户明确确认后再执行获取操作

凭据值包含敏感信息，请谨慎处理

始终提醒用户在安全环境中执行（私有终端、无屏幕共享、无日志记录）

4. Delete Secret

4. 删除凭据

Pre-check before deletion (Safety Requirement):

Before force deleting a secret, always verify its existence and check if it's still in use:

bash

undefined

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

在强制删除凭据前，请始终验证其存在性并检查是否仍在使用：

bash

undefined

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


**If DescribeSecret returns error (secret not found):**
- Stop and inform user: "Secret does not exist, no deletion needed"

**If DescribeSecret succeeds:**
- Review the secret metadata
- Confirm with user before proceeding with force deletion

```bash


**如果DescribeSecret返回错误（凭据不存在）：**
- 停止操作并告知用户："凭据不存在，无需删除"

**如果DescribeSecret执行成功：**
- 检查凭据元数据
- 继续强制删除前请先与用户确认

```bash

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


> **Idempotency**: If `Forbidden.ResourceNotFound` error is returned, it means the secret does not exist, treat as deletion successful and continue with subsequent operations.

---

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


> **幂等性**: 如果返回`Forbidden.ResourceNotFound`错误，说明凭据不存在，视为删除成功，可继续后续操作。

---

5. Update Secret Value

5. 更新凭据值

bash

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

bash

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

6. Describe Secret

6. 查询凭据详情

bash

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

bash

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

7. List Secret Versions

7. 列出凭据版本

bash

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

bash

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

8. Configure Rotation Policy

8. 配置轮换策略

bash

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

bash

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

9. Restore Deleted Secret

9. 恢复已删除凭据

bash

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

Idempotency: If
Rejected.ResourceInUse
error is returned, it means the secret has been restored or was not deleted, treat as restore successful and continue with subsequent operations.

bash

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

幂等性: 如果返回
Rejected.ResourceInUse
错误，说明凭据已恢复或未被删除，视为恢复成功，可继续后续操作。

Advanced Features

高级功能

For managed credentials and other advanced features, see references/managed-credentials.md.

如需了解托管凭证等高级功能，请参考 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

文档	描述
references/related-apis.md	API详细说明
references/ram-policies.md	RAM权限策略
references/managed-credentials.md	托管凭证指南