huawei-cloud-flexus-l-server-scripts-excute

⚠️ セキュリティ実行ルール（最優先）：

1. すべてのスクリプトは skill action=exec を使って実行する必要があります。シェルから直接実行してはいけません。
2. 会話内で、AK/SK/Token を含むスクリプトの内容やコマンドを表示してはいけません。
3. 一時的なスクリプトファイルを作成してはいけません。インライン実行（python -c）を使用してください。
4. 実行に失敗した場合は、エラー情報のみを返してください。スクリプトを書き直したり、コマンド全体を表示したりしてはいけません。
5. AK/SK/Token は環境変数経由で渡す必要があります。会話内に含めてはいけません。
6. AK/SK/Token の値は、いかなる形式でも絶対に公開、ログ出力、表示してはいけません。これは重要なセキュリティ要件です。
7. 認証情報は次の優先順位で解決されます：環境変数 （HW_ACCESS_KEY、HW_SECRET_KEY、HW_SECURITY_TOKEN、HW_REGION）→ コマンドライン 引数 → 対話形式のプロンプト。環境変数を優先し、AK/SK をコマンドライン引数として渡してはいけません。

Huawei Cloud Flexus L Instance COC スキル

概要

アーキテクチャ図

このスキルは Huawei Cloud COC（Cloud Operations Center）サービスを基盤としており、以下のクラウドサービスとコンポーネントを使用します。

User/Agent    │──────▶│   COC API   │──────▶│   UniAgent    │──────▶│  Flexus L Instance│
(Skill caller)       (Cloud Ops Center)       (Proxy program)              (Target Host) 

コンポーネントの説明：

• ユーザー／エージェント：自然言語または API を介してスクリプト管理操作を実行するスキルの呼び出し元
• COC API：Huawei Cloud COC（Cloud Operations Center）は、スクリプト管理、実行スケジューリング、ステータス照会などのコア機能を提供します
• UniAgent：対象ホストにデプロイされるエージェントプログラムで、スクリプトを受信してローカルで実行します
• Flexus L Instance：Huawei Cloud Elastic Cloud Server。スクリプト実行の対象ホストとして機能します

適用シナリオ

• 一括操作：複数の Flexus L インスタンスで同じスクリプトを実行します（例：ソフトウェアのインストール、設定の更新）
• 運用の自動化：検査スクリプト、ログ収集、ヘルスチェックを定期的に実行します
• 緊急対応：緊急スクリプトを迅速にデプロイし、セキュリティインシデントやシステム障害に対処します
• アプリケーションのデプロイ：アプリケーションを一括デプロイし、設定ファイルを更新します
• データ処理：複数のインスタンスでデータ処理タスクを並列実行します

代表的なユースケース

1. 「サーバーのログをクリーンアップする Shell スクリプトを作成する」
2. 「すべての L インスタンスでバックアップスクリプトを実行する」
3. 「最近作成したスクリプトを一覧表示する」
4. 「指定した L インスタンスで Python スクリプトを実行する」
5. 「Nginx を一括インストールするスクリプトを作成する」

トリガーキーワード

ルーティングキーワード：COC スクリプト、スクリプト管理、スクリプト実行、クラウド運用、カスタムスクリプト、一括実行；COC、スクリプト管理、スクリプト実行、クラウド運用。

重要事項

すべてのスクリプトと環境チェック用スクリプトはスキルパッケージ内にあります。実行には skill action=exec を使用する必要があります。シェルから直接実行しないでください。

前提条件

CLI のバージョン要件と確認コマンド

COC SDK のバージョン要件：huaweicloudsdkcoc >= 3.1.0

確認コマンド：

# Check current SDK version
python -c "import huaweicloudsdkcoc; print(huaweicloudsdkcoc.__version__)"

# Verify COC client availability
python -c "from huaweicloudsdkcoc.v1 import CocClient; print('COC SDK version verification passed')"

認証設定とセキュリティルール

サポートされている認証方法：

