huawei-cloud-sac-new-api

Huawei Cloud NewAPI LLM ゲートウェイ

概要

Huawei Cloud 上に「NewAPI LLM ゲートウェイの構築」ソリューションをエンドツーエンドでデプロイします。このプラットフォームは、複数の大規模モデル API リクエストを一元管理して転送する、NewAPI ベースの LLM API ゲートウェイを提供し、負荷分散、キーのローテーション、使用状況の統計に対応します。

アーキテクチャ： ECS（Ubuntu 22.04）、VPC、サブネット、セキュリティグループ（SSH ポート 22 と NewAPI Web ポート 3000）、EIP、EVS（システムディスク）。Cloud-init により Docker をインストールし、NewAPI ゲートウェイコンテナーを起動します。

ツールチェーン： Playwright CLI（ソリューション情報の抽出）＋ Python 3.10 以降（ヘルパースクリプト）＋ Terraform 1.5 以降（宣言的デプロイ）。KooCLI は使用せず、すべてのリソース操作を Terraform で行います。

前提条件

• Python 3.10 以降、Playwright CLI、Terraform 1.5 以降 — CLI インストールガイドを参照してください
• 環境変数（HW_ACCESS_KEY、HW_SECRET_KEY）を使用した Huawei Cloud AK/SK。設定されていない場合は、ユーザーに terraform.auto.tfvars.json を手動で編集して AK/SK を入力するよう促してください — ⛔ 会話のコンテキストでこのファイルを読み取ったり、表示したりしないでください
• 十分な権限を持つ IAM ユーザー — IAM ポリシーを参照してください

セキュリティ

• 🚫 会話や出力に AK/SK を含めないでください
• 🚫 チャットで AK/SK を入力するようユーザーに求めないでください
• 🚫 会話のコンテキストで terraform.auto.tfvars.json を読み取ったり、表示したりしないでください（AK/SK が含まれています）
• ✅ プライマリアカウントより IAM ユーザーを優先してください
• ✅ 変更操作（apply、destroy）には、ユーザーの明示的な確認が必要です

コアコマンド

プレースホルダー値（OS ごとの解決方法については「パラメーター」を参照してください）：

プレースホルダー	Linux / macOS	Windows PowerShell	Windows CMD
<python>	python3	python	python
<script_dir>	./scripts	./scripts	scripts
<temp_dir>	/tmp	$env:TEMP	%TEMP%
<region>	cn-north-4	cn-north-4	cn-north-4
<workdir>	newapi-workdir	newapi-workdir	newapi-workdir
<solution_detail_page_url>	（下記の注意事項を参照）	（同左）	（同左）
<tf_template_url>	（下記の注意事項を参照）	（同左）	（同左）

<solution_detail_page_url> = https://www.huaweicloud.com/solution/implementations/building-a-newapi-llm-gateway.html

<tf_template_url> = https://documentation-samples.obs.cn-north-4.myhuaweicloud.com/solution-as-code-publicbucket/solution-as-code-moudle/building-a-newapi-llm-gateway/building-a-newapi-llm-gateway.tf.json

# 1. Extract solution info
<python> <script_dir>/extract_sac_deploy_info.py \
  --url "<solution_detail_page_url>" \
  --out <temp_dir>/sac_selected.json

# 2. Download and normalize template
<python> <script_dir>/download_tf_template_file.py \
  --url "<tf_template_url>" \
  --out-dir <temp_dir>/<workdir>

<python> <script_dir>/normalize_tf_providers.py <temp_dir>/<workdir> \
  --region "<region>"

# 3. List variables for review
<python> <script_dir>/list_tf_variables.py <temp_dir>/<workdir>

# 4. Deploy
terraform -chdir=<temp_dir>/<workdir> init
terraform -chdir=<temp_dir>/<workdir> plan
# ⛔ STOP — Review the plan output above. Do NOT auto-apply.
# Confirm with the user (AskUserQuestion or equivalent) before proceeding.
# Only after explicit user confirmation:
terraform -chdir=<temp_dir>/<workdir> apply

# 5. Verify
terraform -chdir=<temp_dir>/<workdir> state list
terraform -chdir=<temp_dir>/<workdir> output -json

# 6. Cleanup
terraform -chdir=<temp_dir>/<workdir> destroy
python -c "import os; f='<temp_dir>/<workdir>/terraform.auto.tfvars.json'; os.path.exists(f) and os.remove(f)"

ワークフロー

1. ソリューション情報を抽出する

コアコマンドのステップ 1 を実行した後、結果をユーザーに表示します。

• ソリューション名：出力 JSON の title フィールド
• 推定価格：estimated_price_text フィールド
• デプロイリンク：deploy_links 配列の各項目について、text と url を一覧表示します
• title または estimated_price_text が空の場合はユーザーに警告し、ソリューションページで手動確認するよう提案します

