Alibabacloud Hologres Instance Manage

Hologres Instance Management

Skill for managing Alibaba Cloud Hologres instances - list all instances and get instance details.

Architecture

User → Aliyun CLI → Hologres API (hologram) → Instance List / Instance Details

Installation

Pre-check: Aliyun CLI >= 3.3.3 required

Run aliyun version to verify >= 3.3.3. If not installed or version too low,

run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to update,

or see references/cli-installation-guide.md for installation instructions.

Pre-check: Aliyun CLI plugin update required

[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation.

[MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

curl -fsSL --connect-timeout 4 --max-time 120 https://aliyuncli.alicdn.com/setup.sh | bash
aliyun version

[MUST] CLI User-Agent — Every aliyun CLI command invocation must include: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

Authentication

This skill relies on the Alibaba Cloud default credential chain. It never reads, prints, or explicitly handles AK/SK values.

Security Rules:

- NEVER read, echo, or print AK/SK values

- NEVER ask the user to input AK/SK directly

- NEVER use aliyun configure set with literal credential values

- ONLY use aliyun configure list to verify credential status

aliyun configure list

Check the output for a valid profile (AK, STS, EcsRamRole, or RamRoleArn).

If no valid profile exists, STOP here. The user must configure credentials outside of this session and return after aliyun configure list shows a valid profile.

RAM Policy

The following RAM permissions are required for this skill:

See references/ram-policies.md for the complete RAM policy document.

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read references/ram-policies.md to get the full list of permissions required by this SKILL

2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions

3. Pause and wait until the user confirms that the required permissions have been granted

Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call,

ALL user-customizable parameters (e.g., RegionId, instance names, resource group IDs,

tags, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Core Workflow

Task 1: List All Hologres Instances

Query all Hologres instances in the specified region.

# List all instances
aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" --body "{}" \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

# List instances with resource group filter
aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{"resourceGroupId":"rg-acfmvscak73zmby"}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

# List instances with tag filter
aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{"tag":[{"key":"env","value":"production"}]}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

# List instances by CMS instance type
aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{"cmsInstanceType":"standard"}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

Response Fields:

• InstanceId: Instance ID
• InstanceName: Instance name
• InstanceStatus: Status (Creating/Running/Suspended/Allocating)
• InstanceType: Type (Warehouse/Follower/Standard/Serverless/Shared)
• InstanceChargeType: Payment type (PostPaid/PrePaid)
• RegionId: Region ID
• Endpoints: Network endpoints list

Task 2: Get Instance Details

Get detailed information about a specific Hologres instance.

# Get instance details by ID
aliyun hologram GET /api/v1/instances/{instanceId} \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

# Example with actual instance ID
aliyun hologram GET /api/v1/instances/hgprecn-cn-i7m2v08uu00a \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

Response Fields:

• InstanceId: Instance ID
• InstanceName: Instance name (2-64 characters)
• InstanceStatus: Status (Creating/Running/Suspended/Allocating)
• InstanceType: Type (Warehouse/Follower/Standard/Serverless/Shared)
• InstanceChargeType: Payment type (PostPaid/PrePaid)
• Cpu: CPU cores
• Memory: Memory in GB
• Disk: Standard storage size in GB
• ColdStorage: Cold storage capacity in GB
• Version: Instance version
• Endpoints: Network endpoints with VPC/Internet/Intranet details
• AutoRenewal: Whether auto-renewal is enabled
• EnableHiveAccess: Whether data lake acceleration is enabled
• EnableServerless: Whether serverless computing is enabled
• EnableSSL: Whether SSL is enabled
• StorageType: Storage type (redundant/local)

Success Verification Method

See references/verification-method.md for detailed verification steps.

Quick Verification

# Verify ListInstances
aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" --body "{}" \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage | jq '.InstanceList'

# Verify GetInstance
aliyun hologram GET /api/v1/instances/{your-instance-id} \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage | jq '.Instance.InstanceStatus'

Success Indicators:

• HTTP status code 200
• Success field is true
• InstanceList or Instance field contains valid data

Cleanup

This skill performs read-only operations. No cleanup is required.

Command Tables

See references/related-commands.md for the complete CLI commands reference.

Best Practices

1. Always verify credentials before executing commands using aliyun configure list 2. Use filters (resourceGroupId, tags) to narrow down results when listing many instances 3. Check instance status before performing operations - ensure instance is in Running state 4. Use appropriate network endpoints - choose VPCSingleTunnel for internal access, Internet for external access 5. Monitor instance expiration - check ExpirationTime for PrePaid instances to avoid service interruption 6. Enable SSL for production environments to ensure secure connections

Reference Links

Error Handling

For more error codes, see Hologres Error Center.

Acceptance Criteria: alibabacloud-hologres-instance-manage

Scenario: Hologres Instance Management Purpose: Skill testing acceptance criteria for listing and querying Hologres instances

---

Correct CLI Command Patterns

1. Product — Verify product name exists

✅ CORRECT

aliyun hologram ...

❌ INCORRECT

aliyun hologres ...      # Wrong product name
aliyun Hologram ...      # Case sensitivity may matter
aliyun holo ...          # Abbreviated name not valid

2. Command — Verify ROA-style path syntax

✅ CORRECT

# ListInstances - POST with path, timeout and user-agent
aliyun hologram POST /api/v1/instances --header "Content-Type=application/json" --body '{}' --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills

# GetInstance - GET with path parameter, timeout and user-agent
aliyun hologram GET /api/v1/instances/hgprecn-cn-i7m2v08uu00a --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT

# Wrong: Using RPC-style action name
aliyun hologram ListInstances

# Wrong: Missing HTTP method
aliyun hologram /api/v1/instances

# Wrong: Wrong HTTP method
aliyun hologram GET /api/v1/instances  # ListInstances requires POST

3. Parameters — Verify parameter format

✅ CORRECT

# Header parameter format
--header "Content-Type=application/json"

# Body as JSON string
--body '{"resourceGroupId":"rg-xxx"}'

# Tags as JSON array
--body '{"tag":[{"key":"env","value":"prod"}]}'

❌ INCORRECT

# Wrong: Missing quotes around header value
--header Content-Type=application/json

# Wrong: Invalid JSON in body
--body {resourceGroupId:rg-xxx}

# Wrong: Incorrect tag structure
--body '{"tag":{"key":"env","value":"prod"}}'  # Should be array

4. User-Agent and Timeout — Verify required flags

✅ CORRECT

aliyun hologram POST /api/v1/instances ... --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills

❌ INCORRECT

# Wrong: Missing user-agent
aliyun hologram POST /api/v1/instances ...

# Wrong: Missing timeout
aliyun hologram POST /api/v1/instances ... --user-agent AlibabaCloud-Agent-Skills

# Wrong: Wrong flag name
aliyun hologram POST /api/v1/instances ... --useragent AlibabaCloud-Agent-Skills

---

Correct Python Common SDK Patterns (if applicable)

1. Import Patterns

✅ CORRECT

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

❌ INCORRECT

# Wrong: Old SDK imports
from aliyunsdkcore.client import AcsClient
from aliyunsdkhologram.request.v20220601.ListInstancesRequest import ListInstancesRequest

# Wrong: Missing credentials import
from alibabacloud_tea_openapi.client import Client as OpenApiClient
# Missing: from alibabacloud_credentials.client import Client as CredentialClient

2. Authentication — Must use CredentialClient

✅ CORRECT

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

❌ INCORRECT

# Wrong: Hardcoding credentials
config = open_api_models.Config()
config.access_key_id = 'LTAI5tXXXXXX'          # NEVER do this
config.access_key_secret = '8dXXXXXXXXXX'      # NEVER do this

# Wrong: Using environment variables directly in code
import os
config.access_key_id = os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID']  # Use CredentialClient instead

3. ROA Style API Configuration

✅ CORRECT

# ListInstances - ROA POST
params = open_api_models.Params(
    action='ListInstances',
    version='2022-06-01',
    protocol='HTTPS',
    method='POST',
    auth_type='AK',
    style='ROA',
    pathname='/api/v1/instances',
    req_body_type='json',
    body_type='json'
)

# Request with body (ROA style)
body = {'resourceGroupId': 'rg-xxx'}
request = open_api_models.OpenApiRequest(body=body)

❌ INCORRECT

# Wrong: Using RPC style for ROA API
params = open_api_models.Params(
    action='ListInstances',
    version='2022-06-01',
    style='RPC',          # Should be 'ROA'
    pathname='/',         # Should be '/api/v1/instances'
)

# Wrong: Using query instead of body for ROA POST
request = open_api_models.OpenApiRequest(
    query=OpenApiUtilClient.query(queries)  # Should use body for ROA
)

4. GetInstance Path Parameter

✅ CORRECT

# GetInstance - ROA GET with path parameter
instance_id = 'hgprecn-cn-i7m2v08uu00a'
params = open_api_models.Params(
    action='GetInstance',
    version='2022-06-01',
    protocol='HTTPS',
    method='GET',
    auth_type='AK',
    style='ROA',
    pathname=f'/api/v1/instances/{instance_id}',  # Path parameter in URL
    req_body_type='json',
    body_type='json'
)

❌ INCORRECT

# Wrong: Putting instanceId in query parameters
params = open_api_models.Params(
    pathname='/api/v1/instances',  # Missing instance ID in path
)
queries = {'instanceId': instance_id}  # Wrong location

---

Request/Response Validation

ListInstances Request

✅ CORRECT Request Body

{}

{
  "resourceGroupId": "rg-acfmvscak73zmby"
}

{
  "tag": [
    {"key": "env", "value": "production"}
  ]
}

❌ INCORRECT Request Body

{
  "tags": [{"key": "env", "value": "prod"}]  // Wrong: 'tags' instead of 'tag'
}

ListInstances Response Validation

✅ Valid Response

{
  "RequestId": "D1303CD4-AA70-5998-8025-F55B22C50840",
  "InstanceList": [...],
  "Success": "true",
  "HttpStatusCode": "200"
}

GetInstance Response Validation

✅ Valid Response

{
  "RequestId": "865A02C2-B374-5DD4-9B34-0CA15DA1AEBD",
  "Instance": {
    "InstanceId": "hgpostcn-cn-tl32s6cgw00b",
    "InstanceStatus": "Running",
    ...
  },
  "Success": true,
  "HttpStatusCode": "200"
}

---

Error Handling Patterns

Permission Error

✅ CORRECT Handling

# Check for permission error and provide guidance
RESPONSE=$(aliyun hologram POST /api/v1/instances ...)
if echo "$RESPONSE" | grep -q "NoPermission"; then
  echo "Permission denied. Please grant hologram:ListInstances permission."
  echo "See references/ram-policies.md for required permissions."
fi

Instance Not Found

✅ CORRECT Handling

# Validate instance exists before detailed operations
RESPONSE=$(aliyun hologram GET /api/v1/instances/$INSTANCE_ID ...)
if echo "$RESPONSE" | grep -q "InstanceNotFound"; then
  echo "Instance $INSTANCE_ID not found. Use ListInstances to get valid IDs."
fi

---

Checklist

Before considering this skill complete, verify:

• [ ] All CLI commands use aliyun hologram (correct product name)
• [ ] ListInstances uses POST /api/v1/instances
• [ ] GetInstance uses GET /api/v1/instances/{instanceId}
• [ ] All commands include --user-agent AlibabaCloud-Agent-Skills
• [ ] All commands include --read-timeout 4
• [ ] POST requests include --header "Content-Type=application/json"
• [ ] Request bodies are valid JSON
• [ ] Tags use array format: [{"key":"...","value":"..."}]
• [ ] Python SDK uses CredentialClient() for authentication
• [ ] Python SDK uses style='ROA' for these APIs
• [ ] Error handling covers NoPermission and InstanceNotFound cases

Aliyun CLI Installation & Configuration Guide

Complete guide for installing and configuring Aliyun CLI.

Aliyun CLI 3.3.3+: Supports installing and using all published Alibaba Cloud product plugins. Make sure to upgrade to 3.3.3 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.3)
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.3+ 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

RAM Permissions Required

This document lists all RAM permissions required for the Hologres Instance Management skill.

Summary Table

RAM Policy Document

Minimum Required Policy

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "hologram:ListInstances",
        "hologram:GetInstance"
      ],
      "Resource": "*"
    }
  ]
}

