alibabacloud-solution-deploy

Alibaba Cloud ソリューションのデプロイ

ユーザーのシナリオに最適な実行パス（Terraform または CLI）を選び、タスクを最初から最後まで完了します。

基本原則

自動化を最大限に活用

10 個の手順が必要で、そのうち 9 個を自動化できるなら、9 個すべてを自動化します。本当に人間の操作が必要な 1 個の手順だけで一時停止します。CLI で実行できるクラウド操作はすべて CLI を使用してください。ユーザーがコンソールをクリックして操作しなくて済むようにすることが、ユーザーがあなたに依頼した理由です。

CLI 優先、コンソールは最後の手段

すべてのクラウド操作を、実行可能な aliyun CLI コマンドで表現してください。CLI が存在しない場合に限り、コンソールに切り替えます。その場合は、製品のホームページではなく、該当ページへの直接リンクを提示してください。https://vision.aliyun.com/facebody と https://console.aliyun.com/ の違いは、役に立つか、役に立たないかの違いです。

推測せず、まず確認

• CLI の構文：コマンドを作成する前に、aliyun <product> <command> --help を実行してください。製品によってパラメーター名は一貫しておらず、--RegionId、--region-id、--region のいずれも使用されています。
• エラー：失敗したらすぐに diagnose_cli_command.py を実行してください。Alibaba Cloud API のエラーメッセージは分かりにくいことが多いため、診断スクリプトで専用のエンドポイントを呼び出し、エラーコードに対応する修正方法を確認します。

---

ワークフロー

ステップ 0：環境を確認する

新しいセッションでは、まず次の手順を実行します。

事前確認：Aliyun CLI 3.3.1 以上が必要です

aliyun version を実行して、バージョンが 3.3.1 以上であることを確認します。未インストールの場合、またはバージョンが古い場合は、手順についてはインストールガイドを参照してください。

次に、以下のコマンドを実行して、プラグインの自動インストールを有効にし、エージェントのユーザーエージェントを設定します。

aliyun configure set --auto-plugin-install true --user-agent AlibabaCloud-Agent-Skills

これにより、製品固有の CLI プラグインが初回使用時にダウンロードされるため、手動でインストールする必要がなくなります。また、このスキルからのリクエストであることが識別されます。

次に、環境全体の確認を実行します。

bash {{SKILL_PATH}}/scripts/verify_env.sh

以下を確認します：CLI のバージョン、有効な認証情報、auto-plugin-install、Python3 と SDK。いずれかの確認に失敗した場合は、ユーザーに修正内容を伝えて停止してください。環境が壊れていると、以降のコマンドはすべて失敗します。

RAM 権限の事前確認

コマンドを実行する前に、現在のユーザーに必要な権限があることを確認します。

1. ユーザーの権限をreferences/ram-policies.mdと照合します
2. 権限が不足している場合は中止し、必要なポリシーを適用するようユーザーに求めます

必要な最小権限はreferences/ram-policies.mdに記載されています。

ステップ 1：シナリオを把握する

ユーザーのリクエストから、以下を抽出します。

• 何を構築または設定したいか
• 関連する（または推測できる）Alibaba Cloud 製品
• 主な要件：リージョン、インスタンスの仕様、予算、高可用性の要件、環境（開発／ステージング／本番）

ステップ 2 で使う検索キーワード（中国語＋英語）にまとめます。例：「我要搭个RAG知识库」→ キーワード：RAG、知识库、AnalyticDB、百炼。

ステップ 2：適切なパスに振り分ける

Alibaba Cloud の技術ソリューション 187 件を収録したマスターカタログ references/alicloud-tech-solutions-all.md を確認します。ソリューション名と説明にキーワードが一致するものを検索します。

各行には Terraform Module 名称 列があります。

• 列に値がある（例：analyticdb-rag、deepseek-personal-website）→ パス A：Terraform
• 列が空、または一致するソリューションが見つからない → パス B：CLI 優先

あいまいなキーワードからソリューションを探す場合（例：「小程序」→ develop-your-wechat-mini-program-in-10-minutes）は、intent-mapping.mdも使用します。

先に、どのパスを選ぶのか、その理由とともにユーザーに伝えてから進めます。

---

パス A：Terraform ソリューション

Terraform モジュールが一致した場合は、ローカルに terraform バイナリを用意することなく、IaCService のリモートランタイムを通じてデプロイします。

A.1: モジュールを特定する

references/tf-plan/tf-solutions.md でモジュールの名称とモジュールのアドレスを確認します。次の順に照合してください。

1. マスターカタログにあるモジュール名と完全一致するもの
2. 説明列のキーワードとの一致
3. インテントマッピング

A.2: サンプルパラメーターを取得する

各モジュールには、テスト済みのサンプルを含む GitHub リポジトリがあります。URL を導き出してください。

Module 地址: https://registry.terraform.io/modules/alibabacloud-automation/<name>/alicloud/latest
GitHub repo: https://github.com/alibabacloud-automation/terraform-alicloud-<name>
Example:     https://raw.githubusercontent.com/alibabacloud-automation/terraform-alicloud-<name>/main/examples/complete/main.tf

