Alibabacloud Kms Secret Manage

Alibaba Cloud KMS Secret Management

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

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)

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.

Timeout Configuration

Set appropriate timeouts for CLI commands to avoid hanging:

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

Or use command-line flags:

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

Recommended timeout values:

• Connection timeout: 30 seconds
• Read timeout: 30 seconds

---

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

---

RAM Permission Requirements

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

---

Core Workflows

1. Create Secret

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

# 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

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

---

3. Get Secret Value

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:

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

Python SDK Example:

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)

---

4. Delete Secret

Pre-check before deletion (Safety Requirement):

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

# 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

# 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.

---

5. Update Secret Value

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

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

---

7. List Secret Versions

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

---

8. Configure Rotation Policy

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

---

9. Restore Deleted Secret

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.

---

Advanced Features

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

---

Reference Links

Acceptance Criteria: KMS Secret Management Skill

Scenario: Alibaba Cloud KMS Secret Management Purpose: Skill testing acceptance criteria

---

Correct CLI Command Patterns

1. Product Name - Verify product name exists (kms not other spellings)

✅ Correct

aliyun kms CreateSecret ...

❌ Incorrect

aliyun Kms CreateSecret ...    # Wrong case
aliyun key-management ...      # Wrong product name

2. API Action Name - Verify action exists under this product

✅ Correct

aliyun kms CreateSecret
aliyun kms DeleteSecret
aliyun kms GetSecretValue
aliyun kms ListSecrets

❌ Incorrect

aliyun kms create-secret        # Should be PascalCase
aliyun kms CreateCredential     # Wrong action name

3. Parameter Names - Verify parameters exist for this command

CreateSecret Parameters

✅ Correct

aliyun kms CreateSecret \
  --SecretName "my-secret" \
  --SecretData "secret-value" \
  --VersionId "v1" \
  --Description "description" \
  --SecretType "Generic" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

❌ Incorrect

aliyun kms CreateSecret \
  --secret-name "my-secret"    # Should be --SecretName
  --secret-data "value"        # Should be --SecretData

GetSecretValue Parameters

✅ Correct

aliyun kms GetSecretValue \
  --SecretName "my-secret" \
  --VersionId "v1" \
  --VersionStage "ACSCurrent" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

DeleteSecret Parameters

✅ Correct

aliyun kms DeleteSecret \
  --SecretName "my-secret" \
  --ForceDeleteWithoutRecovery "true" \
  --RecoveryWindowInDays "7" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

4. Enum Values - Verify parameter values are within allowed range

SecretType Enum Values

✅ Correct

--SecretType "Generic"
--SecretType "Rds"
--SecretType "RAMCredentials"
--SecretType "ECS"

❌ Incorrect

--SecretType "generic"         # Wrong case
--SecretType "Database"        # Invalid enum value

VersionStage Enum Values

✅ Correct

--VersionStage "ACSCurrent"
--VersionStage "ACSPrevious"

SecretDataType Enum Values

✅ Correct

--SecretDataType "text"
--SecretDataType "binary"

5. Parameter Value Formats

Filters Parameter (JSON array format)

✅ Correct

--Filters '[{"Key":"SecretName","Values":["test-*"]}]'

❌ Incorrect

--Filters '{"Key":"SecretName","Values":["test-*"]}'  # Should be array
--Filters "SecretName=test-*"                          # Wrong format

ExtendedConfig Parameter (JSON object format)

✅ Correct

--ExtendedConfig '{"SecretSubType":"SingleUser","DBInstanceId":"rm-xxxxxxxx"}'

RotationInterval Parameter (time format)

✅ Correct

--RotationInterval "7d"      # 7 days
--RotationInterval "168h"    # 168 hours
--RotationInterval "604800s" # 604800 seconds

❌ Incorrect

--RotationInterval "7 days"  # Wrong format
--RotationInterval "1w"      # Week not supported

6. Required user-agent flag

✅ Correct - Every command must include user-agent

aliyun kms CreateSecret \
  --SecretName "test" \
  --SecretData "value" \
  --VersionId "v1" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

❌ Incorrect - Missing user-agent

aliyun kms CreateSecret \
  --SecretName "test" \
  --SecretData "value" \
  --VersionId "v1" \
  --region cn-hangzhou

---

Correct Common SDK Code Patterns (if applicable)

1. Import Paths

✅ Correct

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

❌ Incorrect

from aliyunsdkkms.client import Client       # Old SDK
from alibabacloud_kms import Client          # Wrong package name

2. Authentication - Must use CredentialClient, never hardcode AK/SK

✅ Correct

from alibabacloud_credentials.client import Client as CredentialClient
from alibabacloud_tea_openapi import models as open_api_models

credential = CredentialClient()
config = open_api_models.Config(credential=credential)
config.endpoint = 'kms.cn-hangzhou.aliyuncs.com'

❌ Incorrect

config = open_api_models.Config(
    access_key_id='LTAI5txxxxxxxx',        # Hardcoded AK
    access_key_secret='xxxxxxxxxx'          # Hardcoded SK
)

3. Client Initialization

✅ Correct

from alibabacloud_tea_openapi.client import Client as OpenApiClient

client = OpenApiClient(config)

4. API Call

✅ Correct

from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_tea_util import models as util_models

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

body = {
    'SecretName': 'my-secret',
    'SecretData': 'secret-value',
    'VersionId': 'v1'
}