Resource-Scoped Policy (Recommended for Production)

For tighter security, scope permissions to specific regions or instances:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "hologram:ListInstances"
      ],
      "Resource": "acs:hologram:cn-hangzhou:*:instance/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "hologram:GetInstance"
      ],
      "Resource": "acs:hologram:cn-hangzhou:*:instance/hgprecn-cn-*"
    }
  ]
}

System Policy Alternative

Instead of creating a custom policy, you can attach the following system policy:

Applying the Policy

Option 1: Attach System Policy

1. Go to RAM Console 2. Navigate to Users or Roles 3. Select the target user/role 4. Click Add Permissions 5. Search for AliyunHologresReadOnlyAccess 6. Select and confirm

Option 2: Create Custom Policy

1. Go to RAM Console 2. Navigate to Policies → Create Policy 3. Select Script mode 4. Paste the policy JSON above 5. Name the policy (e.g., HologresInstanceReadAccess) 6. Attach to the target user/role

Permission Verification

After granting permissions, verify access:

# Test ListInstances permission
aliyun hologram POST /api/v1/instances --header "Content-Type=application/json" --body "{}" --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

# Test GetInstance permission (replace with actual instance ID)
aliyun hologram GET /api/v1/instances/hgprecn-cn-your-instance-id --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

Common Permission Errors

