huawei-cloud-cli-guidance

huawei cloud cli 指南

概述

华为云 KooCLI 命令行工具指南，提供全面的 KooCLI 使用说明。本指南涵盖 KooCLI 安装、身份验证配置、命令构建、常见错误排查等核心功能，帮助用户高效管理华为云资源。

注意事项

1. 使用 koocli 过程中遇到的任何问题，都必须优先按照本技能提供的指导步骤处理。[MUST][IMPORTANT]
2. 必须完整阅读本文档，并在操作过程中充分利用其中的指导。[MUST][IMPORTANT]

前提条件

• KooCLI 版本：7.2.2 或更高版本
• 华为云账号：有效的华为云账号及相应的访问权限
• 身份验证凭据：访问密钥（AK）和秘密访问密钥（SK），或 IAM 用户凭据
• 网络连接：能够访问华为云服务终端节点
• 操作系统：Linux、macOS 或 Windows（支持 WSL）

KooCLI 命令格式标准

华为云 KooCLI 采用统一的命令格式：

hcloud <service> <operation> [parameters] [options]

命令结构

• hcloud：命令行工具名称
• <service>：云服务名称（例如，ECS、VPC、OBS 等）
• <operation>：API 操作名称（例如，ListInstances、CreateVpc 等）
• [parameters]：操作参数（例如，instance_id、vpc_name 等）
• [options]：全局选项（例如，--cli-region、--cli-output 等）

参数格式规则

1. 必需参数：在命令中直接指定，例如，--instance_id i-12345678
2. 可选参数：用方括号表示，例如，[--description "instance description"]
3. 身份验证参数：使用 --cli- 前缀，例如，--cli-profile、--cli-region
4. 输出参数：使用 --cli-output 指定输出格式（json/table/tsv）
5. 查询参数：使用 --cli-query 进行 JMESPath 查询筛选

场景路由

安装场景

1. 用户询问 KooCLI 安装 → 跳转到“1. 安装 KooCLI”
2. 用户需要验证安装情况 → 检查版本命令 hcloud version

身份验证场景

1. 用户需要配置身份验证 → 跳转到“2. 配置 koocli”
2. 用户询问不同的身份验证模式 → 根据需求选择 Profile 模式、显式参数模式等

命令执行场景

1. 用户需要执行特定操作 → 引导其使用 hcloud <service> --help 查询可用操作
2. 用户遇到错误 → 跳转到“8. 常见问题”进行排查

输出格式场景

1. 用户需要特定格式的输出 → 使用 --cli-output=json/table/tsv
2. 用户需要筛选结果 → 使用 --cli-query 进行 JMESPath 查询

核心命令

请参阅 '../references/core-commands.md'

架构：

Cloud Service OpenAPI
    |
    | ECS API / VPC API / RDS API / OBS API / IAM API ...
    v
Service Metadata JSON API Definition
    |
    | Description:
    | - Service name
    | - API version
    | - Request method GET / POST / PUT / DELETE...
    | - URI path
    | - Request parameters
    | - Response structure
    | - Authentication method
    | - Region and Endpoint
    v
KooCLI Core
    |
    | Read metadata
    | Generate commands
    | Validate parameters
    | Assemble HTTP requests
    | Signature authentication
    | Call OpenAPI
    v
Dynamically Generated Commands
    |
    | hcloud <service name> <API operation name> [parameters]
    v
Unified Execution Engine
    |
    | Execute requests
    | Return results
    v
Huawei Cloud Resource Operation Results

了解 KooCLI 管理华为云资源的逻辑和流程。每次调用华为云服务或在过程中遇到问题时，都必须再次参阅并理解架构，明确当前步骤和后续步骤。[必需]

适用场景

1. 安装 koocli
2. 配置 IAM、AK、SK、区域、Profile
3. 管理华为云资源

1. 安装 KooCLI

1. 检查本地版本

hcloud version

预期输出：当前 KooCLI 版本：7.2.2 或更高版本。

