Back to Details

alibabacloud-hologres-instance-manage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Hologres Instance Management

Hologres实例管理

Skill for managing Alibaba Cloud Hologres instances - list all instances and get instance details.
用于管理阿里云Hologres实例的Skill——支持列出所有实例和获取实例详情。

Architecture

架构

User → Aliyun CLI → Hologres API (hologram) → Instance List / Instance Details
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.
bash
curl -fsSL --connect-timeout 4 --max-time 120 https://aliyuncli.alicdn.com/install.sh | bash
aliyun version
预检查：要求Aliyun CLI版本 >= 3.3.1 运行
aliyun version
确认版本不低于3.3.1。如果未安装或版本过低， 请参考
references/cli-installation-guide.md
的安装指引操作。 之后[必须]运行
aliyun configure set --auto-plugin-install true
开启插件自动安装功能。
bash
curl -fsSL --connect-timeout 4 --max-time 120 https://aliyuncli.alicdn.com/install.sh | bash
aliyun version

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.
本Skill依赖阿里云默认凭证链，不会读取、打印或显式处理AK/SK的值。
安全规则：
  • 禁止读取、回显或打印AK/SK值
  • 禁止要求用户直接输入AK/SK
  • 禁止使用带明文凭证值的
    aliyun configure set
    命令
  • 仅可使用
    aliyun configure list
    命令验证凭证状态
bash
aliyun configure list
检查输出中是否存在有效配置（AK、STS、EcsRamRole或RamRoleArn）。
如果不存在有效配置，请停止操作。 用户必须在当前会话外完成凭证配置，待
aliyun configure list
显示有效配置后再返回操作。

RAM Policy

RAM策略