Best Practices

1. Use Least Privilege: Only grant the minimum permissions needed 2. Scope to Resources: Use resource ARNs to limit access to specific regions/instances 3. Use RAM Roles: Prefer RAM roles over long-term access keys when possible 4. Regular Auditing: Periodically review and revoke unused permissions 5. Enable MFA: Require multi-factor authentication for sensitive operations

Related CLI Commands

Complete reference for all CLI commands used in the Hologres Instance Management skill.

API Information

Command Reference

ListInstances - List All Hologres Instances

API Endpoint: POST /api/v1/instances

CLI Command:

aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

Request Parameters:

cmsInstanceType Values:

• standard - Standard instance
• follower - Read-only follower instance
• mc-acceleration - MaxCompute acceleration instance
• warehouse - Warehouse instance
• high-memory - High memory instance
• serverless - Serverless instance

Example Commands:

# List all instances (no filters)
aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

# Filter by resource group
aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{"resourceGroupId":"rg-acfmvscak73zmby"}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

# Filter by tags
aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{"tag":[{"key":"environment","value":"production"}]}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

# Filter by CMS instance type
aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{"cmsInstanceType":"standard"}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

# Combined filters
aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{"resourceGroupId":"rg-xxx","cmsInstanceType":"standard","tag":[{"key":"env","value":"prod"}]}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

