using-medusa-cloud

Medusa Cloud リソースの管理

mcloud CLI を使用して Medusa Cloud インフラストラクチャを管理する AI エージェント向けの運用ガイドです。セットアップ、デプロイ、デバッグ、環境、変数について説明します。

制約事項

• CLI の出力を解析する場合は、必ず --json を渡してください。プレーンテキストの出力は人間向けであり、予告なく変更される場合があります。
• 変更を加える前に、コンテキストを確認してください。状態を変更する前に mcloud whoami --json を実行してください。
• 書き込む前に読み取ってください。delete、redeploy、trigger-build の前に get または list を実行してください。
• 破壊的な操作には --yes を使用してください。非対話モードでは、delete コマンド（variables delete を含む）に --yes が必要です。
• 変数の変更を適用するにはデプロイが必要です。variables set／delete は再ビルドも再デプロイも行いません。ランタイムの変更には redeploy、ビルドの変更には trigger-build を使用してください。
• 本番環境は削除できません。仕様上、mcloud environments delete は本番環境に対してエラーになります。
• ユーザーから明示的に求められない限り、--reveal は渡さないでください。シークレットの値がターミナルのスクロールバックやログに表示されます。
• --json と --follow は併用できません。プログラムでログを取り込む場合は、--json と期間を限定する --from／--to を使用してください。

重要：必要に応じてリファレンスファイルを読み込む

作業内容に応じて、以下のリファレンスを読み込んでください。

• CLI をセットアップする場合 → まず setup.md を必ず読み込んでください
• 失敗したデプロイをデバッグする場合 → まず debugging-deployments.md を必ず読み込んでください
• 環境または変数を管理する場合 → まず environments-and-variables.md を必ず読み込んでください

最低要件： 複数ステップのワークフローを実行する前に、少なくとも 1 つのリファレンスファイルを読み込んでください。

クイックリファレンス

認証の確認

状態を変更する前に、必ず認証とスコープを確認してください。

mcloud whoami --json | jq -e '.auth.kind != "none" and .organization.id != null'

終了コード 0 = 認証済みで、スコープが設定されています。0 以外の場合は処理を中止し、ユーザーに確認してください。

コンテキストを一度だけ設定

mcloud use \
  --organization org_123 \
  --project proj_123 \
  --environment production

重要： フラグなしの mcloud use は対話型であり、CI／Docker／パイプ入力では失敗します。必ずフラグを渡してください。

デプロイステータスに応じた対応

backend_status（または storefront_status）に基づいて対応を振り分けます。

ステータス	意味	確認するログ
build-failed	ビルドステップが失敗しました	mcloud deployments build-logs <id>
deployment-failed	ビルド後にランタイムがクラッシュしました	mcloud logs --deployment <id>
timed-out	制限時間を超過しました	両方：まず build-logs、その後ランタイムログ

再デプロイの判断

コマンド	使用する状況
mcloud environments redeploy <env>	修正箇所が環境側（変数の変更、インフラストラクチャ）の場合 — 既存のビルドを再実行します
mcloud environments trigger-build <env>	修正箇所が追跡対象ブランチのソースコードの場合 — 新しいビルドを開始します

よくある落とし穴

• TTY が必要なコマンド。 mcloud login、（フラグなしの）mcloud use、および --yes なしの delete には TTY が必要です。CI、Docker、パイプ入力では失敗します。
• MCLOUD_TOKEN の優先順位。 設定されている場合、ファイルベースの認証情報は無視され、mcloud login は拒否されます。アカウントを切り替えるには、これを unset してください。
• 個人用と組織用のアクセスキー。 個人用キーには --organization が必要です。組織用キーにはあらかじめスコープが設定されています。
• organizations list には個人用の認証が必要です。 組織用アクセスキーでこのコマンドを実行すると 401 が返されます。
• ビルド ID とデプロイ ID。 depl_* はデプロイ ID、それ以外はビルド ID（最新のデプロイに解決されます）です。mcloud logs --deployment は両方を受け付けますが、その他のコマンドが受け付けるのはビルド ID のみです。
• mcloud local build には --json がありません。 プレーンテキストをストリーミングし、終了コード（0 = 成功）で成功を示します。Docker が必要で、プロジェクトの Git リポジトリ内で実行する必要があります。build-failed の失敗をローカルで再現するには、これを使用してください。debugging-deployments.md を参照してください。

リファレンスファイル

setup.md                       - CLI installation, authentication, context setup
debugging-deployments.md       - Build/deployment failure recipes and log analysis
environments-and-variables.md  - Environment lifecycle and variable management