トラブルシューティングガイド
infra-cli の使用中に発生する可能性のある問題とその解決方法について説明します。
よくある問題
❌ Terraform 状態がロックされている
症状: Error: Error locking state: Error acquiring the state lock
原因: 別のプロセスが Terraform を実行中、前回の実行が異常終了してロックが残っている
解決方法:
infra status my-company dev # 状態を確認
infra unlock my-company dev # ロックを解除（慎重に実行）
⚠️ 注意: ロック解除前に、他のメンバーがデプロイ中でないことを確認してください。チームで作業している場合は、Slack などで確認してから実行してください。
❌ config.toml の設定が不正
症状: Error: Invalid configuration
原因: config.toml の構文エラー、必須フィールドの欠落、値の型が不正
解決方法:
infra validate my-company # 設定を検証
# エラー内容を確認して、config.tomlを修正
infra generate my-company dev --force # 再生成
よくある設定エラー: name に大文字や特殊文字を使用している、template に存在しないテンプレート名を指定している、min_replicas が max_replicas より大きい、location に無効なリージョン名を指定している
❌ デプロイが失敗した
症状: Error: Error applying plan
原因: Azure リソースの制限に到達、権限不足、リソース名の競合、ネットワーク設定の問題
解決方法:
# 1. 状態を確認
infra status my-company dev
# 2. プランを再確認
infra plan my-company dev
# 3. Azure Portalでリソースグループを確認
# rg-my-company-dev が正常か確認
# 4. 必要に応じてTerraform状態を手動確認
cd terraform/environments/tenants/my-company/dev
terraform show
# 5. 詳細ログを確認
export TF_LOG=DEBUG
infra plan my-company dev
Azure Portal での確認項目:
- サブスクリプションが正しいか
- リソースグループが存在するか
- リソース制限に到達していないか
- デプロイエラーの詳細を確認
❌ グローバルインストールが動かない
症状:
command not found: infra
原因:
- グローバルインストールが正しく行われていない
- PATH が正しく設定されていない
解決方法:
# アンインストールしてから再インストール
yarn uninstall:global
yarn build
yarn install:global
# PATHを確認
which infra
# 実行可能か確認
infra --version
それでも動かない場合:
# Yarnのグローバルディレクトリを確認
yarn global bin
# PATHに追加（~/.zshrc または ~/.bashrc に追記）
export PATH="$(yarn global bin):$PATH"
# シェルをリロード
source ~/.zshrc # または source ~/.bashrc
Terraform 関連
Terraform State が見つからない
症状:
Error: Failed to get existing workspaces
原因:
- Azure Storage Account のバックエンド設定が不正
- サブスクリプションが間違っている
解決方法:
# 正しいサブスクリプションに切り替え
az account set --subscription e3143cb2-4707-4614-bbba-3ddeb66669c2
# サブスクリプションを確認
az account show
# Terraformファイルを再生成
infra generate my-company dev --force
# 初期化
cd terraform/environments/tenants/my-company/dev
terraform init
Terraform プランが想定と異なる
症状:
- 予期しないリソースが削除される
- 予期しないリソースが作成される
解決方法:
# 1. config.tomlを確認
vim terraform/environments/tenants/my-company/config.toml
# 2. 環境変数を確認
infra decrypt my-company
vim terraform/environments/tenants/my-company/.env.frontend.dev
# 3. Terraformファイルを再生成
infra encrypt my-company
infra generate my-company dev --force
# 4. プランを再確認
infra plan my-company dev
Azure 認証関連
Azure ログインエラー
症状:
Error: Azure CLI authentication failed
解決方法:
# Azure再認証
az login
# Subscriptionを確認・切り替え
az account show
az account set --subscription "e3143cb2-4707-4614-bbba-3ddeb66669c2"
# 認証情報をクリア（必要に応じて）
az account clear
az login
サブスクリプションへのアクセス権限がない
症状:
Error: Authorization failed
原因:
- Azure サブスクリプションへのアクセス権限がない
解決方法:
- Azure Portal で権限を確認
- サブスクリプション管理者に権限付与を依頼
- 正しいアカウントでログインしているか確認
# 現在のアカウントを確認
az account show
# 別のアカウントでログイン
az login --tenant generativex.onmicrosoft.com
環境変数関連
暗号化された環境変数が復号化できない
症状:
Error: Failed to decrypt environment variables
原因:
- 暗号化キーが間違っている
- ファイルが破損している
解決方法:
# 1. 環境変数ファイルを手動で確認
ls -la terraform/environments/tenants/my-company/encrypted/
# 2. 暗号化ファイルを削除して再作成
rm terraform/environments/tenants/my-company/encrypted/*.env.*
# 3. 環境変数ファイルを再編集
cd terraform/environments/tenants/my-company
vim .env.frontend.dev
vim .env.backend.dev
# 4. 再暗号化
cd ../../../../
infra encrypt my-company
環境変数が Container Apps に反映されない
症状:
- デプロイ後も古い環境変数が使われている
原因:
- Container Apps が環境変数を再読み込みしていない
- デプロイが正しく実行されていない
解決方法:
# 1. 環境変数を更新
infra decrypt my-company
# .env.* を編集
infra encrypt my-company
# 2. Terraformファイルを再生成
infra generate my-company dev --force
# 3. 変更を確認
infra plan my-company dev
# 4. デプロイ
infra apply my-company dev
# 5. Azure Portalで環境変数を確認
# Container Apps → Configuration → Environment variables
Azure Portal での手動確認:
- Azure Portal を開く
- Container Apps を選択
- Configuration → Environment variables で値を確認
- 必要に応じて手動で更新して Container Apps を再起動
デプロイメント関連
イメージが見つからない
症状:
Error: Image not found in registry
原因:
- Docker イメージが Azure Container Registry にプッシュされていない
- イメージ名またはタグが間違っている
解決方法:
# イメージ確認
az acr repository list --name gxsharedacr
az acr repository show-tags --name gxsharedacr --repository my-app-frontend
# config.tomlのイメージ名を確認
vim terraform/environments/tenants/my-company/config.toml
# 正しいイメージ名に修正
# [environments.dev.frontend]
# image_name = "my-app-frontend"
# image_tag = "latest"
# 再生成・デプロイ
infra generate my-company dev --force
infra apply my-company dev
Docker イメージのビルド・プッシュ:
# 手動でイメージをビルド・プッシュ
az acr build --file Dockerfile --registry gxsharedacr --image my-app-frontend:latest .
詳細は CI/CD の使い方 を参照。
GitHub Actions が失敗する
症状:
- GitHub Actions のワークフローが失敗する
原因:
- GitHub Secrets が設定されていない
- Service Principal の権限不足
- イメージ名が不正
解決方法:
-
GitHub Secrets を確認:
Settings → Secrets and variables → Actions
必要なシークレット:
- AZURE_CLIENT_ID
- AZURE_CLIENT_SECRET
- AZURE_TENANT_ID
- AZURE_SUBSCRIPTION_ID
- ACR_NAME -
Service Principal の権限を確認:
# Service Principalの権限確認
az role assignment list --assignee <client-id> -
イメージ名を確認:
# .github/workflows/deploy.yml
IMAGE_NAME: ${{ github.event.repository.name }}
詳細は CI/CD の使い方 を参照。
CLI ツール関連
ビルドエラー
症状:
error TS2304: Cannot find name 'xxx'
原因:
- TypeScript の型定義が不正
- 依存関係が不足している
解決方法:
# 依存関係を再インストール
rm -rf node_modules yarn.lock
yarn install
# 再ビルド
yarn build
# エラーが続く場合はキャッシュをクリア
yarn cache clean
yarn install
yarn build
依存関係のエラー
症状:
error: Cannot find module 'xxx'
解決方法:
# 依存関係を再インストール
yarn install
# グローバルインストールを更新
yarn uninstall:global
yarn build
yarn install:global
ネットワーク関連
Backend にアクセスできない
症状:
- Frontend から Backend への接続が失敗する
原因:
frontend-backendテンプレートでは Backend は内部ネットワークのみ- ネットワーク設定が不正
解決方法:
-
テンプレートを確認:
# config.tomlを確認
vim terraform/environments/tenants/my-company/config.toml
# template = "frontend-backend" の場合
# Backendは内部ネットワークのみでアクセス可能 -
Frontend の環境変数を確認:
# .env.frontend.dev を確認
infra decrypt my-company
vim terraform/environments/tenants/my-company/.env.frontend.dev
# Backend URLは内部URLを使用
# API_URL=http://backend-service.internal
詳細は アーキテクチャガイド を参照。
詳細ログ
詳細なログが必要な場合は、Terraform のデバッグモードを有効化できます:
# Terraformのデバッグモードを有効化
export TF_LOG=DEBUG
infra plan my-company dev
# ログレベルの選択肢
# - TRACE (最も詳細)
# - DEBUG
# - INFO
# - WARN
# - ERROR
# ログファイルに出力
export TF_LOG=DEBUG
export TF_LOG_PATH=./terraform-debug.log
infra plan my-company dev
FAQ
Q: どの Azure サブスクリプションを使えばいいですか？
A:
- 本番環境:
gx-prod-subscription(e3143cb2-4707-4614-bbba-3ddeb66669c2) を使用してください。必ず Terraform で管理する必要があります。 - 開発・検証環境:
gx-dev-subscription(8bebe608-cec5-41c4-9ee0-4377b03cb235) を使用できます。手動構築も可能です。
切り替え方法:
# 本番環境に切り替え
az account set --subscription e3143cb2-4707-4614-bbba-3ddeb66669c2
# 開発環境に切り替え
az account set --subscription 8bebe608-cec5-41c4-9ee0-4377b03cb235
Q: gx-prod-subscription で手動でリソースを作成してもいいですか？
A: いいえ、絶対に手動でリソースを作成しないでください。gx-prod-subscription はすべて Terraform で一元管理することが必須です。手動でリソースを作成すると、管理が混乱し、予期しない問題が発生する可能性があります。すべての変更は本リポジトリを通じて実施してください。
Q: 既存の Azure リソースをインポートできますか？
A: Terraform の terraform import コマンドを使用してインポートできます。詳細は Terraform のドキュメントを参照してください。ただし、gx-prod-subscription では手動で作成されたリソースは原則として存在しないはずです。
Q: カスタムテンプレートを作成できますか？
A: はい、terraform/modules/applications/ に新しいディレクトリを作成し、テンプレートを定義できます。詳細はコントリビューションセクションを参照してください。
Q: 本番環境のデプロイ前に確認する方法は？
A: infra plan <tenant> prd コマンドで変更内容を事前に確認できます。実際にリソースは作成されません。
# プラン確認
infra plan my-company prd
# 変更内容を確認してから
infra apply my-company prd
Q: 環境変数の暗号化は必要ですか？
A: Git に機密情報をコミットする場合は暗号化を推奨します。infra encrypt <tenant> コマンドで暗号化できます。
# 暗号化
infra encrypt my-company
# 暗号化されたファイルのみをGitにコミット
git add terraform/environments/tenants/my-company/encrypted/
git commit -m "Add encrypted environment variables"
Q: Terraform State はどこに保存されますか？
A: すべてのテナントの Terraform State は Azure Storage Account で一元管理されています。ローカル環境に .tfstate ファイルは保存されません。
Q: 複数人で同時にデプロイできますか？
A: いいえ、Terraform State のロック機能により、同時デプロイは防止されます。他の人がデプロイ中の場合は、完了を待ってから実行してください。
サポート
ドキュメント
- テナント登録 - 初めての方向けの始め方ガイド
- CLI リファレンス - 全コマンドの詳細
- アーキテクチャガイド - システム構成の詳細
- CI/CD の使い方 - GitHub Actions による CI/CD
問題報告
バグや機能要求は GitHub Issues でお願いします。