2. 一键安装（如果本地版本检查通过，则跳过此步骤）

# Universal for all platforms
curl -sSL https://cn-north-4-hdn-koocli.obs.cn-north-4.myhuaweicloud.com/cli/latest/hcloud_install.sh -o ./hcloud_install.sh && bash ./hcloud_install.sh

# Non-interactive installation
curl -sSL https://cn-north-4-hdn-koocli.obs.cn-north-4.myhuaweicloud.com/cli/latest/hcloud_install.sh -o ./hcloud_install.sh && bash ./hcloud_install.sh -y

安装完成后，检查本地是否安装成功。

重要：禁止执行其他操作！！！任何文件内容变更都必须获得用户许可。

如需更详细的安装指南，请参阅 ./references/installation-guide.md

2. 配置 koocli

凭据配置

koocli 下载完成后，询问用户希望以哪种方式使用 koocli [必需]

1. koocli 提供无需配置的使用方式，只需在命令中直接传入当前用户身份验证相关参数。

2. 如果用户选择以非交互方式添加配置项，请执行 hcloud configure init，并引导用户输入每个参数值。

使用 koocli 管理华为云资源时，如果需要其他权限，请参阅 '../references/iam-policies.md'

3. ecsAgency

用户成功建立对弹性云服务器（ECS）的委托后，在 ECS 服务器内使用 KooCLI 时，可以在命令中指定 "--cli-mode=ecsAgency"。KooCLI 会根据 ECS 委托自动获取用于身份验证的临时 AK/SK 和 SecurityToken。

4. AssumeRole

委托方用户创建委托并将资源交由另一个账号管理时，受托方可以在命令中添加 "--cli-agency-domain-id"/"--cli-agency-domain-name"、"--cli-agency-name" 和 "--cli-source-profile" 选项，以无需配置的方式 AssumeRole 并调用云服务 API，从而管理和使用委托方的资源：

hcloud VPC ListAddressGroup/v3 --cli-region="cn-north-4" --project_id="2cc60****************caefa5019ef" --cli-agency-domain-id=13534326******************5cf67b --cli-agency-name=****** --cli-source-profile=test
{
  "request_id": "29ec21****************6d6b4cdd82",
  "address_groups": [],
  "page_info": {
  "current_count": 0
   }
}

5. SSO 登录

KooCLI 的 SSO 登录命令会通过完成 SSO 登录，将用户身份验证信息保存到配置文件中，避免在执行操作时频繁输入这些固定信息。可以使用以下命令进行 SSO 登录： hcloud configure sso

# SSO profile name (configuration item name to save after SSO login, required), SSO start URL (user portal URL, required), SSO region (region where IAM Identity Center is opened, required), Region (default or commonly used region, optional)
hcloud configure sso
? Input SSO profile name [required]:  sso
? Input SSO start URL [required]:  https://idcenter.huaweicloud.com/d-3********6/portal
? Input SSO region [required]:  cn-north-4
? Input Region:  cn-north-4
Browser page has been opened, waiting for you to complete SSO login...
? Choose account name: ACCOUNT_01
? Choose permission set name: PERMISSION_01
SSO login successful

6. 身份验证模式

KooCLI 配置项的身份验证模式值为 AKSK、ecsAgency、SSO、AssumeRole。建议使用 AKSK。当正在使用的配置项同时配置了多个与身份验证模式相关的参数时，使用 "--cli-mode" 选项指定该配置项的身份验证模式：

设置配置项时，需要使用 "--cli-profile" 指定配置项名称，并根据身份验证模式 "--cli-mode" 添加相应的身份验证参数：