runtime = util_models.RuntimeOptions()
request = open_api_models.OpenApiRequest(body=body)

response = client.call_api(params, request, runtime)

---

Common Anti-patterns

1. Do not print secret values in output

❌ Incorrect

echo "Secret value: $(aliyun kms GetSecretValue --SecretName test | jq -r '.SecretData')"

2. Do not expose secrets in command history

✅ Correct - Read from file

aliyun kms CreateSecret \
  --SecretName "my-secret" \
  --SecretData "$(cat secret.txt)" \
  --VersionId "v1" \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

3. Do not assume default parameters

❌ Incorrect - Missing required parameters

aliyun kms CreateSecret \
  --SecretName "my-secret" \
  --SecretData "value"
  # Missing --VersionId and --region

---

Test Scenario Checklist

• [ ] CreateSecret can create generic secrets
• [ ] DeleteSecret soft delete with recovery window
• [ ] DeleteSecret force delete without recovery
• [ ] GetSecretValue get current version
• [ ] GetSecretValue get specified version
• [ ] GetSecretValue get ACSPrevious version
• [ ] ListSecrets list all secrets
• [ ] ListSecrets use Filters for filtering
• [ ] PutSecretValue store new version
• [ ] UpdateSecret update description
• [ ] UpdateSecretVersionStage switch version stage
• [ ] UpdateSecretRotationPolicy enable/disable auto rotation
• [ ] RotateSecret manual rotation
• [ ] RestoreSecret restore deleted secret
• [ ] SetSecretPolicy/GetSecretPolicy only work for secrets in KMS instances

---

API Version and Endpoint

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.1+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.1 or later for full plugin ecosystem coverage.

Installation

macOS

Using Homebrew (Recommended)

brew install aliyun-cli
# Upgrade to latest
brew upgrade aliyun-cli

# Verify version (>= 3.3.1)
aliyun version

Using Binary

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-macosx-latest-amd64.tgz

# Extract
tar -xzf aliyun-cli-macosx-latest-amd64.tgz

# Move to PATH
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

Linux

Debian/Ubuntu

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

CentOS/RHEL

# Download
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-amd64.tgz
sudo mv aliyun /usr/local/bin/

# Verify
aliyun version

ARM64 Architecture

# Download ARM64 version
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-arm64.tgz

# Extract and install
tar -xzf aliyun-cli-linux-latest-arm64.tgz
sudo mv aliyun /usr/local/bin/

Windows

Using Binary 1. Download from: https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip 2. Extract the ZIP file 3. Add the directory to your PATH environment variable 4. Open new Command Prompt or PowerShell 5. Verify: aliyun version

Using PowerShell

# Download
Invoke-WebRequest -Uri "https://aliyuncli.alicdn.com/aliyun-cli-windows-latest-amd64.zip" -OutFile "aliyun-cli.zip"

# Extract
Expand-Archive -Path aliyun-cli.zip -DestinationPath C:\aliyun-cli

# Add to PATH (requires admin privileges)
$env:Path += ";C:\aliyun-cli"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [System.EnvironmentVariableTarget]::Machine)

# Verify
aliyun version

Configuration

Quick Start

aliyun configure set \
  --mode AK \
  --access-key-id <your-access-key-id> \
  --access-key-secret <your-access-key-secret> \
  --region cn-hangzhou

All aliyun configure commands support non-interactive flags, which is the recommended approach — it works in scripts, CI/CD pipelines, and agent-driven automation without hanging on stdin prompts.

Where to Get Access Keys

1. Log in to Aliyun Console: https://ram.console.aliyun.com/ 2. Navigate to: AccessKey Management 3. Create a new AccessKey pair 4. Save the secret immediately — it's only shown once

Configuration Modes

Aliyun CLI supports 6 authentication modes. All examples below use non-interactive flags.

1. AK Mode (Access Key)

Most common mode for personal accounts and scripts.

aliyun configure set \
  --mode AK \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Configuration is stored in ~/.aliyun/config.json:

{
  "current": "default",
  "profiles": [
    {
      "name": "default",
      "mode": "AK",
      "access_key_id": "LTAI5tXXXXXXXX",
      "access_key_secret": "8dXXXXXXXXXXXXXXXXXXXXXXXX",
      "region_id": "cn-hangzhou",
      "output_format": "json",
      "language": "en"
    }
  ]
}

2. StsToken Mode (Temporary Credentials)

For short-lived access (tokens expire in 1-12 hours).

aliyun configure set \
  --mode StsToken \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --sts-token v1.0:XXXXXXXXXXXXXXXX \
  --region cn-hangzhou

Use cases: CI/CD pipelines, temporary access for external contractors, cross-account access.

3. RamRoleArn Mode (Assume RAM Role)

Assume a RAM role for elevated or cross-account access.

aliyun configure set \
  --mode RamRoleArn \
  --access-key-id LTAI5tXXXXXXXX \
  --access-key-secret 8dXXXXXXXXXXXXXXXXXXXXXXXX \
  --ram-role-arn acs:ram::123456789012:role/AdminRole \
  --role-session-name my-session \
  --region cn-hangzhou

Use cases: cross-account resource access, temporary elevated privileges, role-based access control.

4. EcsRamRole Mode (ECS Instance RAM Role)

Use the RAM role attached to an ECS instance — no credentials needed.

aliyun configure set \
  --mode EcsRamRole \
  --ram-role-name MyEcsRole \
  --region cn-hangzhou