1. 認証情報の取得方法：

   このスキルでは、以下の方法で Huawei Cloud の認証情報を取得できます（優先度の高い順）：

   1. 環境変数（最優先）

      • HW_ACCESS_KEY：Huawei Cloud の Access Key AK
      • HW_SECRET_KEY：Huawei Cloud の Access Key SK
      • HW_SECURITY_TOKEN：一時認証情報用のセキュリティトークン

   2. コマンドラインパラメーター（環境変数が指定されていない場合に使用）

      • --ak：Huawei Cloud の Access Key AK
      • --sk：Huawei Cloud の Access Key SK
      • --security-token：一時認証情報用のセキュリティトークン（一時 AK/SK を使用する場合に必須）

   3. 対話形式での入力（上記の方法がどちらも指定されていない場合）

   • プログラムが AK/SK などの認証情報を入力するようユーザーに求めます

# Execute script directly (will automatically use environment variables)
python {baseDir}/scripts/caller.py create --name "test_script" --type SHELL --content "echo hello" --description "Test script"

2. 環境変数（推奨）：

export HW_ACCESS_KEY="your_access_key"
export HW_SECRET_KEY="***"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"
export HW_REGION="cn-north-4"

# Run without --ak/--sk; credentials are read from environment variables
python {baseDir}/scripts/caller.py create --name "test_script" --type SHELL --content "echo hello" --description "Test script"

⚠️ セキュリティに関する注意：コマンドラインで --ak "..." --sk "..." を渡すと、プロセス一覧（例：ps aux）に認証情報が表示されます。この方法は、信頼できる単一ユーザー環境でのみ使用してください。環境変数または hcloud configure の使用を推奨します。

3. 対話形式での入力（テスト）：

python {baseDir}/scripts/caller.py create
# Will prompt for AK/SK/region

認証パラメーターの説明：

パラメーター	説明	必須	デフォルト	例
--ak	Huawei Cloud の Access Key AK（一時 AK も使用可能）	はい*	入力を求められます	--ak AXXX...
--sk	Huawei Cloud の Access Key SK（一時 SK も使用可能）	はい*	入力を求められます	--sk SXXX...
--security-token	一時認証情報用のセキュリティトークン（一時 AK/SK を使用する場合に必須）	いいえ	入力を求められます	--security-token XXXX...
--region	COC サービスのリージョン	いいえ	cn-north-4	--region cn-north-4

注意：* 印の付いたパラメーターは、環境変数（HW_ACCESS_KEY、HW_SECRET_KEY、HW_SECURITY_TOKEN、HW_REGION）で指定できます。環境変数が設定されている場合は、コマンドラインパラメーターより優先されます。

認証の優先順位：

1. まず環境変数を確認します：HW_ACCESS_KEY、HW_SECRET_KEY、HW_SECURITY_TOKEN、HW_REGION
2. 必要な環境変数がすべて設定されている場合は、それらを直接使用します
3. 環境変数が設定されていない場合は、コマンドラインパラメーターを使用します
4. どちらも指定されていない場合は、対話形式での入力を求めます

セキュリティルール：

• 認証情報をハードコードしない：AK/SK をコードや設定ファイルに直接埋め込まないでください
• 最小権限の原則：必要最小限の権限のみを付与してください
• キーの定期的なローテーション：90 日ごとに AK/SK をローテーションしてください
• キーのローテーション通知を有効にする：Huawei Cloud Console で有効期限のリマインダーを設定してください

IAM 権限一覧

このスキルには、以下の IAM 権限が必要です。詳細については、IAM ポリシーのドキュメントを参照してください。

権限カテゴリ	権限名	説明
スクリプト管理	coc:script:create	スクリプトを作成
スクリプト管理	coc:script:list	スクリプトを一覧表示
スクリプト管理	coc:script:get	スクリプトの詳細を取得
スクリプト管理	coc:script:update	スクリプトを更新
スクリプト管理	coc:script:delete	スクリプトを削除
実行管理	coc:execution:create	実行タスクを作成
実行管理	coc:execution:list	実行タスクを一覧表示
実行管理	coc:execution:get	実行の詳細を取得
インスタンス管理	coc:instance:list	対象インスタンスを一覧表示

権限不足エラーへの対処フロー

権限不足エラーへの対処：

1. エラーの特定：

# Typical error message
error: AccessDenied
message: You do not have permission to perform this action.

2. トラブルシューティングの手順：

   • AK/SK の設定を確認します
   • ユーザーに必要な COC 権限があることを確認します
   • リージョンの設定を検証します
   • IAM ポリシーが有効かどうか確認します