Response Structure:

{
  "RequestId": "D1303CD4-AA70-5998-8025-F55B22C50840",
  "InstanceList": [
    {
      "InstanceId": "hgpostcn-cn-aaab9ad2d8fb",
      "InstanceName": "test_instance",
      "InstanceStatus": "Running",
      "InstanceType": "Standard",
      "InstanceChargeType": "PrePaid",
      "RegionId": "cn-hangzhou",
      "ZoneId": "cn-hangzhou-h",
      "CreationTime": "2022-12-16T02:24:05Z",
      "ExpirationTime": "2023-05-04T16:00:00.000Z",
      "Version": "1.3.37",
      "EnableHiveAccess": "true",
      "EnableSSL": "true",
      "StorageType": "redundant",
      "ResourceGroupId": "rg-acfmvscak73zmby",
      "CommodityCode": "hologram_postpay_public_cn",
      "LeaderInstanceId": "hgprecn-cn-2r42sqvxm006",
      "SuspendReason": "Manual",
      "Tags": [{"Key": "tag", "Value": "value"}],
      "Endpoints": [
        {
          "Endpoint": "hgpostcn-cn-xxx.hologres.aliyuncs.com:80",
          "Type": "Internet",
          "Enabled": true,
          "VSwitchId": "vsw-xxx",
          "VpcId": "vpc-xxx",
          "VpcInstanceId": "hgpostcn-cn-xxx-frontend-st"
        }
      ]
    }
  ],
  "Success": "true",
  "HttpStatusCode": "200"
}

