/alibabacloud-hologres-instance-manage

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](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 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.

# 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`: Statu