Requirements: must be running on an ECS instance with a RAM role attached.

Use cases: scripts and automation running on ECS instances.

5. RsaKeyPair Mode (RSA Key Pair)

Use RSA key pair for authentication (generate key pair in Aliyun Console first).

aliyun configure set \
  --mode RsaKeyPair \
  --private-key /path/to/private-key.pem \
  --key-pair-name my-key-pair \
  --region cn-hangzhou

6. RamRoleArnWithEcs Mode (ECS + RAM Role)

Combine ECS instance role with RAM role assumption for cross-account access from ECS.

aliyun configure set \
  --mode RamRoleArnWithEcs \
  --ram-role-name MyEcsRole \
  --ram-role-arn acs:ram::123456789012:role/TargetRole \
  --role-session-name my-session \
  --region cn-hangzhou

Environment Variables

Highest priority - overrides config file

Access Key Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

STS Token Mode

export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
export ALIBABA_CLOUD_SECURITY_TOKEN=your_sts_token
export ALIBABA_CLOUD_REGION_ID=cn-hangzhou

ECS RAM Role Mode

export ALIBABA_CLOUD_ECS_METADATA=role_name

Use Case:

• CI/CD pipelines
• Docker containers
• Temporary credential override

Managing Multiple Profiles

Create Named Profiles

aliyun configure set --profile projectA \
  --mode AK \
  --access-key-id LTAI5tAAAAAAAA \
  --access-key-secret 8dAAAAAAAAAAAAAAAAAAAAAAAA \
  --region cn-hangzhou

aliyun configure set --profile projectB \
  --mode AK \
  --access-key-id LTAI5tBBBBBBBB \
  --access-key-secret 8dBBBBBBBBBBBBBBBBBBBBBBBB \
  --region cn-shanghai

Use Specific Profile

aliyun ecs describe-instances --profile projectA

export ALIBABA_CLOUD_PROFILE=projectA
aliyun ecs describe-instances   # Uses projectA

List and Switch Profiles

aliyun configure list                      # List all profiles
aliyun configure set --current projectA    # Switch default profile

Credential Priority

Credentials are loaded in this order (first found wins):

1. Command-line flag: --profile <name> 2. Environment variable: ALIBABA_CLOUD_PROFILE 3. Environment credentials: ALIBABA_CLOUD_ACCESS_KEY_ID, etc. 4. Configuration file: ~/.aliyun/config.json (current profile) 5. ECS Instance RAM Role: If running on ECS with attached role

Verification

Test Authentication

# Basic test - list regions
aliyun ecs describe-regions

# Expected output: JSON array of regions

If successful, you'll see:

{
  "Regions": {
    "Region": [
      {
        "RegionId": "cn-hangzhou",
        "RegionEndpoint": "ecs.cn-hangzhou.aliyuncs.com",
        "LocalName": "华东 1（杭州）"
      },
      ...
    ]
  },
  "RequestId": "..."
}

If failed, you'll see error messages:

• InvalidAccessKeyId.NotFound - Wrong Access Key ID
• SignatureDoesNotMatch - Wrong Access Key Secret
• InvalidSecurityToken.Expired - STS token expired (for StsToken mode)
• Forbidden.RAM - Insufficient permissions

Debug Configuration

# Show current configuration
aliyun configure get

# Test with debug logging
aliyun ecs describe-regions --log-level=debug

# Check credential provider
aliyun configure get mode

Security Best Practices

1. Use RAM Users (Not Root Account)

❌ Don't: Use Aliyun root account credentials ✅ Do: Create RAM users with specific permissions

# Create RAM user in console
# Attach only necessary policies
# Use RAM user's access keys

2. Principle of Least Privilege

Grant only the minimum permissions needed:

# Example: Read-only ECS access
# Attach policy: AliyunECSReadOnlyAccess

3. Rotate Access Keys Regularly

# Create new access key in RAM Console, then update configuration
aliyun configure set --access-key-id NEW_KEY --access-key-secret NEW_SECRET
# Delete old access key from console

4. Use STS Tokens for Temporary Access

aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token XXXX --region cn-hangzhou

5. Use ECS RAM Roles When Possible

aliyun configure set --mode EcsRamRole --ram-role-name MyRole --region cn-hangzhou

6. Never Commit Credentials

# Add to .gitignore
echo "~/.aliyun/config.json" >> .gitignore

# Use environment variables in CI/CD instead

7. Secure Config File

# Restrict permissions
chmod 600 ~/.aliyun/config.json

Troubleshooting

Issue: Command Not Found

# Check installation
which aliyun

# Check PATH
echo $PATH

# Reinstall or add to PATH

Issue: Authentication Failed

# Verify configuration
aliyun configure get

# Test with debug
aliyun ecs describe-regions --log-level=debug

# Check credentials in console
# Verify access key is active

Issue: Permission Denied

# Error: Forbidden.RAM

# Check RAM user permissions
# Attach necessary policies in RAM console
# Example: AliyunECSFullAccess for ECS operations

Issue: STS Token Expired

# Error: InvalidSecurityToken.Expired

# Reconfigure with new token
aliyun configure set --mode StsToken \
  --access-key-id XXXX --access-key-secret XXXX \
  --sts-token NEW_TOKEN --region cn-hangzhou

Issue: Wrong Region

# Some resources may not exist in the specified region

# Check available regions
aliyun ecs describe-regions