---

GetInstance - Get Instance Details

API Endpoint: GET /api/v1/instances/{instanceId}

CLI Command:

aliyun hologram GET /api/v1/instances/{instanceId} \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

Path Parameters:

Example Commands:

# Get instance details
aliyun hologram GET /api/v1/instances/hgprecn-cn-i7m2v08uu00a \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

# With specific region endpoint
aliyun hologram GET /api/v1/instances/hgpostcn-cn-aaab9ad2d8fb \
  --endpoint hologram.cn-hangzhou.aliyuncs.com \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

Response Structure:

{
  "RequestId": "865A02C2-B374-5DD4-9B34-0CA15DA1AEBD",
  "Instance": {
    "InstanceId": "hgpostcn-cn-tl32s6cgw00b",
    "InstanceName": "test",
    "InstanceStatus": "Running",
    "InstanceType": "Standard",
    "InstanceChargeType": "PrePaid",
    "InstanceOwner": "12345678900000",
    "RegionId": "cn-hangzhou",
    "ZoneId": "cn-hangzhou-h",
    "Cpu": 32,
    "Memory": 128,
    "Disk": "500",
    "ColdStorage": 800,
    "ComputeNodeCount": 2,
    "GatewayCount": 2,
    "GatewayCpu": 4,
    "GatewayMemory": 16,
    "CreationTime": "2021-02-03T13:06:06Z",
    "ExpirationTime": "2021-02-03T13:06:06Z",
    "Version": "r1.3.37",
    "AutoRenewal": "true",
    "EnableHiveAccess": "true",
    "EnableServerless": true,
    "EnableSSL": true,
    "StorageType": "redundant",
    "ResourceGroupId": "rg-aekzuq7hpybze2i",
    "CommodityCode": "hologram_combo_public_cn",
    "LeaderInstanceId": "hgpostcn-cn-i7m2ncd6w002",
    "SuspendReason": "Manual",
    "ReplicaRole": "Active",
    "Tags": [{"Key": "tag", "Value": "value"}],
    "Endpoints": [
      {
        "Endpoint": "hgprecn-cn-xxx.hologres.aliyuncs.com:80",
        "Type": "Internet",
        "Enabled": true,
        "VSwitchId": "vsw-bp1jqwp2ys6kp7tc9t983",
        "VpcId": "vpc-uf66jjber3hgvwhki3wna",
        "VpcInstanceId": "hgprecn-cn-uqm362o1b001-frontend-st",
        "AlternativeEndpoints": "hgprecn-cn-xxx.hologres.aliyuncs.com:80"
      }
    ]
  },
  "Success": true,
  "HttpStatusCode": "200"
}

---

Response Field Reference

Instance Status Values

Instance Type Values

Instance Charge Type Values

Endpoint Type Values

Storage Type Values

Suspend Reason Values

---

Quick Reference

Important Notes