3. 解決方法：

   • 必要な権限について管理者に問い合わせます
   • IAM ポリシーがユーザー／ロールに正しくアタッチされていることを確認します
   • ポリシーが反映されるまで待ちます（通常 5～10 分）

4. 確認：

# Re-execute to verify permissions
python {baseDir}/scripts/caller.py list

コアコマンド

スクリプト管理コマンド

スクリプトの作成：

# Set credentials via environment variables (recommended)
export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"
export HW_REGION="cn-north-4"

# Run without --ak/--sk; credentials are read from environment variables
python {baseDir}/scripts/caller.py create --name "backup_script" --type SHELL --content "echo 'Backup completed'" --description "Data backup script"

スクリプトの詳細表示：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"

python {baseDir}/scripts/caller.py show --script-uuid "SC202xxxxxxxx13701c4a8a62"

スクリプトの一覧表示：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"

python {baseDir}/scripts/caller.py list --page 1 --size 10

スクリプトの削除：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"

python {baseDir}/scripts/caller.py delete --script-uuid "SC202xxxxxxxx13701c4a8a62"

スクリプト実行コマンド

スクリプトの実行：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"

python {baseDir}/scripts/caller.py execute --script-uuid "SC202xxxxxxxx13701c4a8a62" --execute-user root --timeout 300

対話型実行：python {baseDir}/scripts/caller.py execute（認証情報は環境変数から読み込まれます）

実行結果の照会：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
# Optional for temporary credentials:
export HW_SECURITY_TOKEN="your_security_token"

python {baseDir}/scripts/caller.py query --execute-uuid "SCT202xxxxxxxx01af694bf"

パラメーターリファレンス

グローバルパラメーター（すべてのコマンド）

パラメーター	説明	必須	デフォルト	例
--ak	Huawei Cloud のアクセスキー AK（一時 AK も使用できます）	はい*	入力を求められます	--ak AXXX...
--sk	Huawei Cloud のアクセスキー SK（一時 SK も使用できます）	はい*	入力を求められます	--sk SXXX...
--security-token	一時認証情報用のセキュリティトークン（一時 AK/SK を使用する場合に必要です）	いいえ	入力を求められます	--security-token XXXX...
--region	COC サービスのリージョン	いいえ	cn-north-4	--region cn-north-4

注：* が付いたパラメーターは、環境変数で指定できます。

• HW_ACCESS_KEY - Huawei Cloud のアクセスキー
• HW_SECRET_KEY - Huawei Cloud のシークレットキー
• HW_SECURITY_TOKEN - 一時セキュリティトークン（任意）
• HW_REGION - COC サービスのリージョン

環境変数が設定されている場合、コマンドラインパラメーターより優先されます。

create コマンドのパラメーター

パラメーター	説明	必須	デフォルト
--name	スクリプト名	はい	-
--type	スクリプトの種類（SHELL/PYTHON/BAT）	はい	-
--content	スクリプトの内容	はい	-
--description	スクリプトの説明	はい	-
--risk-level	リスクレベル（LOW/MEDIUM/HIGH）	いいえ	LOW
--version	スクリプトのバージョン	いいえ	1.0.0

execute コマンドのパラメーター

パラメーター	説明	必須	デフォルト
--script-uuid	スクリプト UUID	いいえ	最新のスクリプト
--execute-user	実行ユーザー	いいえ	root
--timeout	タイムアウト時間（秒）（5～1800）	いいえ	300
--success-rate	成功率（0.01～100）	いいえ	1
--rotation-strategy	ローテーション戦略（CONTINUE/PAUSE）	いいえ	CONTINUE

show コマンドのパラメーター

パラメーター	説明	必須	デフォルト
--script-uuid	スクリプト UUID	はい	-

list コマンドのパラメーター

パラメーター	説明	必須	デフォルト
--page	ページ番号	いいえ	1
--size	ページサイズ	いいえ	10

delete コマンドのパラメーター

パラメーター	説明	必須	デフォルト
--script-uuid	スクリプト UUID	はい	-

query コマンドのパラメーター

パラメーター	説明	必須	デフォルト
--execute-uuid	実行タスク UUID	はい	-

SDK のインストール

スクリプトを初めて作成または実行する前に、Huawei Cloud COC SDK の依存関係がインストールされていることを確認してください。スキルディレクトリ（skills/coc）から次を実行します。