如果配置项的身份验证模式为 "AKSK"，则配置命令中的 "--cli-access-key" 和 "--cli-secret-key" 的值不能为空；
如果配置项的身份验证模式为 "ecsAgency"，则在配置命令中指定 "--cli-mode=ecsAgency"；
如果配置项的身份验证模式为 "SSO"，则配置命令中的 "--cli-sso-start-url" 和 "--cli-sso-region" 的值不能为空；
如果配置项的身份验证模式为 "AssumeRole"，则配置命令中的 "--cli-agency-domain-id"/"--cli-agency-domain-name"、"--cli-agency-name" 和 "--cli-source-profile" 的值不能为空。

7. 身份验证模式选择

只能使用一种身份验证方式：

模式	适用场景	启动命令	清理
配置文件模式	Agent 会话、多次调用	hcloud configure init --cli-profile agent-profile	需要清理临时配置文件
显式参数模式	一次性命令、CI/CD	在每条命令中传入身份验证参数	无本地配置
现有配置文件模式	用户已完成配置	--cli-profile <profile-name>	不要修改配置

配置文件模式配置

# Create dedicated profile
hcloud configure init --cli-profile agent-profile

# View configuration
hcloud configure list

# Execute commands using profile
hcloud <service> <operation> \
  --cli-profile agent-profile \
  --cli-region cn-north-4 \
  --cli-output=json

显式参数模式

# Using permanent AK/SK
hcloud <service> <operation> \
  --cli-access-key <AccessKeyId> \
  --cli-secret-key <SecretAccessKey> \
  --cli-region cn-north-4

# Using temporary credentials
hcloud <service> <operation> \
  --cli-access-key <AccessKeyId> \
  --cli-secret-key <SecretAccessKey> \
  --cli-security-token <SecurityToken> \
  --cli-region cn-north-4

多环境管理

为不同环境创建独立配置文件：

• dev：开发环境
• test：测试环境
• prod：生产环境

调用时明确指定：

hcloud <service> <operation> \
  --cli-profile dev \
  --cli-region cn-north-4

3. 构造任何命令之前，请先查看 --help

帮助输出是权威来源。[重要]

按以下步骤执行帮助查询：

1. 使用 hcloud --help 命令查询 KooCLI 支持的云服务列表。获取准确的云服务名称后，继续下一步。
2. 使用 hcloud <service> --help 命令查询服务的 operation 列表。了解该服务支持哪些操作，找到用户需要的操作后，继续下一步。
3. 使用 hcloud <service> <operation> --help 查询特定云服务 operation 的帮助信息。
4. 执行 API 调用命令后，将输出结果打印给用户

4. 确保服务可用

当用户询问或希望执行相应的服务管理时，还应执行上一步的帮助查询，以确保服务存在且可用。

5. OBS 使用命令

KooCLI 已集成 obsutil 工具通过命令行管理 OBS 数据的部分功能。具体功能和命令必须严格按照上述帮助输出步骤进行。
如果找不到相应操作，需要提示用户安装 obsutil 以获取完整功能，并说明原因。

*** OBS 命令说明： ***

OBS-related commands in KooCLI may exist in two forms:
1. OpenAPI style:
   hcloud OBS <operation>
2. OBS integrated commands / obsutil style:
   hcloud obs <command>
The two have different parameter systems, must check help separately before execution:
hcloud OBS --help
hcloud OBS <operation> --help
hcloud obs help
hcloud obs help <command>

6. 筛选和格式化输出

KooCLI 支持三种输出格式：json、table、tsv。默认输出格式为 json。
可以使用 "--cli-output" 参数指定上述任意一种输出格式，也可以使用带有 JMESPath 表达式的 "--cli-query" 选项，对 json 结果执行 JMESPath 查询，筛选出用户需要的信息。

参数	参数用途
cli-output	cli-o 响应数据的输出格式，可以是：json、table、tsv
cli-query	用于筛选响应数据的 cli-query JMESPath 路径
cli-output-num	cli-output-num 是否在 table 输出中打印行号。取值：true 或 false

输出格式控制

# JSON format (recommended for Agent)
hcloud <service> <operation> \
  --cli-profile agent-profile \
  --cli-region cn-north-4 \
  --cli-output=json