1. User-Agent Header: All commands must include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage 2. Timeout: All commands must include --read-timeout 4 (4 seconds) 3. Content-Type: POST requests require --header "Content-Type=application/json" 4. ROA Style: These APIs use RESTful style, not RPC 5. Region: Ensure you're querying the correct region where instances exist 6. Credentials: Rely on default credential chain; never handle AK/SK explicitly

Success Verification Method

This document provides detailed verification steps to confirm successful execution of Hologres instance management operations.

Scenario Goal Verification

Task 1: Verify ListInstances Operation

Expected Outcome: Successfully retrieve a list of all Hologres instances in the account.

Verification Command:

# Execute ListInstances and verify response
aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

Success Indicators: 1. HTTP status code is 200 2. Response contains "Success": "true" or "Success": true 3. InstanceList field is present (may be empty array if no instances exist) 4. No ErrorCode or ErrorMessage in response

Verification Script:

#!/bin/bash
# Verify ListInstances operation

RESPONSE=$(aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage 2>&1)

# Check if response contains success indicator
if echo "$RESPONSE" | grep -q '"Success"'; then
  SUCCESS=$(echo "$RESPONSE" | grep -o '"Success"[[:space:]]*:[[:space:]]*[^,}]*' | head -1)
  if echo "$SUCCESS" | grep -qiE 'true'; then
    echo "✅ ListInstances: SUCCESS"
    # Count instances
    COUNT=$(echo "$RESPONSE" | grep -o '"InstanceId"' | wc -l)
    echo "   Found $COUNT instance(s)"
  else
    echo "❌ ListInstances: FAILED"
    echo "   Response: $RESPONSE"
  fi
else
  echo "❌ ListInstances: ERROR"
  echo "   Response: $RESPONSE"
fi

---

Task 2: Verify GetInstance Operation

Expected Outcome: Successfully retrieve detailed information about a specific Hologres instance.

Prerequisites:

• You must have a valid instance ID (obtain from ListInstances first)

Verification Command:

# First, get an instance ID from ListInstances
INSTANCE_ID=$(aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage \
  | grep -o '"InstanceId":"[^"]*"' | head -1 | cut -d'"' -f4)

# Then verify GetInstance with that ID
if [ -n "$INSTANCE_ID" ]; then
  aliyun hologram GET /api/v1/instances/$INSTANCE_ID \
    --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage
fi

Success Indicators: 1. HTTP status code is 200 2. Response contains "Success": true 3. Instance object is present with detailed fields 4. Instance.InstanceId matches the requested ID 5. Instance.InstanceStatus field is present

Verification Script:

#!/bin/bash
# Verify GetInstance operation

# Get first instance ID
INSTANCE_ID=$(aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage 2>/dev/null \
  | grep -o '"InstanceId":"[^"]*"' | head -1 | cut -d'"' -f4)

if [ -z "$INSTANCE_ID" ]; then
  echo "⚠️  No instances found to verify GetInstance"
  exit 0
fi

echo "Testing GetInstance with ID: $INSTANCE_ID"

RESPONSE=$(aliyun hologram GET /api/v1/instances/$INSTANCE_ID \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage 2>&1)

# Check for success
if echo "$RESPONSE" | grep -q '"Success"[[:space:]]*:[[:space:]]*true'; then
  echo "✅ GetInstance: SUCCESS"
  
  # Extract key fields
  NAME=$(echo "$RESPONSE" | grep -o '"InstanceName":"[^"]*"' | cut -d'"' -f4)
  STATUS=$(echo "$RESPONSE" | grep -o '"InstanceStatus":"[^"]*"' | cut -d'"' -f4)
  TYPE=$(echo "$RESPONSE" | grep -o '"InstanceType":"[^"]*"' | cut -d'"' -f4)
  
  echo "   Instance Name: $NAME"
  echo "   Status: $STATUS"
  echo "   Type: $TYPE"
else
  echo "❌ GetInstance: FAILED"
  echo "   Response: $RESPONSE"
fi

---

Complete Verification Suite