WebFetch でサンプルの main.tf を取得します。これらの値は実際にテスト済みのデプロイから取得したもので、汎用的なデフォルト値よりもはるかに信頼できます。

パラメーターの優先順位：

1. ユーザーが明示的に指定した値 → 常に使用
2. examples/complete/ のサンプル main.tf → デフォルト値として使用
3. フォールバックのデフォルト値（取得に失敗した場合のみ）：terraform-defaults.md を参照

A.3: ユーザーに確認する

パラメーターを提示し、確認を求めます。黙って適用してはいけません。クラウドリソースには実際に費用がかかります。

以下是基于官方示例的部署参数，请确认或修改：
• Region: cn-hangzhou
• Instance type: ecs.c7.large
• VPC CIDR: 172.16.0.0/12
• Password: (请提供)

パスワードや API キーなどの機密情報は、自分で生成してはいけません。ユーザーが提供します。

A.4: main.tf を作成してデプロイする

# Based on: https://github.com/alibabacloud-automation/terraform-alicloud-<name>/blob/main/examples/complete/main.tf
module "<module_name>" {
  source  = "alibabacloud-automation/<module_name>/alicloud"
  version = "~> 1.0"
  # Parameters adjusted per user confirmation
}

リモートランタイムを使用してデプロイします。詳しい使い方は terraform-online-runtime.md を参照してください。

SKILL_DIR="{{SKILL_PATH}}"
TF="${SKILL_DIR}/scripts/terraform_runtime_online.sh"
STATE_ID=$($TF apply main.tf | grep '^STATE_ID=' | cut -d= -f2)
echo "STATE_ID=$STATE_ID" >> terraform_state_ids.env

以降の更新や破棄には STATE_ID が必要です。これを失うと、リソースを管理できなくなります。

A.5: 検証して報告する

リソースが存在することを確認します。クリーンアップ用の破棄コマンドを提示します。

---

パス B：CLI 優先の実行

このパスでは、Terraform テンプレートを使わずにすべてを処理します。アプローチは、アーキテクチャを理解する → 手順に分解する → 各手順に対応する CLI コマンドを調べる → 実行する、です。

B.1: アーキテクチャを理解する

コマンドを書く前に、構築するものを理解してください。

• マスターカタログに一致するソリューションがあった場合（TF モジュールがないだけの場合）でも、チュートリアルリンク（デプロイチュートリアル列）があります。そのページを取得して、対象アーキテクチャ、必要な製品、デプロイの順序を確認してください。これを設計図として、各手順を CLI コマンドに置き換えます。
• ソリューションがまったく一致しない場合は、ユーザーの説明をもとに検討してください。どの製品が必要か、何が何に依存するか、最終的な状態はどうなるかを考えます。

B.2: 手順に分解する

目標を、依存関係に沿って並べた最小単位の手順に分解します。次の点を検討してください。

• リソースの作成順序：VPC → VSwitch → セキュリティグループ → ECS は、ほぼ常に基盤となります。
• ID の引き継ぎ：どの手順の出力 ID が後続の手順で必要になるか（VpcId → CreateVSwitch、VSwitchId → RunInstances）
• 非同期処理：作成呼び出しがすぐに戻っても、リソースの作成には時間がかかる場合があります。そのため、ポーリングが必要です。
• CLI がない可能性のあるもの：一部の製品の有効化や、コンソールでしか利用できない機能があります。

B.3: CLI コマンドを調べる

各手順について、スクリプトを使い、正しい API 名とパラメーターを調べてください。これは非常に重要です。記憶に頼ってはいけません。Alibaba Cloud には何千もの API があり、パラメーター名は製品によって統一されていません。

python3 {{SKILL_PATH}}/scripts/lsit_products.py '<keyword>'        # Find product code + API version
python3 {{SKILL_PATH}}/scripts/search_apis.py '<what you want to do>'  # Natural language → API
python3 {{SKILL_PATH}}/scripts/search_documents.py '<topic>'       # Parameter details, valid values, constraints
python3 {{SKILL_PATH}}/scripts/lsit_api_overview.py <Product> <version>  # Full API list for a product

複数の製品を調べる場合は、スクリプトを並行して実行してください。並行処理できるものを順番に処理しないでください。

コンソールを使わずに済む、よく使われる CLI の簡易コマンド：

シナリオ	CLI コマンド	備考
Bailian（百炼）の API キーを取得する	aliyun modelstudio list-workspaces → aliyun modelstudio create-api-key --WorkspaceId <id>	コンソールを使わずに済みます。ほぼすべての AI ソリューションで必要です。
ECS でコマンドを実行する	aliyun ecs RunCommand --Type RunShellScript --CommandContent '<script>' --InstanceId.1 <id>	ユーザーに SSH 接続を求める代わりに、Cloud Assistant を使います。
OSS 操作	aliyun ossutil cp/ls/mb ...	oss ではなく、ossutil サブコマンドを使います。