pip install -r {baseDir}/requirements.txt

インストールに関する注意事項：

• インストールには数分かかる場合があります。しばらくお待ちください
• インストールが完了すると、scripts ディレクトリ内の Python コードを呼び出して、スクリプトを作成および実行できます
• SDK のインストールには、次のミラーを使用してください（2 番目の pip ミラーを優先）：

  pip install -r {baseDir}/requirements.txt -i https://pypi.org/project/huaweicloudsdkcoc/
  

  または

  pip install -r {baseDir}/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
  

インストールの確認：

python -c "from huaweicloudsdkcoc.v1 import CocClient; print('SDK installed successfully!')"

ワークフロー

基本的なワークフロー

1. スクリプトを作成する（環境変数を使用）：

# Set environment variables first
export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
export HW_SECURITY_TOKEN="your_token"  # Optional

# Execute command (will automatically use environment variables)
python {baseDir}/scripts/caller.py create --name "test_script" --type SHELL --content "echo hello" --description "Test script"

2. スクリプトを実行する：

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"
export HW_SECURITY_TOKEN="your_token"  # Optional

python {baseDir}/scripts/caller.py execute --script-uuid "SC202xxxxxxxx13701c4a8a62" --execute-user root --timeout 300 --success-rate 100

⚠️ --ak "..." --sk "..." のコマンドライン引数で AK/SK を渡さないでください。プロセス一覧（例：ps aux）に表示されてしまいます。必ず環境変数または hcloud configure を使用してください。

ヒント：パラメーターの詳細については、「パラメーターリファレンス」セクションを参照してください。

対話モード

スクリプトの実行時に、以下の情報が対話形式で要求されます（L-instance のみ）：

必須パラメーター：

• L-instance のリソース ID（resource_id）
• L-instance のリージョン（region_id）

オプションのパラメーター（Enter キーを押すとデフォルト値が使用されます）：

• スクリプト UUID（デフォルトでは直近に作成されたスクリプトを使用）
• 実行ユーザー（デフォルトは root）
• タイムアウト（デフォルトは 300 秒）
• 成功率（デフォルトは 1）
• ローテーション戦略（デフォルトは CONTINUE）

出力形式

スクリプト一覧の出力

Found 25 scripts (Page 1, 10 per page):
--------------------------------------------------------------------------------
No.    Script UUID                    Name                 Type        Risk Level
--------------------------------------------------------------------------------
1       SC202xxxxxxxx13701c4a8a62     backup_script        SHELL       LOW
2       SC202xxxxxxxx10302201d5b9e78     deploy_script        SHELL       HIGH
3       SC202xxxxxxxx13701c4a8a62     monitor_script       PYTHON      MEDIUM
--------------------------------------------------------------------------------

JSON 出力形式

スクリプト作成成功時のレスポンス：

{
  "ok": true,
  "text": "Script created successfully: SC202xxxxxxxx13701c4a8a62",
  "result": {
    "data": "SC202xxxxxxxx13701c4a8a62"
  },
  "error": null
}

スクリプト実行成功時のレスポンス：

{
  "ok": true,
  "text": "Script execution started: SCT202xxxxxxxx01af694bf",
  "result": {
    "data": "SCT202xxxxxxxx01af694bf"
  },
  "error": null
}

実行結果のクエリに対するレスポンス：

{
  "data": {
    "batch_index": 1,
    "total_instances": 1,
    "execute_instances": [
      {
        "id": 40304358,
        "cmd_uuid": "2exxxxxxxxxxxxxx6b5",
        "job_sign": null,
        "target_instance": {
          "resource_id": "6axxxxxxxxxxxxxxx9e",
          "agent_sn": "e5xxxxxxxxxxxxxxxxxx77",
          "agent_status": null,
          "agent_version": "1.1.8",
          "region_id": "cn-north-4",
          "project_id": null,
          "properties": {
            "host_name": "dify-test-001",
            "fixed_ip": null,
            "floating_ip": null,
            "region_id": "cn-north-4",
            "zone_id": null,
            "application": null,
            "group": null,
            "project_id": null
          },
          "custom_attributes": null,
          "provider": "hcss",
          "type": "l-instance"
        },
        "gmt_created": 1779934038727,
        "gmt_finished": 1779934107670,
        "execute_costs": 68943,
        "status": "ABNORMAL",
        "message": "Reading package lists...\nWARNING: apt does not have a stable CLI interface. Use with caution in scripts.\n\n\nBuilding dependency tree...\nReading state information...\nexpect is already the newest version (5.45.4-2build1).\n\n[SYSTEM INFO] script job execute timeout."
      }
    ]
  }
}