# Update default region
aliyun configure set region cn-shanghai

Advanced Configuration

Custom Endpoint

# Use custom or private endpoint
export ALIBABA_CLOUD_ECS_ENDPOINT=ecs-vpc.cn-hangzhou.aliyuncs.com

Proxy Settings

# HTTP proxy
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# No proxy for specific domains
export NO_PROXY=localhost,127.0.0.1,.aliyuncs.com

Timeout Settings

# Connection timeout (default: 10s)
export ALIBABA_CLOUD_CONNECT_TIMEOUT=30

# Read timeout (default: 10s)
export ALIBABA_CLOUD_READ_TIMEOUT=30

Next Steps

After installation and configuration:

1. Install plugins for services you need (v3.3.1+ supports all published product plugins):

   aliyun plugin install --names ecs vpc rds

   # List all available plugins
   aliyun plugin list-remote

2. Explore commands:

   aliyun ecs --help
   aliyun fc --help

3. Read documentation:

• Command Syntax Guide
• Global Flags Reference
• Common Scenarios

References

• Official Documentation: https://help.aliyun.com/zh/cli/
• RAM Console: https://ram.console.aliyun.com/
• Access Key Management: https://ram.console.aliyun.com/manage/ak
• Plugin Repository: https://github.com/aliyun/aliyun-cli

Managed Credentials Guide

This document details the creation and management of KMS managed credentials.

Managed Credentials Overview

Managed credentials can automatically manage cloud product credential rotation, supporting the following types:

---

RDS Managed Credentials

Create RDS Managed Credential

aliyun kms CreateSecret \
  --SecretName "<secret-name>" \
  --SecretType Rds \
  --SecretData '{"Accounts":[{"AccountName":"<db-username>","AccountPassword":"<password>"}]}' \
  --VersionId "v1" \
  --ExtendedConfig '{"SecretSubType":"SingleUser","DBInstanceId":"<RDS-instance-ID>"}' \
  --EnableAutomaticRotation true \
  --RotationInterval 7d \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

SecretData Format

{
  "Accounts": [
    {
      "AccountName": "dbuser",
      "AccountPassword": "<database-password>"
    }
  ]
}

ExtendedConfig Format

{
  "SecretSubType": "SingleUser",
  "DBInstanceId": "rm-xxxxxxxx",
  "CustomData": {}
}

Rotation Mode Description

• SingleUser: Single account mode, directly modifies account password during rotation
• DualUser: Dual account mode, switches between two accounts during rotation, no business interruption

---

RAM Managed Credentials

Create RAM Managed Credential

aliyun kms CreateSecret \
  --SecretName "<secret-name>" \
  --SecretType RAMCredentials \
  --SecretData '{"AccessKeys":[{"AccessKeyId":"<AK>","AccessKeySecret":"<SK>"}]}' \
  --VersionId "v1" \
  --ExtendedConfig '{"SecretSubType":"RamUserAccessKey","UserName":"<RAM-username>"}' \
  --EnableAutomaticRotation true \
  --RotationInterval 30d \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

SecretData Format

{
  "AccessKeys": [
    {
      "AccessKeyId": "<AccessKeyId>",
      "AccessKeySecret": "<AccessKeySecret>"
    }
  ]
}

ExtendedConfig Format

{
  "SecretSubType": "RamUserAccessKey",
  "UserName": "ram-user-name",
  "CustomData": {}
}

---

ECS Managed Credentials

Create ECS Managed Credential (Password Mode)

aliyun kms CreateSecret \
  --SecretName "<secret-name>" \
  --SecretType ECS \
  --SecretData '{"UserName":"root","Password":"<password>"}' \
  --VersionId "v1" \
  --ExtendedConfig '{"SecretSubType":"Password","RegionId":"<region-id>","InstanceId":"<ECS-instance-ID>"}' \
  --EnableAutomaticRotation true \
  --RotationInterval 30d \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Password Mode SecretData Format

{
  "UserName": "root",
  "Password": "<login-password>"
}

SSH Key Mode SecretData Format

{
  "UserName": "root",
  "PublicKey": "<SSH-public-key>",
  "PrivateKey": "<SSH-private-key>"
}

ExtendedConfig Format

{
  "SecretSubType": "Password",
  "RegionId": "cn-hangzhou",
  "InstanceId": "i-xxxxxxxx",
  "CustomData": {}
}

---

Secret Policy (KMS Instance Only)

Limitation: SetSecretPolicy and GetSecretPolicy APIs only apply to secrets in KMS instances, not supported in shared KMS.

Set Secret Policy

aliyun kms SetSecretPolicy \
  --SecretName "<secret-name>" \
  --Policy '<policy-JSON>' \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Policy Format Example

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "RAM": ["acs:ram::*:user/app-user"]
      },
      "Action": ["kms:GetSecretValue"],
      "Resource": ["*"]
    }
  ]
}

Query Secret Policy

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

---

Additional RAM Permissions Required for Managed Credentials

When using managed credentials, in addition to KMS permissions, you need to grant permissions for the corresponding cloud products.

RDS Managed Credential Permissions

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "rds:ResetAccountPassword",
        "rds:DescribeAccounts",
        "rds:DescribeDBInstanceAttribute"
      ],
      "Resource": "*"
    }
  ]
}

