alibabacloud-hologres-instance-manage

Hologres 实例管理

用于管理 Alibaba Cloud Hologres 实例的技能——列出所有实例并获取实例详情。

架构

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

安装

预检查：需要 Aliyun CLI >= 3.3.3

运行 aliyun version，确认版本 >= 3.3.3。如果尚未安装或版本过低， 运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行更新， 或参阅 references/cli-installation-guide.md 获取安装说明。

预检查：需要更新 Aliyun CLI 插件

[MUST] 运行 aliyun configure set --auto-plugin-install true，启用自动安装插件。 [MUST] 运行 aliyun plugin update，确保所有现有插件始终为最新版本。

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

[MUST] CLI User-Agent — 每次调用 aliyun CLI 命令时，都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage

身份验证

此技能依赖 Alibaba Cloud 默认凭证链。它绝不会读取、打印或显式处理 AK/SK 值。

安全规则：

• 绝不读取、回显或打印 AK/SK 值
• 绝不要求用户直接输入 AK/SK
• 绝不使用包含明文凭证值的 aliyun configure set
• 仅使用 aliyun configure list 验证凭证状态

aliyun configure list

检查输出，确认存在有效的配置文件（AK、STS、EcsRamRole 或 RamRoleArn）。

如果不存在有效的配置文件，请在此处停止。 用户必须在本次会话之外配置凭证，并在 aliyun configure list 显示有效配置文件后再返回。

RAM 策略

此技能需要以下 RAM 权限：

产品	RAM 操作	资源范围	描述
Hologram	hologram:ListInstances	acs:hologram:{#regionId}:{#accountId}:instance/*	列出所有 Hologres 实例
Hologram	hologram:GetInstance	acs:hologram:{#regionId}:{#accountId}:instance/{#InstanceId}	获取实例详情

完整的 RAM 策略文档请参阅 references/ram-policies.md。

[MUST] 权限失败处理： 在执行过程中，任何命令或 API 调用因权限错误而失败时，请按以下流程处理：

1. 阅读 references/ram-policies.md，获取此 SKILL 所需权限的完整列表
2. 使用 ram-permission-diagnose 技能，引导用户申请所需权限
3. 暂停操作，等待用户确认所需权限已授予

参数确认

重要：参数确认 — 执行任何命令或 API 调用之前， 必须与用户确认所有可由用户自定义的参数（例如 RegionId、实例名称、资源组 ID、 标签等）。未经用户明确同意，不得自行假定或使用默认值。

参数名称	必填/可选	描述	默认值
RegionId	可选	实例所在的地域	用户的默认地域
InstanceId	必填（用于 GetInstance）	Hologres 实例的 ID	无
resourceGroupId	可选	按资源组 ID 筛选	无
tag	可选	按标签（键值对）筛选	无
cmsInstanceType	可选	云监控实例类型（standard/follower/mc-acceleration/warehouse/high-memory/serverless）	无

核心工作流

任务 1：列出所有 Hologres 实例

查询指定地域中的所有 Hologres 实例。

# 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

响应字段：

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

任务 2：获取实例详情

获取特定 Hologres 实例的详细信息。

# 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

响应字段：

• 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/Internet/Intranet 详细信息的网络终端节点
• AutoRenewal：是否已启用自动续费
• EnableHiveAccess：是否已启用数据湖加速
• EnableServerless：是否已启用无服务器计算
• EnableSSL：是否已启用 SSL
• StorageType：存储类型（redundant/local）

成功验证方法

详细验证步骤请参阅 references/verification-method.md。

快速验证

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

成功标志：

• HTTP 状态码为 200
• Success 字段为 true
• InstanceList 或 Instance 字段包含有效数据

清理

此技能仅执行只读操作，无需清理。

命令表

完整的 CLI 命令参考请参阅 references/related-commands.md。

操作	CLI 命令	描述
列出实例	aliyun hologram POST /api/v1/instances --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage	获取所有 Hologres 实例的列表
获取实例	aliyun hologram GET /api/v1/instances/{instanceId} --read-timeout 4 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-hologres-instance-manage	获取特定实例的详情

最佳实践

1. 执行命令前始终验证凭据，使用 aliyun configure list
2. 使用筛选条件（resourceGroupId、tags）缩小实例较多时的查询结果范围
3. 检查实例状态再执行操作，确保实例处于 Running 状态
4. 使用合适的网络终端节点：内部访问选择 VPCSingleTunnel，外部访问选择 Internet
5. 监控实例到期时间：检查 PrePaid 实例的 ExpirationTime，避免服务中断
6. 在生产环境中启用 SSL，确保连接安全

参考链接

参考资料	描述
references/cli-installation-guide.md	Aliyun CLI 安装指南
references/ram-policies.md	所需的 RAM 权限
references/related-commands.md	完整的 CLI 命令参考
references/verification-method.md	成功验证步骤
Hologres API Documentation	官方 API 文档

错误处理

HTTP 状态	错误代码	错误消息	解决方法
403	NoPermission	RAM 用户权限不足	授予 AliyunHologresReadOnlyAccess 权限
400	InvalidParameter	参数值无效	检查参数格式和约束
404	InstanceNotFound	实例不存在	确认实例 ID 正确

更多错误代码请参阅 Hologres Error Center。