ステータスの説明：

• FINISHED - 実行成功
• ABNORMAL - 実行失敗
• PROCESSING/READY - 実行中

検証方法

1. SDK のインストール確認

python -c "from huaweicloudsdkcoc.v1 import CocClient; print('SDK installed successfully!')"

2. スクリプトの作成確認

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"

python {baseDir}/scripts/caller.py create --name "test_script" --type SHELL --content "echo hello" --description "Test script" --non-interactive
# Expected output: Script UUID returned

3. スクリプトの実行確認

export HW_ACCESS_KEY="your_ak"
export HW_SECRET_KEY="your_sk"

python {baseDir}/scripts/caller.py execute --script-uuid "SC202xxxxxxxx13701c4a8a62" --execute-user root --timeout 300 --non-interactive
# Expected output: Execution task ID returned

4. スモークテスト

python {baseDir}/scripts/smoke_test.py
# This will test the configuration and optional API connectivity

注意事項

一般的な注意事項

• スクリプトの実行に必要なパラメーター - L-instance の resource_id と region_id を指定する必要があります
• スクリプト UUID の自動取得 - 指定されていない場合、直近に作成されたスクリプトが自動的に使用されます
• スクリプトの種類を一致させる必要があります - SHELL/PYTHON/BAT
• リスクレベルを正しく設定する必要があります - LOW/MEDIUM/HIGH
• 実行結果のポーリングが必要です - 実行 API はタスク ID を返すため、実行ステータスを別途照会する必要があります

ベストプラクティス

スクリプト管理のベストプラクティス

1. スクリプトの再利用性：設定可能なパラメーターを備えた汎用スクリプトを作成し、再利用性を最大限に高めます
2. エラー処理：スクリプトには必ずエラー処理とログ記録を含めます
3. 冪等性：安全に複数回実行できるよう、スクリプトを冪等に設計します
4. スクリプトのバージョン管理：重要なスクリプトにはバージョン管理を適用します
5. リソースのタグ付け：スクリプトには一貫した命名規則とタグを使用します

実行のベストプラクティス

1. 最初にテストする：一括実行の前に、必ず単一の L-instance でスクリプトをテストします
2. リスク評価：スクリプトに適切なリスクレベル（LOW/MEDIUM/HIGH）を設定します
3. スケジュール設定：定期的なタスクにはスケジュール実行を使用します
4. 監視：実行結果を監視し、失敗時のアラートを設定します

リージョンの概念

COC には、次の 2 種類のリージョンの概念があります。

1. COC サービスリージョン（API エンドポイントのリージョン）：

• cn-north-4（China North-Beijing-4、デフォルト）
• ap-southeast-3（APAC-Singapore）
• eu-west-101（Europe-Frankfurt）

2. ターゲットインスタンスのリージョン（L-instance が配置されているリージョン）：

• Huawei Cloud のグローバルリージョンを指定できます
• 対話形式の入力では、リージョン ID とリージョン名の両方に対応しています

重要：COC サービスリージョンとターゲットインスタンスのリージョンは異なる場合があります。

エラー処理

認証失敗（403）：

error: Authentication failed

• AK/SK が無効です。正しい認証情報を再設定してください

API クォータ超過（429）：

error: API quota exceeded

• API クォータを使い切りました。時間をおくか、アップグレードしてください

パラメーターエラー（400）：

error: Invalid parameter

• リクエストパラメーターが正しいか確認してください

セキュリティに関する注意事項

• AK/SK のセキュリティ：AK/SK は Huawei Cloud API へのアクセスに必要な重要な認証情報です。安全に保管し、他者と共有しないでください。
• 認証情報の取得：Huawei Cloud 管理コンソールにログイン → マイ認証情報 → アクセスキー → 新しいアクセスキー

参考ドキュメント

• IAM ポリシーの設定
• 検証方法
• 受け入れ基準
• プロジェクトの依存関係の設定