Bailian API キーの取得パターンは特に重要です。ほぼすべての AI 関連ソリューションで DashScope/Bailian SK が必要ですが、プログラムから取得できることを知らないユーザーもよくいます。計画に百炼/Bailian/DashScope が含まれる場合は、modelstudio コマンドを積極的に使ってキーを取得してください。

B.4: 計画を提示して確認を得る

書き込み操作を実行する前に、実行計画の全体を提示します。計画には、現在のアカウントに必要なすべての権限を記載した RAM 権限セクションを必ず含めてください。これにより、実行開始前にユーザーがアクセス権を確認でき、デプロイの途中で Forbidden.RAM エラーが発生するのを防げます。

計画した CLI コマンドから必要な権限を割り出します。各 aliyun <product> <API> 呼び出しは、<product>:<API> の形式の RAM アクションに対応します（例：aliyun vpc CreateVpc → vpc:CreateVpc）。

所需 RAM 权限:

| 云产品 | 所需权限 (Action) | 对应步骤 | 快捷策略 |
|--------|-------------------|----------|----------|
| VPC | vpc:CreateVpc, vpc:CreateVSwitch, vpc:DescribeVpcs | 步骤 1-2 | AliyunVPCFullAccess |
| ECS | ecs:RunInstances, ecs:DescribeInstances, ecs:RunCommand | 步骤 4-6 | AliyunECSFullAccess |
| EIP | vpc:AllocateEipAddress, vpc:AssociateEipAddress | 步骤 3 | AliyunEIPFullAccess |

提示: 可使用快捷策略快速授权，或按 Action 列配置最小权限自定义策略。

---

执行计划 (共 N 步, M 步 CLI 自动化, K 步需控制台):

步骤 1 — 创建 VPC
  aliyun vpc CreateVpc --RegionId cn-hangzhou --CidrBlock 172.16.0.0/12 --VpcName demo-vpc

步骤 2 — 创建交换机 (依赖: 步骤1 VpcId)
  aliyun vpc CreateVSwitch --RegionId cn-hangzhou --VpcId <步骤1> --ZoneId cn-hangzhou-h --CidrBlock 172.16.0.0/24

步骤 3 — [控制台] 开通视觉智能 API (无 CLI)
  打开: https://vision.aliyun.com/facebody → 点击 "立即开通"

ユーザーの承認を待ちます。クラウドリソースには費用が発生し、RDS インスタンスの削除など、一部の操作は取り消せません。

B.5: 実行

各ステップで、次の手順を実行します。

1. まず構文を確認する：aliyun <product> <api> --help — パラメーターのエラーが API に到達する前に検出します
2. コマンドを実行する
3. 結果を確認する：非同期操作をポーリングし、リソースを照会して存在を確認します
4. 出力を記録する：後続のステップと最終レポートで使う ID、エンドポイント、接続文字列を保存します

B.6: エラーへの対処

コマンドが失敗した場合：

python3 {{SKILL_PATH}}/scripts/diagnose_cli_command.py '<the full command>' '<the error message>'

診断スクリプトは、エラーコードを実行可能な修正方法に対応付ける専用 API を呼び出します。修正を適用して再試行します。修正後も同じエラーが続く場合は、診断結果を添えてユーザーに報告します。何も考えずに再試行し続けてはいけません。

失敗したステップから再開します。すでに成功したステップを再実行してはいけません。これらのリソースはすでに存在しており、再実行すると失敗する（重複する）か、不要な重複リソースが作成されます。

B.7: 報告

次の内容を要約します。

• 作成したリソース（ID を含む）
• アクセス用エンドポイント／接続文字列
• 構築したものの使用方法
• クリーンアップ用コマンド（依存関係の逆順で削除：ECS → Security Group → VSwitch → VPC）

---

スクリプトリファレンス

スクリプト	目的	例
verify_env.sh	環境の確認	bash {{SKILL_PATH}}/scripts/verify_env.sh
lsit_products.py	製品コードとバージョンの確認	python3 {{SKILL_PATH}}/scripts/lsit_products.py 'ECS'
search_apis.py	自然言語から API を検索	python3 {{SKILL_PATH}}/scripts/search_apis.py '创建ECS实例'
search_documents.py	詳細情報のドキュメント検索	python3 {{SKILL_PATH}}/scripts/search_documents.py 'ECS实例规格'
lsit_api_overview.py	製品の API 一覧	python3 {{SKILL_PATH}}/scripts/lsit_api_overview.py Ecs 2014-05-26
diagnose_cli_command.py	CLI エラーの診断	python3 {{SKILL_PATH}}/scripts/diagnose_cli_command.py '<cmd>' '<err>'
terraform_runtime_online.sh	リモート TF の実行	terraform-online-runtime.md を参照

参考資料

• 意図の対応付け — キーワードからソリューションへの対応付け
• Terraform のデフォルト設定 — デフォルトのパラメーター値
• Terraform オンラインランタイム — IaCService スクリプトの使用方法
• すべての技術ソリューションカタログ — TF Module の提供状況を含む 187 件のソリューション
• TF ソリューションの詳細 — Registry アドレスを含む 48 個の Terraform モジュール