Terraform CI/CD Service Principal セットアップガイド
このドキュメントでは、GitHub Actions から Terraform を実行するための Service Principal をterraform/shared/で作成する方法を説明します。
概要
terraform/modules/shared/azure-terraform-ci.tf で Terraform CI/CD 実行用の Service Principal が作成されます。
作成されるリソース:
- Azure AD Application (
terraform-ci-app) - Service Principal (
terraform-ci-sp) - OIDC Federated Credentials (GitHub Actions 用)
- 必要な権限のロール割り当て
必要な権限
Service Principal には以下の権限が付与されます：
- Storage Blob Data Contributor - Terraform State Storage Account へのアクセス
- Contributor - サブスクリプションレベル（すべてのリソースの作成・管理）
- Key Vault Secrets User - Key Vault からのシークレット読み取り
セットアップ手順
1. Terraform の実行
cd terraform/environments/shared
# 初期化（初回のみ、またはプロバイダー更新時）
terraform init
# 変更内容の確認
terraform plan
# 適用
terraform apply
2. 出力値の確認
適用後、以下のコマンドで Service Principal の情報を取得：
# Client ID (GitHub SecretsのTERRAFORM_AZURE_CLIENT_ID)
terraform output -json shared_infrastructure | jq -r '.terraform_ci_service_principal_id'
# Tenant ID (GitHub SecretsのTERRAFORM_AZURE_TENANT_ID)
terraform output -json shared_infrastructure | jq -r '.azure_tenant_id'
# Subscription ID (GitHub SecretsのTERRAFORM_AZURE_SUBSCRIPTION_ID)
terraform output -json shared_infrastructure | jq -r '.azure_subscription_id'
3. GitHub Secrets への設定
取得した値を GitHub Secrets に設定：
# Client ID
CLIENT_ID=$(terraform output -json shared_infrastructure | jq -r '.terraform_ci_service_principal_id')
gh secret set TERRAFORM_AZURE_CLIENT_ID --repo GenerativeX/infra --body "$CLIENT_ID"
# Tenant ID
TENANT_ID=$(terraform output -json shared_infrastructure | jq -r '.azure_tenant_id')
gh secret set TERRAFORM_AZURE_TENANT_ID --repo GenerativeX/infra --body "$TENANT_ID"
# Subscription ID
SUBSCRIPTION_ID=$(terraform output -json shared_infrastructure | jq -r '.azure_subscription_id')
gh secret set TERRAFORM_AZURE_SUBSCRIPTION_ID --repo GenerativeX/infra --body "$SUBSCRIPTION_ID"
または、手動で GitHub の Settings → Secrets and variables → Actions から設定してください。
OIDC 認証
Service Principal はOIDC 認証を使用するように設定されています。これにより：
- パスワード不要:
AZURE_CLIENT_SECRETは不要 - より安全: シークレットの管理が不要
- 自動更新: GitHub Actions が自動的にトークンを取得
OIDC Federated Credentials
以下のリポジトリとブランチ/PR で使用可能：
GenerativeX/infraリポジトリmainブランチへの push- Pull Request
トラブルシューティング
Service Principal が作成されない
- Azure AD への書き込み権限があるか確認
terraform planでエラーがないか確認- Azure AD プロバイダーが正しく初期化されているか確認
OIDC 認証が失敗する
- Federated Credentials が正しく作成されているか確認
- GitHub リポジトリ名が正しいか確認（
GenerativeX/infra） - GitHub Actions ワークフローで
azure/login@v2アクションを使用しているか確認
権限エラーが発生する
- ロール割り当てが正しく適用されているか確認
- Storage Account へのアクセス権限を確認
- サブスクリプションレベルの Contributor 権限を確認
更新方法
Service Principal のパスワードを更新する場合：
cd terraform/environments/shared
terraform apply
パスワードは自動的に生成され、terraform_ci_service_principal_secretとして出力されます（OIDC 使用時は不要）。
セキュリティ考慮事項
- 最小権限の原則: 必要最小限の権限のみを付与
- OIDC 推奨: パスワードベースの認証ではなく OIDC を使用
- 定期的な監査: Service Principal の使用状況を定期的に確認
- 権限の見直し: 必要に応じて権限を縮小