RAM Managed Credential Permissions

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ram:CreateAccessKey",
        "ram:DeleteAccessKey",
        "ram:ListAccessKeys",
        "ram:GetUser"
      ],
      "Resource": "*"
    }
  ]
}

ECS Managed Credential Permissions

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:ModifyInstanceAttribute",
        "ecs:DescribeInstances"
      ],
      "Resource": "*"
    }
  ]
}

---

Rotation Policy Configuration

Enable Automatic Rotation

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

Rotation Interval Description

Valid Range: 6 hours ~ 365 days

Disable Automatic Rotation

aliyun kms UpdateSecretRotationPolicy \
  --SecretName "<secret-name>" \
  --EnableAutomaticRotation false \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Manual Rotation

aliyun kms RotateSecret \
  --SecretName "<secret-name>" \
  --VersionId "<new-version-id>" \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

---

Best Practices

1. Choose appropriate rotation period: 7-30 days recommended for production 2. Use dual account mode (RDS): Avoid business interruption during rotation 3. Monitor rotation events: Monitor rotation results via ActionTrail 4. Test rotation process: Verify in test environment before applying to production 5. Configure alerts: Set up CloudMonitor alerts for rotation failure events

KMS Secret Management RAM Permission Policies

This document lists the RAM permissions required for using KMS secret management features.

Permission Overview

Secret Management Permission List

---

Recommended Permission Policies

1. Full Secret Management Permissions (Read-Write)

For users or applications requiring full secret management capabilities.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "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"
      ],
      "Resource": "*"
    }
  ]
}

2. Read-Only Secret Management Permissions

For users or applications only needing to query secret information.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:DescribeSecret",
        "kms:ListSecrets",
        "kms:GetSecretValue",
        "kms:ListSecretVersionIds",
        "kms:GetSecretPolicy",
        "kms:ListKmsInstances",
        "kms:ListKeys"
      ],
      "Resource": "*"
    }
  ]
}

3. Secret Create and Update Permissions (No Delete)

For users needing to create and update secrets but not delete them.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:CreateSecret",
        "kms:UpdateSecret",
        "kms:DescribeSecret",
        "kms:ListSecrets",
        "kms:GetSecretValue",
        "kms:PutSecretValue",
        "kms:ListSecretVersionIds",
        "kms:UpdateSecretVersionStage",
        "kms:UpdateSecretRotationPolicy",
        "kms:RotateSecret"
      ],
      "Resource": "*"
    }
  ]
}

4. Specified Secret Access Permissions

Restrict access to secrets with specific name prefixes.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:DescribeSecret",
        "kms:GetSecretValue",
        "kms:ListSecretVersionIds"
      ],
      "Resource": "acs:kms:*:*:secret/prod-*"
    },
    {
      "Effect": "Allow",
      "Action": "kms:ListSecrets",
      "Resource": "*"
    }
  ]
}

5. Application Minimum Permissions (GetSecretValue Only)

For application runtime scenarios retrieving secrets.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:GetSecretValue"
      ],
      "Resource": "acs:kms:*:*:secret/${SecretName}"
    }
  ]
}

---

Additional Permissions for Managed Credentials

RDS Managed Credentials

When using RDS managed credentials, additional RDS permissions are required:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "rds:ResetAccountPassword",
        "rds:DescribeAccounts",
        "rds:DescribeDBInstanceAttribute"
      ],
      "Resource": "*"
    }
  ]
}

RAM Managed Credentials

When using RAM managed credentials, additional RAM permissions are required:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ram:CreateAccessKey",
        "ram:DeleteAccessKey",
        "ram:ListAccessKeys",
        "ram:GetUser"
      ],
      "Resource": "*"
    }
  ]
}

ECS Managed Credentials

When using ECS managed credentials, additional ECS permissions are required:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ecs:ModifyInstanceAttribute",
        "ecs:DescribeInstances"
      ],
      "Resource": "*"
    }
  ]
}

---

System Policies

Alibaba Cloud provides the following system policies related to KMS:

Using System Policies

# Grant full KMS permissions to RAM user
aliyun ram AttachPolicyToUser \
  --PolicyType System \
  --PolicyName AliyunKMSFullAccess \
  --UserName <username>

---

Best Practices

1. Principle of Least Privilege: Only grant necessary permissions, avoid using * wildcards 2. Resource Restrictions: Limit accessible secret scope through resource ARN 3. Separate Read-Write Permissions: Applications typically only need GetSecretValue permission 4. Audit Logging: Enable ActionTrail to record secret access logs 5. Regular Review: Periodically review and clean up unnecessary permissions

---

Reference Links

• KMS Authorize RAM Users
• RAM Permission Policy Syntax
• KMS API Reference

KMS Secret Management Related API List

This document lists all APIs related to Alibaba Cloud KMS secret management and their CLI commands.

Secret Management API Overview

Auxiliary Query API Overview

---

Detailed API Parameter Description

1. CreateSecret - Create Secret

Create a secret and store its initial version.

CLI Command Format:

aliyun kms CreateSecret \
  --SecretName <secret-name> \
  --SecretData <secret-value> \
  --VersionId <version-id> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Required Parameters:

Optional Parameters:

---

2. DeleteSecret - Delete Secret

Delete secret object, supports setting recovery window or force deletion.

CLI Command Format:

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

Required Parameters:

Optional Parameters:

---

3. UpdateSecret - Update Secret Metadata

Update secret description or extended configuration.

CLI Command Format:

aliyun kms UpdateSecret \
  --SecretName <secret-name> \
  --Description <new-description> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Required Parameters:

Optional Parameters:

---

4. DescribeSecret - Query Secret Metadata

Query secret metadata information.

CLI Command Format:

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

Required Parameters:

Optional Parameters:

---

5. ListSecrets - Query Secret List

Query all secrets created by current user in current region, supports pagination and filtering.

CLI Command Format:

aliyun kms ListSecrets \
  --PageNumber <page-number> \
  --PageSize <page-size> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Pagination Parameters:

Filters Parameter Details:

Filters is a JSON array composed of Key-Values pairs, supporting the following Key values:

Note: Multiple Values within the same Key are OR relationship.

Example: [{"Key":"SecretName","Values":["sec1","sec2"]}] means SecretName=sec1 OR SecretName=sec2

Pagination Information in Response:

Example 1 - Basic Pagination Query:

# Query page 1, 20 items per page
aliyun kms ListSecrets \
  --PageNumber 1 \
  --PageSize 20 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

Example 2 - Pagination Query with Tags:

aliyun kms ListSecrets \
  --PageNumber 1 \
  --PageSize 20 \
  --FetchTags true \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

Example 3 - Filter by Secret Type:

aliyun kms ListSecrets \
  --Filters '[{"Key":"SecretType","Values":["Rds","ECS"]}]' \
  --PageNumber 1 \
  --PageSize 50 \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

Example 4 - Filter by KMS Instance:

aliyun kms ListSecrets \
  --Filters '[{"Key":"DKMSInstanceId","Values":["kst-hzz65f176a0ogplgqobxt"]}]' \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

Example 5 - Filter by Secret Name:

aliyun kms ListSecrets \
  --Filters '[{"Key":"SecretName","Values":["prod-db","prod-api"]}]' \
  --region cn-hangzhou \
  --user-agent AlibabaCloud-Agent-Skills

Response Example:

{
  "PageNumber": 1,
  "PageSize": 20,
  "RequestId": "6a6287a0-ff34-4780-a790-fdfca900557f",
  "TotalCount": 55,
  "SecretList": {
    "Secret": [
      {
        "SecretName": "secret001",
        "SecretType": "Generic",
        "CreateTime": "2024-07-17T07:59:05Z",
        "UpdateTime": "2024-07-17T07:59:05Z"
      }
    ]
  }
}

Tip: If filtering resources by tags exceeds 4000, please use the ListResourceTags interface for querying.

---

6. GetSecretValue - Get Secret Value

Get the actual value of a secret.

CLI Command Format:

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

Required Parameters:

Optional Parameters:

---

7. PutSecretValue - Store New Version Secret Value

Store a new version of secret value for a secret.

CLI Command Format:

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

Required Parameters:

Optional Parameters:

---

8. ListSecretVersionIds - Query Secret Version List

Query all version information of a secret.

CLI Command Format:

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

Required Parameters:

Optional Parameters:

---

9. UpdateSecretVersionStage - Update Version Stage

Update secret version stage label.

CLI Command Format:

aliyun kms UpdateSecretVersionStage \
  --SecretName <secret-name> \
  --VersionStage <stage-label> \
  --MoveToVersion <target-version-id> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Required Parameters:

Optional Parameters (at least one required):

---

10. UpdateSecretRotationPolicy - Update Rotation Policy

Update secret rotation policy.

CLI Command Format:

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

Required Parameters:

Optional Parameters:

---

11. RotateSecret - Manual Secret Rotation

Immediately execute secret rotation.

CLI Command Format:

aliyun kms RotateSecret \
  --SecretName <secret-name> \
  --VersionId <new-version-id> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Required Parameters:

---

12. RestoreSecret - Restore Deleted Secret

Restore a secret in deletion waiting period.

CLI Command Format:

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

Required Parameters:

---

13. SetSecretPolicy - Set Secret Policy

Set secret policy for secrets in KMS instances.

CLI Command Format:

aliyun kms SetSecretPolicy \
  --SecretName <secret-name> \
  --Policy '<policy-JSON>' \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Required Parameters:

Optional Parameters:

Note: SetSecretPolicy and GetSecretPolicy only apply to secrets in KMS instances, not supported in shared KMS.

---

15. GetSecretPolicy - Query Secret Policy

Query the secret policy of a specified secret.

CLI Command Format:

aliyun kms GetSecretPolicy \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Required Parameters:

Optional Parameters:

---

Auxiliary Query API Parameter Description

16. ListKmsInstances - Query KMS Instance List

Query the list of KMS instances under current account. Used to automatically obtain DKMSInstanceId when creating secrets.

CLI Command Format:

aliyun kms ListKmsInstances \
  --PageNumber 1 \
  --PageSize 10 \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Parameters:

Response:

Response Example:

{
  "KmsInstances": {
    "KmsInstance": [
      {
        "KmsInstanceId": "kst-hzz68c22f94iwd4k7v0jf",
        "KmsInstanceArn": "acs:kms:cn-hangzhou:120708975881****:keystore/kst-hzz68c22f94iwd4k7v0jf"
      }
    ]
  },
  "TotalCount": 1
}

---

17. ListKeys - Query Key List

Query the key list in current region, supports filtering by key type and KMS instance. Used to automatically obtain EncryptionKeyId when creating secrets.

CLI Command Format:

aliyun kms ListKeys \
  --Filters '[{"Key":"KeySpec","Values":["Aliyun_AES_256"]},{"Key":"DKMSInstanceId","Values":["<KMS-instance-ID>"]}]' \
  --PageNumber 1 \
  --PageSize 10 \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Parameters:

Filters Supported Key Values:

Response:

Response Example:

{
  "Keys": {
    "Key": [
      {
        "KeyId": "key-hzz68d1fd85qslv95ilz4",
        "KeyArn": "acs:kms:cn-hangzhou:123456:key/key-hzz68d1fd85qslv95ilz4"
      }
    ]
  },
  "TotalCount": 1
}

---

18. CreateKey - Create Key

Create a key. When ListKeys query returns no AES256 key, automatically create one for secret encryption.

CLI Command Format:

aliyun kms CreateKey \
  --KeySpec Aliyun_AES_256 \
  --KeyUsage ENCRYPT/DECRYPT \
  --DKMSInstanceId "<KMS-instance-ID>" \
  --Description "Secret management encryption key" \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Parameters:

Response:

Response Example:

{
  "KeyMetadata": {
    "KeyId": "key-hzz62f1cb66fa42qo****",
    "KeySpec": "Aliyun_AES_256",
    "KeyUsage": "ENCRYPT/DECRYPT",
    "KeyState": "Enabled",
    "DKMSInstanceId": "kst-hzz68c22f94iwd4k7v0jf",
    "CreationDate": "2024-03-25T10:00:00Z",
    "Creator": "154035569884****",
    "Description": "Secret management encryption key",
    "Origin": "Aliyun_KMS",
    "ProtectionLevel": "SOFTWARE"
  }
}

---

Secret Type Description

1. Generic (Generic Secret)

Used to store sensitive information in any format, such as API keys, database passwords, certificates, etc.

2. Rds (RDS Managed Secret)

Manage ApsaraDB RDS database account passwords, supports automatic rotation.

SecretData Format:

{"Accounts":[{"AccountName":"user1","AccountPassword":"password123"}]}

ExtendedConfig Format:

{
  "SecretSubType": "SingleUser",
  "DBInstanceId": "rm-xxxxxxxx",
  "CustomData": {}
}

3. RAMCredentials (RAM Managed Secret)

Manage RAM user AccessKeys, supports automatic rotation.

SecretData Format:

{"AccessKeys":[{"AccessKeyId":"LTAI5xxx","AccessKeySecret":"xxx"}]}

ExtendedConfig Format:

{
  "SecretSubType": "RamUserAccessKey",
  "UserName": "ram-user-name",
  "CustomData": {}
}

4. ECS (ECS Managed Secret)

Manage ECS instance login credentials (password or SSH key), supports automatic rotation.

Password Mode SecretData Format:

{"UserName":"root","Password":"password123"}

SSH Key Mode SecretData Format:

{"UserName":"root","PublicKey":"ssh-rsa xxx","PrivateKey":"-----BEGIN RSA PRIVATE KEY-----\nxxx\n-----END RSA PRIVATE KEY-----"}

ExtendedConfig Format:

{
  "SecretSubType": "Password",
  "RegionId": "cn-hangzhou",
  "InstanceId": "i-xxxxxxxx",
  "CustomData": {}
}

---

Limitations

KMS Secret Management Verification Methods

This document provides methods for verifying whether various KMS secret management operations were executed successfully.

Verification Process Overview

graph TB
    A[Create Secret] --> B[List Secrets]
    B --> C[Get Secret Value]
    C --> D[Update Secret Version]
    D --> E[Verify Version]
    E --> F[Delete Secret]
    F --> G[Restore Secret]

---

1. Create Secret Verification

Verification Command

# After creating secret, use DescribeSecret to verify creation success
aliyun kms DescribeSecret \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators

• HTTP status code: 200
• Response contains SecretName field with value matching creation
• CreateTime field shows creation time

Example Response

{
  "SecretName": "my-secret",
  "CreateTime": "2024-01-15T10:30:00Z",
  "SecretType": "Generic",
  "Description": "Test secret",
  "RequestId": "xxx"
}

---

2. Secret List Verification (Pagination Query)

Basic Query Verification

# Query secret list, confirm secret exists in list
aliyun kms ListSecrets \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Pagination Query Verification

# Verify pagination parameters take effect
aliyun kms ListSecrets \
  --PageNumber 1 \
  --PageSize 5 \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators

• HTTP status code: 200
• SecretList array contains target secret
• TotalCount shows correct total number of secrets
• PageNumber matches request parameter
• PageSize matches request parameter
• Number of returned secrets does not exceed PageSize

Pagination Traversal Verification

# First page
aliyun kms ListSecrets \
  --PageNumber 1 \
  --PageSize 10 \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

# Second page (if TotalCount > 10)
aliyun kms ListSecrets \
  --PageNumber 2 \
  --PageSize 10 \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Filter Query Verification

# Filter by name
aliyun kms ListSecrets \
  --Filters '[{"Key":"SecretName","Values":["<secret-name>"]}]' \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

# Filter by type
aliyun kms ListSecrets \
  --Filters '[{"Key":"SecretType","Values":["Generic"]}]' \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

---

3. Get Secret Value Verification

Verification Command

# Get secret value, verify secret content is correct
aliyun kms GetSecretValue \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators

• HTTP status code: 200
• SecretData field contains secret value
• VersionId field shows version ID
• VersionStages contains ACSCurrent