# Table format (suitable for manual viewing)
hcloud <service> <operation> \
  --cli-profile agent-profile \
  --cli-region cn-north-4 \
  --cli-output=table

# Text format
hcloud <service> <operation> \
  --cli-profile agent-profile \
  --cli-region cn-north-4 \
  --cli-output=text

JMESPath 筛选

使用 --cli-query 提取特定字段：

# Extract specific fields
hcloud <service> <list-operation> \
  --cli-profile agent-profile \
  --cli-region cn-north-4 \
  --cli-output=json \
  --cli-query "items[].{ID:id,Name:name,Status:status}"

# Filter specific status
hcloud <service> <list-operation> \
  --cli-profile agent-profile \
  --cli-region cn-north-4 \
  --cli-output=json \
  --cli-query "items[?status=='ACTIVE'].{ID:id,Name:name,Status:status}"

注意： JMESPath 查询字段必须根据实际 JSON 返回结构编写，不能假设所有列表接口都会返回 items。

7. 调试

排查 KooCLI 命令失败问题时，首先在具体执行命令后添加 --cli-debug=true，以查看底层请求、响应、终端节点、参数解析和身份验证相关信息。

8. 常见问题

KooCLI 将命令调用过程中遇到的错误分为五种，并在错误提示消息开头标明具体类型。各种错误的定位方法如下：

1. [NETWORK_ERROR]：通常是 HTTP 请求异常，请检查网络连接；
2. [CLI_ERROR]：通常是 KooCLI 在命令处理过程中自身发生异常导致的错误，请联系 KooCLI 值班人员寻求帮助；
3. [USE_ERROR]：通常是命令中的参数不正确导致的错误，请根据错误提示进行相应修改；
4. [OPENAPI_ERROR]：通常是调用云服务 API 时发生的错误，请联系相关云服务值班人员寻求帮助；
5. [APIE_ERROR]：通常是调用 API Explorer 获取元数据时发生的错误，请联系 API Explorer 云服务值班人员寻求帮助。

遇到错误时，根据错误类型查询帮助，并逐步与用户交互以解决问题。

9. 安全

凭证安全

1. 切勿在对话或命令中暴露 AK/SK 值（禁止使用 echo $ACCESS_KEY_ID）
2. 切勿让用户直接在对话中输入 AK/SK
3. 切勿使用 hcloud configure set 传入明文凭证
4. 仅使用 hcloud configure list 检查凭证状态
5. 云环境建议使用 IAM 用户，而非主账号
6. 对敏感操作启用 MFA（多重身份验证）

操作安全

1. 执行修改操作前必须获得用户确认（安全组规则、重启、删除等）
2. 优先使用只读 API，避免修改资源状态
3. 生产环境操作需要风险警告
4. 报告输出中绝不能出现敏感信息（AK/SK、密码等）

配置安全

• 为不同环境使用独立配置文件
• 定期轮换凭据
• 遵循最小权限原则
• 清理临时配置文件
• 加密敏感配置信息

参数验证

全局参数

参数	描述	示例
--cli-profile	配置文件名	--cli-profile dev
--cli-region	区域	--cli-region cn-north-4
--cli-output	输出格式	--cli-output=json
--cli-query	JMESPath 查询	--cli-query "items[].{ID:id,Name:name}"
--cli-debug	调试模式	--cli-debug=true

身份验证参数

身份验证模式	必需参数	可选参数
AKSK	--cli-access-key、--cli-secret-key	--cli-security-token
Profile	--cli-profile	--cli-mode、--cli-region
ECS Agency	--cli-mode=ecsAgency	--cli-region
SSO	--cli-sso-start-url、--cli-sso-region	--cli-profile、--cli-region
AssumeRole	--cli-agency-domain-id、--cli-agency-name、--cli-source-profile	--cli-region

服务专属参数

使用 hcloud <service> <operation> --help 查看特定操作的参数列表。

输出格式

KooCLI 支持三种输出格式：

