Hologres Instance Management#

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

Architecture#

text

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.

bash

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

bash

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:

ProductRAM ActionResource ScopeDescriptionHologramhologram:ListInstancesacs:hologram:{#regionId}:{#accountId}:instance/*List all Hologres instancesHologramhologram:GetInstanceacs:hologram:{#regionId}:{#accountId}:instance/{#InstanceId}Get instance details

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.

Parameter NameRequired/OptionalDescriptionDefault ValueRegionIdOptionalRegion where instances are locatedUser's default regionInstanceIdRequired (for GetInstance)The ID of the Hologres instanceNoneresourceGroupIdOptionalFilter by resource group IDNonetagOptionalFilter by tags (key-value pairs)NonecmsInstanceTypeOptionalCloud Monitor instance type (standard/follower/mc-acceleration/warehouse/high-memory/serverless)None

Core Workflow#

Task 1: List All Hologres Instances#

Query all Hologres instances in the specified region.

bash

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

bash

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

bash

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

ActionCLI CommandDescriptionList Instancesaliyun hologram POST /api/v1/instances --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manageGet list of all Hologres instancesGet Instancealiyun hologram GET /api/v1/instances/{instanceId} --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manageGet details of a specific instance

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#

ReferenceDescriptionreferences/cli-installation-guide.mdAliyun CLI installation guidereferences/ram-policies.mdRequired RAM permissionsreferences/related-commands.mdComplete CLI commands referencereferences/verification-method.mdSuccess verification stepsHologres API DocumentationOfficial API documentation

Error Handling#

HTTP StatusError CodeError MessageResolution403NoPermissionRAM user permission is insufficientGrant AliyunHologresReadOnlyAccess permission400InvalidParameterInvalid parameter valueCheck parameter format and constraints404InstanceNotFoundInstance does not existVerify instance ID is correct

For more error codes, see Hologres Error Center.