Example Response

{
  "SecretName": "my-secret",
  "SecretData": "my-secret-value",
  "VersionId": "v1",
  "VersionStages": {
    "VersionStage": ["ACSCurrent"]
  },
  "SecretDataType": "text",
  "RequestId": "xxx"
}

---

4. Store New Version Verification

Verification Command

# After storing new version, query version list to verify
aliyun kms ListSecretVersionIds \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators

• HTTP status code: 200
• VersionIds array contains new version ID
• New version's VersionStages contains ACSCurrent
• Old version's VersionStages becomes ACSPrevious

Verify New Version Value

aliyun kms GetSecretValue \
  --SecretName <secret-name> \
  --VersionId <new-version-id> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

---

5. Update Metadata Verification

Verification Command

# After updating description, query secret info to verify
aliyun kms DescribeSecret \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators

• HTTP status code: 200
• Description field shows updated description
• LastRotationDate or other metadata fields are updated

---

6. Version Stage Verification

Verification Command

# After updating version stage, query version list to verify
aliyun kms ListSecretVersionIds \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators

• Specified version's VersionStages is updated
• ACSCurrent label points to expected version

---

7. Rotation Policy Verification

Verification Command

# After updating rotation policy, query secret info to verify
aliyun kms DescribeSecret \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators

• AutomaticRotation field shows Enabled or Disabled
• RotationInterval field shows set rotation interval
• NextRotationDate shows next rotation time (if enabled)

Example Response

{
  "SecretName": "my-secret",
  "AutomaticRotation": "Enabled",
  "RotationInterval": "604800s",
  "NextRotationDate": "2024-01-22T10:30:00Z",
  "RequestId": "xxx"
}

---

8. Manual Rotation Verification

Verification Command

# After manual rotation, get current version secret value
aliyun kms GetSecretValue \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators

• VersionId shows new version ID after rotation
• VersionStages contains ACSCurrent
• Getting ACSPrevious version can retrieve old value

Verify Old Version

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

---

9. Delete Secret Verification

Verification Command (Soft Delete)

# After soft delete, secret enters deletion waiting period
aliyun kms DescribeSecret \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators (Soft Delete)

• HTTP status code: 200
• PlannedDeleteTime field shows planned deletion time

Verification Command (Force Delete)

# After force delete, secret is immediately deleted, query should return error
aliyun kms DescribeSecret \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators (Force Delete)

• Returns error: Forbidden.ResourceNotFound or EntityNotExist.Secret

---

10. Restore Secret Verification

Verification Command

# After restore, query secret info to verify
aliyun kms DescribeSecret \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators

• HTTP status code: 200
• PlannedDeleteTime field does not exist or is empty
• Secret status returns to normal

---

11. Secret Policy Verification

Verify Set Policy

# After setting policy, query policy to verify
aliyun kms GetSecretPolicy \
  --SecretName <secret-name> \
  --region <region-id> \
  --user-agent AlibabaCloud-Agent-Skills

Success Indicators

• HTTP status code: 200
• Policy field contains set policy content

---

Common Errors and Handling

---

Complete Verification Script Example

#!/bin/bash
# KMS Secret Management Complete Verification Script

SECRET_NAME="test-secret-$(date +%s)"
REGION="cn-hangzhou"
VERSION_1="v1"
VERSION_2="v2"

echo "=== 1. Create Secret ==="
aliyun kms CreateSecret \
  --SecretName "$SECRET_NAME" \
  --SecretData "initial-value" \
  --VersionId "$VERSION_1" \
  --Description "Test secret" \
  --region "$REGION" \
  --user-agent AlibabaCloud-Agent-Skills

echo "=== 2. Verify Creation ==="
aliyun kms DescribeSecret \
  --SecretName "$SECRET_NAME" \
  --region "$REGION" \
  --user-agent AlibabaCloud-Agent-Skills

echo "=== 3. Get Secret Value ==="
aliyun kms GetSecretValue \
  --SecretName "$SECRET_NAME" \
  --region "$REGION" \
  --user-agent AlibabaCloud-Agent-Skills

echo "=== 4. Store New Version ==="
aliyun kms PutSecretValue \
  --SecretName "$SECRET_NAME" \
  --SecretData "new-value" \
  --VersionId "$VERSION_2" \
  --region "$REGION" \
  --user-agent AlibabaCloud-Agent-Skills

echo "=== 5. Verify Version List ==="
aliyun kms ListSecretVersionIds \
  --SecretName "$SECRET_NAME" \
  --region "$REGION" \
  --user-agent AlibabaCloud-Agent-Skills

echo "=== 6. Delete Secret (Soft Delete) ==="
aliyun kms DeleteSecret \
  --SecretName "$SECRET_NAME" \
  --RecoveryWindowInDays 7 \
  --region "$REGION" \
  --user-agent AlibabaCloud-Agent-Skills

echo "=== 7. Restore Secret ==="
aliyun kms RestoreSecret \
  --SecretName "$SECRET_NAME" \
  --region "$REGION" \
  --user-agent AlibabaCloud-Agent-Skills

echo "=== 8. Force Delete Secret ==="
aliyun kms DeleteSecret \
  --SecretName "$SECRET_NAME" \
  --ForceDeleteWithoutRecovery true \
  --region "$REGION" \
  --user-agent AlibabaCloud-Agent-Skills

echo "=== Verification Complete ==="