Hologres Instance Management

Architecture

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

Installation

Pre-check: Aliyun CLI >= 3.3.1 required Run

aliyun version

to verify >= 3.3.1. If not installed or version too low, see

references/cli-installation-guide.md

for installation instructions. Then [MUST] run

aliyun configure set --auto-plugin-install true

to enable automatic plugin installation.

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

Authentication

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

aliyun configure list

RAM Policy

acs:hologram:{#regionId}:{#accountId}:instance/*

acs:hologram:{#regionId}:{#accountId}:instance/{#InstanceId}

[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

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

# 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

# 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

# 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

• 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 instance details by ID
aliyun hologram GET /api/v1/instances/{instanceId} \
  --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills

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

• 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

Quick Verification

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

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

• HTTP status code 200

• Success

  field is

  true

• InstanceList

  or

  Instance

  field contains valid data

Cleanup

Command Tables

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

aliyun hologram GET /api/v1/instances/{instanceId} --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills

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

AliyunHologresReadOnlyAccess