huawei-cloud-cli-guidance

Huawei Cloud CLI の利用ガイド

概要

Huawei Cloud KooCLI コマンドラインツールの利用ガイドです。KooCLI の包括的な利用方法を説明します。このガイドでは、KooCLI のインストール、認証設定、コマンドの構築、一般的なエラーのトラブルシューティングなどの主要な機能を取り上げ、ユーザーが Huawei Cloud リソースを効率的に管理できるよう支援します。

注意事項

1. koocli の使用中に問題が発生した場合は、このスキルで提供される手順を優先して対応する必要があります。[MUST][IMPORTANT]
2. このドキュメントを最後まで読み、作業中はそのガイダンスを最大限に活用する必要があります。[MUST][IMPORTANT]

前提条件

• KooCLI のバージョン：7.2.2 以降
• Huawei Cloud アカウント：有効な Huawei Cloud アカウントと、それに対応するアクセス権限
• 認証情報：アクセスキー（AK）とシークレットキー（SK）、または IAM ユーザーの認証情報
• ネットワーク接続：Huawei Cloud サービスのエンドポイントにアクセスできること
• オペレーティングシステム：Linux、macOS、または Windows（WSL に対応）

KooCLI コマンド形式の標準

Huawei Cloud 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. Install KooCLI」に進みます
2. インストールの確認が必要な場合 → バージョン確認コマンド hcloud version を実行します

認証のシナリオ

1. 認証の設定が必要な場合 →「2. Configure koocli」に進みます
2. さまざまな認証方式について質問された場合 → 要件に応じてプロファイル方式、明示的なパラメーター方式などを選択します

コマンド実行のシナリオ

1. 特定の操作を実行する必要がある場合 → hcloud <service> --help を使用して、利用可能な操作を確認するよう案内します
2. エラーが発生した場合 →「8. Common issues」に進んでトラブルシューティングを行います

出力形式のシナリオ

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 が Huawei Cloud リソースを管理するロジックとプロセスを理解してください。Huawei Cloud サービスを呼び出すたび、または作業中に問題が発生するたびに、アーキテクチャを改めて参照して理解し、現在の手順と後続の手順を明確にする必要があります。[必須]

対応シナリオ

1. koocli をインストールする
2. IAM、AK、SK、リージョン、プロファイルを設定する
3. Huawei Cloud リソースを管理する

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 を使用して Huawei Cloud リソースを管理する際に別の権限が必要な場合は、'../references/iam-policies.md' を参照してください。

3. ecsAgency

ユーザーが Elastic Cloud Server（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. 認証モードの選択

認証方法は、いずれか1つだけを使用してください。

モード	適用シナリオ	開始コマンド	クリーンアップ
プロファイルモード	エージェントのセッション、複数回の呼び出し	hcloud configure init --cli-profile agent-profile	一時プロファイルをクリーンアップする必要があります
明示的なパラメーターモード	1回限りのコマンド、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 には、コマンドラインから OBS データを管理するための obsutil ツールの一部の機能が統合されています。具体的な機能とコマンドについては、前述のヘルプ出力の手順を厳守して参照し、それに従って実行してください。
操作が見つからない場合は、すべての機能を利用できるよう、ユーザーに 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 の 3 種類の出力形式をサポートしています。デフォルトの出力形式は json です。
「--cli-output」パラメーターを使用して、前述の出力形式を指定できます。また、「--cli-query」オプションに JMESPath 式を指定して 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 は、コマンド呼び出し中に発生したエラーを 5 種類に分類し、エラーメッセージの冒頭に該当する種類を表示します。各エラーの特定方法は以下のとおりです。

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
プロファイル	--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 は 3 つの出力形式をサポートしています。

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. 長期的なセッション管理にはプロファイルモードを使用します
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 — 基本コマンド