| name | alibabacloud-hologres-instance-manage |
| description | Alibaba Cloud Hologres Instance Management Skill. Use for listing and querying Hologres instances.
Triggers: "hologres", "list instances", "get instance details", "hologres instance", "hologram".
|
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:
| Product | RAM Action | Resource Scope | Description |
|---|
| Hologram | hologram:ListInstances | acs:hologram:{#regionId}:{#accountId}:instance/* | List all Hologres instances |
| Hologram | hologram:GetInstance | acs: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:
- Read
references/ram-policies.md to get the full list of permissions required by this SKILL
- Use
ram-permission-diagnose skill to guide the user through requesting the necessary permissions
- 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 Name | Required/Optional | Description | Default Value |
|---|
| RegionId | Optional | Region where instances are located | User's default region |
| InstanceId | Required (for GetInstance) | The ID of the Hologres instance | None |
| resourceGroupId | Optional | Filter by resource group ID | None |
| tag | Optional | Filter by tags (key-value pairs) | None |
| cmsInstanceType | Optional | Cloud 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.
aliyun hologram POST /api/v1/instances \
--header "Content-Type=application/json" --body "{}" \
--read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage
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
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
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 IDInstanceName: Instance nameInstanceStatus: Status (Creating/Running/Suspended/Allocating)InstanceType: Type (Warehouse/Follower/Standard/Serverless/Shared)InstanceChargeType: Payment type (PostPaid/PrePaid)RegionId: Region IDEndpoints: Network endpoints list
Task 2: Get Instance Details
Get detailed information about a specific Hologres instance.
aliyun hologram GET /api/v1/instances/{instanceId} \
--read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage
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 IDInstanceName: 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 coresMemory: Memory in GBDisk: Standard storage size in GBColdStorage: Cold storage capacity in GBVersion: Instance versionEndpoints: Network endpoints with VPC/Internet/Intranet detailsAutoRenewal: Whether auto-renewal is enabledEnableHiveAccess: Whether data lake acceleration is enabledEnableServerless: Whether serverless computing is enabledEnableSSL: Whether SSL is enabledStorageType: Storage type (redundant/local)
Success Verification Method
See references/verification-method.md for detailed verification steps.
Quick Verification
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'
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 trueInstanceList 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.
| Action | CLI Command | Description |
|---|
| List Instances | aliyun hologram POST /api/v1/instances --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage | Get list of all Hologres instances |
| Get Instance | aliyun hologram GET /api/v1/instances/{instanceId} --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage | Get details of a specific instance |
Best Practices
- Always verify credentials before executing commands using
aliyun configure list
- Use filters (resourceGroupId, tags) to narrow down results when listing many instances
- Check instance status before performing operations - ensure instance is in
Running state
- Use appropriate network endpoints - choose VPCSingleTunnel for internal access, Internet for external access
- Monitor instance expiration - check
ExpirationTime for PrePaid instances to avoid service interruption
- Enable SSL for production environments to ensure secure connections
Reference Links
Error Handling
| HTTP Status | Error Code | Error Message | Resolution |
|---|
| 403 | NoPermission | RAM user permission is insufficient | Grant AliyunHologresReadOnlyAccess permission |
| 400 | InvalidParameter | Invalid parameter value | Check parameter format and constraints |
| 404 | InstanceNotFound | Instance does not exist | Verify instance ID is correct |
For more error codes, see Hologres Error Center.