The following RAM permissions are required for this skill:
ProductRAM ActionResource ScopeDescription
Hologramhologram:ListInstances
acs:hologram:{#regionId}:{#accountId}:instance/*
List all Hologres instances
Hologramhologram: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:
  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
本Skill需要以下RAM权限：
产品RAM操作资源范围描述
Hologramhologram:ListInstances
acs:hologram:{#regionId}:{#accountId}:instance/*
列出所有Hologres实例
Hologramhologram:GetInstance
acs:hologram:{#regionId}:{#accountId}:instance/{#InstanceId}
获取实例详情
完整RAM策略文档请查看references/ram-policies.md。
[必须]权限失败处理规则： 执行过程中任何命令或API调用因权限错误失败时，遵循以下流程处理：
  1. 读取
    references/ram-policies.md
    获取本Skill所需的完整权限列表
  2. 使用
    ram-permission-diagnose
    skill引导用户申请所需权限
  3. 暂停操作，等待用户确认已授予所需权限后再继续

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 Value
RegionIdOptionalRegion where instances are locatedUser's default region
InstanceIdRequired (for GetInstance)The ID of the Hologres instanceNone
resourceGroupIdOptionalFilter by resource group IDNone
tagOptionalFilter by tags (key-value pairs)None
cmsInstanceTypeOptionalCloud Monitor instance type (standard/follower/mc-acceleration/warehouse/high-memory/serverless)None
重要提示：参数确认 — 执行任何命令或API调用前， 所有用户可自定义参数（例如RegionId、实例名、资源组ID、 标签等）必须与用户确认。未经用户明确许可，不得假设或使用默认值。
参数名必填/可选描述默认值
RegionId可选实例所在区域用户默认区域
InstanceIdGetInstance操作必填Hologres实例ID无
resourceGroupId可选按资源组ID过滤无
tag可选按标签（键值对）过滤无
cmsInstanceType可选云监控实例类型（standard/follower/mc-acceleration/warehouse/high-memory/serverless）无

Core Workflow

核心工作流

Task 1: List All Hologres Instances

任务1：列出所有Hologres实例

Query all Hologres instances in the specified region.
bash
undefined
查询指定区域下的所有Hologres实例。
bash
undefined

List all instances

列出所有实例

aliyun hologram POST /api/v1/instances
--header "Content-Type=application/json" --body "{}"
--read-timeout 4 --user-agent AlibabaCloud-Agent-Skills
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
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
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

按CMS实例类型列出实例

aliyun hologram POST /api/v1/instances
--header "Content-Type=application/json"
--body '{"cmsInstanceType":"standard"}'
--read-timeout 4 --user-agent AlibabaCloud-Agent-Skills

**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
aliyun hologram POST /api/v1/instances
--header "Content-Type=application/json"
--body '{"cmsInstanceType":"standard"}'
--read-timeout 4 --user-agent AlibabaCloud-Agent-Skills

**响应字段：**
- `InstanceId`：实例ID
- `InstanceName`：实例名称
- `InstanceStatus`：实例状态（Creating/Running/Suspended/Allocating）
- `InstanceType`：实例类型（Warehouse/Follower/Standard/Serverless/Shared）
- `InstanceChargeType`：付费类型（PostPaid/PrePaid）
- `RegionId`：区域ID
- `Endpoints`：网络端点列表

Task 2: Get Instance Details

任务2：获取实例详情

Get detailed information about a specific Hologres instance.
bash
undefined
获取指定Hologres实例的详细信息。
bash
undefined

Get instance details by ID

按ID获取实例详情

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

Example with actual instance ID

填入实际实例ID的示例

aliyun hologram GET /api/v1/instances/hgprecn-cn-i7m2v08uu00a
--read-timeout 4 --user-agent AlibabaCloud-Agent-Skills

**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)
aliyun hologram GET /api/v1/instances/hgprecn-cn-i7m2v08uu00a
--read-timeout 4 --user-agent AlibabaCloud-Agent-Skills

**响应字段：**
- `InstanceId`：实例ID
- `InstanceName`：实例名称（2-64个字符）
- `InstanceStatus`：实例状态（Creating/Running/Suspended/Allocating）
- `InstanceType`：实例类型（Warehouse/Follower/Standard/Serverless/Shared）
- `InstanceChargeType`：付费类型（PostPaid/PrePaid）
- `Cpu`：CPU核数
- `Memory`：内存大小，单位GB
- `Disk`：标准存储大小，单位GB
- `ColdStorage`：冷存储容量，单位GB
- `Version`：实例版本
- `Endpoints`：网络端点，包含VPC/公网/内网详细信息
- `AutoRenewal`：是否开启自动续费
- `EnableHiveAccess`：是否开启数据湖加速
- `EnableServerless`：是否开启Serverless计算
- `EnableSSL`：是否开启SSL
- `StorageType`：存储类型（redundant/local）

Success Verification Method

成功验证方法

See references/verification-method.md for detailed verification steps.
详细验证步骤请查看references/verification-method.md。

Quick Verification

快速验证

bash
undefined
bash
undefined

Verify ListInstances

验证ListInstances接口

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

Verify GetInstance

验证GetInstance接口

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

**Success Indicators:**
- HTTP status code 200
- `Success` field is `true`
- `InstanceList` or `Instance` field contains valid data
aliyun hologram GET /api/v1/instances/{your-instance-id}
--read-timeout 4 --user-agent AlibabaCloud-Agent-Skills | jq '.Instance.InstanceStatus'

**成功标识：**
- HTTP状态码为200
- `Success`字段值为`true`
- `InstanceList`或`Instance`字段包含有效数据

Cleanup

清理

This skill performs read-only operations. No cleanup is required.
本Skill仅执行只读操作，无需清理。

Command Tables

命令表

See references/related-commands.md for the complete CLI commands reference.
ActionCLI CommandDescription
List Instances
aliyun hologram POST /api/v1/instances --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills
Get list of all Hologres instances
Get Instance
aliyun hologram GET /api/v1/instances/{instanceId} --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills
Get details of a specific instance
完整CLI命令参考请查看references/related-commands.md。
操作CLI命令描述
列出实例
aliyun hologram POST /api/v1/instances --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills
获取所有Hologres实例列表
获取实例
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
  1. 执行命令前始终验证凭证，使用
    aliyun configure list
    命令检查
  2. 列出大量实例时使用过滤器（资源组ID、标签）缩小结果范围
  3. 执行操作前检查实例状态，确保实例处于
    Running
    状态
  4. 使用合适的网络端点——内部访问选择VPCSingleTunnel，外部访问选择公网端点
  5. 监控实例到期时间——检查包年包月实例的
    ExpirationTime
    ，避免服务中断
  6. 生产环境开启SSL，确保连接安全

Reference Links

参考链接

ReferenceDescription
references/cli-installation-guide.mdAliyun CLI installation guide
references/ram-policies.mdRequired RAM permissions
references/related-commands.mdComplete CLI commands reference
references/verification-method.mdSuccess verification steps
Hologres API DocumentationOfficial API documentation
参考文档描述
references/cli-installation-guide.mdAliyun CLI安装指南
references/ram-policies.md所需RAM权限说明
references/related-commands.md完整CLI命令参考
references/verification-method.md成功验证步骤
Hologres API文档官方API文档

Error Handling

错误处理

HTTP StatusError CodeError MessageResolution
403NoPermissionRAM user permission is insufficientGrant 
AliyunHologresReadOnlyAccess
permission
400InvalidParameterInvalid parameter valueCheck parameter format and constraints
404InstanceNotFoundInstance does not existVerify instance ID is correct
For more error codes, see Hologres Error Center.
HTTP状态码错误码错误信息解决方案
403NoPermissionRAM用户权限不足授予
AliyunHologresReadOnlyAccess
权限
400InvalidParameter参数值无效检查参数格式和约束条件
404InstanceNotFound实例不存在核实实例ID是否正确
更多错误码请查看Hologres错误中心。