2. テンプレートをダウンロードして正規化する

normalize_tf_providers.py は、リージョンなどのパラメーターを含む terraform.auto.tfvars.json を書き込みます。環境変数 HW_ACCESS_KEY／HW_SECRET_KEY が設定されていない場合、AK/SK フィールドは空のままです。ファイルのパスをユーザーに伝え、AK/SK を入力するために手動で編集するよう促してください。⛔ 会話のコンテキストでファイルの内容を読み取ったり、表示したりしないでください。 その後、次のステップに進みます。

3. 変数を確認する

ユーザーと一緒に確認します。機密性の高い変数が空または脆弱な場合は、apply を実行しないでください。

4. デプロイする

⛔ 停止 — terraform apply を実行する前に、terraform plan の出力を確認し、ユーザーの承認を得てください（AskUserQuestion などを使用）。自動で apply を実行しないでください。ユーザーの明示的な確認を得てから続行してください。

5. 検証

検証方法と受け入れ基準を参照してください。

6. クリーンアップ

パラメーター

パラメーター	必須	デフォルト	制約
region	はい	cn-north-4	サポート対象のリージョンのみ
AK/SK	はい	—	環境変数 HW_ACCESS_KEY/HW_SECRET_KEY。設定されていない場合は、tfvars.jsonを編集するようユーザーに促します（⛔ コンテキスト内でtfvars.jsonを読み取らないでください）
ecs_password	はい	—	8～26文字。大文字、小文字、数字、記号を組み合わせます
ecs_flavor	いいえ	x1.8u.16g	ECSフレーバーID
system_disk_size	いいえ	100	40～1024 GB
bandwidth_size	いいえ	300	EIP帯域幅（Mbit/s）
charging_unit	いいえ	month	month または year
charging_period	いいえ	1	—

デプロイ後の出力

• terraform output -json — NewAPIゲートウェイURLを含む access_instructions を含みます
• NewAPI Web UI：http://<EIP>:3000（cloud-initの完了まで約10分かかります）
• 検証：ssh root@<EIP> "docker ps" でNewAPIコンテナが実行中であることを確認します

出力形式

terraform output -json は、以下の主要フィールドを含むJSONを返します。

{
  "access_instructions": { "value": "http://<EIP>:3000" },
  "ecs_eip":             { "value": "<Elastic IP>" },
  "ecs_id":              { "value": "<ECS Instance ID>" },
  "vpc_id":              { "value": "<VPC ID>" }
}

すべてのスクリプト出力はJSON形式です。extract_sac_deploy_info.py はソリューション情報のJSONを出力し、list_tf_variables.py は変数一覧のJSONを出力します。

検証

デプロイ結果を次の手順で検証します。

1. テンプレートの抽出 — <temp_dir>/sac_selected.json に solution_name と price フィールドが含まれていることを確認します
2. テンプレートのダウンロード — <temp_dir>/newapi-workdir 以下に .tf ファイルが存在し、terraform validate が成功することを確認します
3. 変数の確認 — list_tf_variables.py の出力で機密変数（AK/SK、パスワード）が空でないことを確認し、ユーザーが上書きを確認します
4. デプロイ — terraform plan にエラーがないことを確認し、ユーザーがデプロイを確認した後、apply の実行後に terraform state list ですべての想定リソースが表示されることを確認します
5. サービスへの到達性 — cloud-initの完了まで10～15分待ってから、curl -s http://<EIP>:3000 が200を返すことを確認します
6. コンテナ — ssh root@<EIP> "docker ps" でNewAPIコンテナが実行中であることを確認します

詳細は検証方法と受け入れ基準を参照してください。

ベストプラクティス

• apply の前に必ず terraform plan を実行します
• 最初は charging_unit=month を使用し、検証後に year に切り替えます
• デプロイ後、cloud-initのために10～15分待ちます
• NewAPIダッシュボードでAPIの使用状況とキーのローテーション状態を監視します

参考ドキュメント

ドキュメント	説明
CLIインストールガイド	Python、Playwright CLI、Terraformのインストール
IAMポリシー	権限、エージェンシーの設定、障害対応
検証方法	ワークフローの各手順に沿った検証
受け入れ基準	デプロイの受け入れチェックリスト全体
関連コマンド	Terraform、スクリプト、リモートアクセスのリファレンス

注意事項

• サポート対象のリージョンは cn-north-4 のみです
• terraform.auto.tfvars.json は機密情報です。VCSにコミットしないでください。会話のコンテキスト内で読み取ったり表示したりしないでください
• normalize_tf_providers.py はリージョンをtfvarsに書き込みます。環境変数が設定されていない場合、AK/SKは空のままになるため、ユーザーが手動で入力する必要があります
• ツールチェーン：Playwright CLI + Python + Terraform（KooCLIは不要）