Run all verifications in sequence:

#!/bin/bash
# Complete verification suite for Hologres Instance Management skill

echo "=========================================="
echo "Hologres Instance Management Verification"
echo "=========================================="
echo ""

# Step 1: Verify credentials
echo "Step 1: Checking credentials..."
if aliyun configure list | grep -q "AK\|STS"; then
  echo "✅ Credentials configured"
else
  echo "❌ No valid credentials found"
  exit 1
fi
echo ""

# Step 2: Verify ListInstances
echo "Step 2: Testing ListInstances..."
RESPONSE=$(aliyun hologram POST /api/v1/instances \
  --header "Content-Type=application/json" \
  --body '{}' \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage 2>&1)

if echo "$RESPONSE" | grep -qiE '"Success"[[:space:]]*:[[:space:]]*"?true'; then
  echo "✅ ListInstances: SUCCESS"
  INSTANCE_COUNT=$(echo "$RESPONSE" | grep -o '"InstanceId"' | wc -l)
  echo "   Found $INSTANCE_COUNT instance(s)"
  
  # Get first instance ID for GetInstance test
  INSTANCE_ID=$(echo "$RESPONSE" | grep -o '"InstanceId":"[^"]*"' | head -1 | cut -d'"' -f4)
else
  echo "❌ ListInstances: FAILED"
  echo "$RESPONSE"
  exit 1
fi
echo ""

# Step 3: Verify GetInstance (if instances exist)
if [ -n "$INSTANCE_ID" ]; then
  echo "Step 3: Testing GetInstance with ID: $INSTANCE_ID..."
  RESPONSE=$(aliyun hologram GET /api/v1/instances/$INSTANCE_ID \
    --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage 2>&1)
  
  if echo "$RESPONSE" | grep -qiE '"Success"[[:space:]]*:[[:space:]]*true'; then
    echo "✅ GetInstance: SUCCESS"
    STATUS=$(echo "$RESPONSE" | grep -o '"InstanceStatus":"[^"]*"' | head -1 | cut -d'"' -f4)
    echo "   Instance Status: $STATUS"
  else
    echo "❌ GetInstance: FAILED"
    echo "$RESPONSE"
  fi
else
  echo "Step 3: Skipped (no instances to test GetInstance)"
fi
echo ""

echo "=========================================="
echo "Verification Complete"
echo "=========================================="

---

Error Scenarios and Resolution

Permission Denied

Symptom:

{
  "ErrorCode": "NoPermission",
  "ErrorMessage": "RAM user permission is insufficient, please grant AliyunHologresReadOnlyAccess permission."
}

Resolution: 1. Grant hologram:ListInstances and hologram:GetInstance permissions 2. Or attach AliyunHologresReadOnlyAccess system policy

Instance Not Found

Symptom:

{
  "ErrorCode": "InstanceNotFound",
  "ErrorMessage": "Instance does not exist"
}

Resolution: 1. Verify the instance ID is correct 2. Check if the instance exists in the specified region 3. Use ListInstances to get valid instance IDs

Invalid Credentials

Symptom:

{
  "ErrorCode": "InvalidAccessKeyId.NotFound",
  "ErrorMessage": "Specified access key is not found"
}

Resolution: 1. Run aliyun configure list to check current configuration 2. Reconfigure credentials with valid access keys 3. Verify the access key is active in RAM Console

---

Automated Health Check

Add this to your monitoring scripts:

#!/bin/bash
# Health check for Hologres API access

check_hologres_api() {
  local result
  result=$(aliyun hologram POST /api/v1/instances \
    --header "Content-Type=application/json" \
    --body '{}' \
    --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage 2>&1)
  
  if echo "$result" | grep -qiE '"Success"[[:space:]]*:[[:space:]]*"?true'; then
    return 0
  else
    return 1
  fi
}

if check_hologres_api; then
  echo "Hologres API: OK"
  exit 0
else
  echo "Hologres API: FAILED"
  exit 1
fi