JSON 格式（默认）

hcloud ECS ListInstances/v3 --cli-region=cn-north-4 --cli-output=json

适用场景：自动化脚本、API 集成、数据提取

表格格式

hcloud ECS ListInstances/v3 --cli-region=cn-north-4 --cli-output=table

适用场景：手动查看、快速浏览

TSV 格式

hcloud ECS ListInstances/v3 --cli-region=cn-north-4 --cli-output=tsv

适用场景：导入电子表格、数据处理

JMESPath 查询

hcloud ECS ListInstances/v3 --cli-region=cn-north-4 --cli-output=json --cli-query "servers[?status=='ACTIVE'].{ID:id,Name:name,Status:status}"

验证方法

安装验证

1. 版本检查：hcloud version 应返回 7.2.2 或更高版本
2. 帮助验证：hcloud --help 应显示可用的服务列表

身份验证

1. 配置文件验证：hcloud configure list 显示已配置的配置文件
2. 权限验证：hcloud IAM ListUsers/v3 --cli-profile <profile> 测试 IAM 权限

命令验证

1. 帮助验证：对每项服务执行 hcloud <service> --help，确认可用操作
2. 参数验证：使用 --cli-debug=true 查看参数解析结果
3. 响应验证：检查命令返回的 HTTP 状态码和错误消息

环境验证

1. 网络连通性：curl -s https://ecs.cn-north-4.myhuaweicloud.com 测试服务端点
2. 证书验证：确保系统时钟已同步，证书有效

最佳实践

身份验证管理

1. 使用 Profile 模式管理长期会话
2. 为不同环境（dev/test/prod）创建独立的配置文件
3. 定期轮换 AK/SK，避免长期使用同一凭据
4. 使用 IAM 用户而非主账号执行日常操作

命令构建

1. 先查询帮助：hcloud <service> --help → hcloud <service> <operation> --help
2. 使用 --cli-debug=true 进行初步命令调试
3. 逐步添加参数，避免一次性构建复杂命令
4. 使用 --cli-query 筛选和格式化输出

错误处理

1. 阅读错误类型前缀：[NETWORK_ERROR]、[CLI_ERROR]、[USE_ERROR]、[OPENAPI_ERROR]、[APIE_ERROR]
2. 对于 [NETWORK_ERROR]，检查网络连通性
3. 对于 [USE_ERROR]，验证参数格式
4. 对于 [OPENAPI_ERROR]，查看 API 文档

性能优化

1. 使用 --cli-output=json 进行自动化处理
2. 正确使用 --cli-query 以减少数据传输
3. 使用脚本代替交互式命令 执行批量操作
4. 缓存常用配置，避免重复输入

注意事项

使用限制

1. 版本兼容性：确保 KooCLI 版本与服务 API 版本兼容
2. 区域限制：某些服务仅在特定区域可用
3. API 配额：注意 API 调用频率限制
4. 网络要求：某些操作需要特定的网络环境

常见问题

1. 参数顺序：某些服务对参数顺序敏感
2. JSON 格式：复杂参数需要使用正确的 JSON 格式
3. 区域设置：忘记设置 --cli-region 会导致操作在默认区域执行
4. 输出解析：表格格式的输出可能会因终端宽度而被截断

故障排除

1. 启用调试：--cli-debug=true 会显示详细的请求信息
2. 检查日志：查看 ~/.hcloud/logs/ 中的日志文件
3. 检查版本：确保 KooCLI 版本为最新版本
4. 网络诊断：使用 curl 测试服务终端节点的可达性

参考文档

• ./references/installation-guide.md — 安装指南
• ./references/cli-troubleshooting.md — 错误排查
• ./references/common-workflows.md — 常见工作流
• ./references/parameter-format.md — 参数格式规则
• ./references/service-catalog.md — 服务目录
• ./references/iam-policies.md — IAM 策略
• ./references/acceptance-criteria.md — 验收标准
• ./references/core-commands.md — 核心命令