azd-deployment

Azure Developer CLI (azd) による Container Apps へのデプロイ

リモートビルド、マネージド ID、冪等なインフラストラクチャを使用して、コンテナー化されたフロントエンドとバックエンドのアプリケーションを Azure Container Apps にデプロイします。

承認と準備

既存のプロジェクトファイルと、現在のテナント、サブスクリプション、環境を先に確認してください。プロビジョニング、デプロイ、ロールの割り当て、フックの実行はクラウドリソースを変更し、費用が発生する場合があります。正確な差分、対象、影響の見積もり、ロールバック計画を準備し、ユーザーがそのデプロイを明示的に承認した場合にのみ実行してください。共有ログに環境変数の値や認証情報を出力しないでください。

クイックスタート

# Initialize and deploy
azd auth login
azd init                    # Creates azure.yaml and .azure/ folder
azd env new <env-name>      # Create environment (dev, staging, prod)
azd up                      # Provision infra + build + deploy

コアとなるファイル構成

project/
├── azure.yaml              # azd service definitions + hooks
├── infra/
│   ├── main.bicep          # Root infrastructure module
│   ├── main.parameters.json # Parameter injection from env vars
│   └── modules/
│       ├── container-apps-environment.bicep
│       └── container-app.bicep
├── .azure/
│   ├── config.json         # Default environment pointer
│   └── <env-name>/
│       ├── .env            # Environment-specific values (azd-managed)
│       └── config.json     # Environment metadata
└── src/
    ├── frontend/Dockerfile
    └── backend/Dockerfile

azure.yaml の構成

最小構成

name: azd-deployment
services:
  backend:
    project: ./src/backend
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      remoteBuild: true

フックを含む完全な構成

name: azd-deployment
metadata:
  template: [email protected]

infra:
  provider: bicep
  path: ./infra

azure:
  location: eastus2

services:
  frontend:
    project: ./src/frontend
    language: ts
    host: containerapp
    docker:
      path: ./Dockerfile
      context: .
      remoteBuild: true

  backend:
    project: ./src/backend
    language: python
    host: containerapp
    docker:
      path: ./Dockerfile
      context: .
      remoteBuild: true

hooks:
  preprovision:
    shell: sh
    run: |
      echo "Before provisioning..."
      
  postprovision:
    shell: sh
    run: |
      echo "After provisioning - set up RBAC, etc."
      
  postdeploy:
    shell: sh
    run: |
      echo "Frontend: ${SERVICE_FRONTEND_URI}"
      echo "Backend: ${SERVICE_BACKEND_URI}"

azure.yaml の主なオプション

オプション	説明
remoteBuild: true	Azure Container Registry でイメージをビルドします（推奨）
context: .	プロジェクトパスを基準とした Docker ビルドコンテキスト
host: containerapp	Azure Container Apps にデプロイします
infra.provider: bicep	インフラストラクチャに Bicep を使用します

環境変数の流れ

3 段階の構成

1. ローカルの .env - ローカル開発専用
2. .azure/<env>/.env - azd が管理し、Bicep の出力から自動入力されます
3. main.parameters.json - 環境変数を Bicep パラメーターにマッピングします

パラメーターの注入パターン

// infra/main.parameters.json
{
  "parameters": {
    "environmentName": { "value": "${AZURE_ENV_NAME}" },
    "location": { "value": "${AZURE_LOCATION=eastus2}" },
    "azureOpenAiEndpoint": { "value": "${AZURE_OPENAI_ENDPOINT}" }
  }
}

構文：${VAR_NAME} または ${VAR_NAME=default_value}

環境変数の設定

# Set for current environment
azd env set AZURE_OPENAI_ENDPOINT "https://my-openai.openai.azure.com"
azd env set AZURE_SEARCH_ENDPOINT "https://my-search.search.windows.net"

# Set during init
azd env new prod
azd env set AZURE_OPENAI_ENDPOINT "..." 

Bicep の出力 → 環境変数

// In main.bicep - outputs auto-populate .azure/<env>/.env
output SERVICE_FRONTEND_URI string = frontend.outputs.uri
output SERVICE_BACKEND_URI string = backend.outputs.uri
output BACKEND_PRINCIPAL_ID string = backend.outputs.principalId

デプロイの再現性

調整とリビジョンの変更

1. Bicep は宣言型です - リソースは望ましい状態に調整されます
2. リモートビルドでは一意のタグが付与されます - イメージタグにはデプロイのタイムスタンプが含まれます
3. ACR はレイヤーを再利用します - 変更されたレイヤーのみがアップロードされます

管理対象外の変更を意図的に保持する

デプロイを準備する前に、カスタムドメイン、イングレス、ロールの割り当て、その他の Portal で管理されている設定を確認してください。必要な設定をレビュー済みのインフラストラクチャコードに移すか、具体的な復元計画を準備してください。プロパティを null に設定しても、Azure がポータル外で行われた編集を保持するとは限りません。デプロイを繰り返すと新しいイメージリビジョンが作成され、フックが再実行されることがあります。すべてのフックが冪等であると断言せず、こうした影響を確認してください。

既存のコンテナーレジストリを外部管理のまま維持する場合は、プロジェクトの Bicep で明示的に参照してください。デプロイを成功させるために、不完全なモジュールをコピーしたり、無関係な設定を上書きしたりしないでください。

Container App のサービス検出

同じ環境内にある Container Apps 間の内部 HTTP ルーティング：

// Backend reference in frontend env vars
env: [
  {
    name: 'BACKEND_URL'
    value: 'http://ca-backend-${resourceToken}'  // Internal DNS
  }
]

フロントエンドのプロキシは、検証済みのバックエンド内部ホスト名、スキーム、ポートを使用して構成してください。例示用 Bicep の resourceToken がプロジェクトに存在すると決めつけたり、宣言されていない nginx の $BACKEND_URL 変数をコピーしたりしないでください。テンプレートを使用する場合は、デプロイ前にレンダリング後の nginx 構成を検証してください。

# Schematic: replace this host with the approved internal endpoint.
location /api {
    proxy_pass http://approved-internal-backend;
}

マネージド ID と RBAC

システム割り当て ID を有効にする

resource containerApp 'Microsoft.App/containerApps@2024-03-01' = {
  identity: {
    type: 'SystemAssigned'
  }
}

output principalId string = containerApp.identity.principalId

プロビジョニング後の RBAC 割り当て

hooks:
  postprovision:
    shell: sh
    run: |
      set -eu
      : "${BACKEND_PRINCIPAL_ID:?Set the reviewed backend principal ID}"
      : "${OPENAI_RESOURCE_ID:?Set the approved OpenAI resource scope}"
      : "${SEARCH_RESOURCE_ID:?Set the approved Search resource scope}"
      PRINCIPAL_ID="${BACKEND_PRINCIPAL_ID}"
      
      # Azure OpenAI access
      az role assignment create \
        --assignee-object-id "$PRINCIPAL_ID" \
        --assignee-principal-type ServicePrincipal \
        --role "Cognitive Services OpenAI User" \
        --scope "$OPENAI_RESOURCE_ID"
      
      # Azure AI Search access
      az role assignment create \
        --assignee-object-id "$PRINCIPAL_ID" \
        --role "Search Index Data Reader" \
        --scope "$SEARCH_RESOURCE_ID"

よく使うコマンド

# Environment management
azd env list                        # List environments
azd env select <name>               # Switch environment
azd show                            # Inspect project/resource information
azd env set KEY value               # Set variable

# Deployment
azd up                              # Full provision + deploy
azd provision                       # Infrastructure only
azd deploy                          # Code deployment only
azd deploy --service backend        # Deploy single service

# Debugging
azd show                            # Show project status
az containerapp logs show -n <app> -g <rg> --follow  # Stream logs

デプロイ後の検証

デプロイコマンドの終了コードだけで完了を報告しないでください。許可された対象範囲内で、次のことを行います。

1. azd show を確認し、実際の環境、リソース ID、サービスエンドポイントを承認済みの計画と照合します。
2. インストール済みの Azure CLI がサポートする読み取り専用コマンドを使って、アクティブな Container Apps リビジョン、イメージのアーキテクチャ、イングレス、準備状態を確認します。確認したリビジョンと正常性の状態を記録し、新しいリビジョンにトラフィックが流れていると決めつけないでください。
3. プロジェクト所有のスモークテストを、明示的に承認されたエンドポイントに対して実行します。料金が発生する取引、メッセージの送信、実際の顧客データの公開を行わずに、フロントエンドとバックエンドの連携および ID ベースのアクセスを検証します。
4. 必要なロール割り当てが、正確なリソーススコープに設定されていることを確認します。権限チェックに失敗した場合は失敗として扱い、自動的により広範なロールを追加する理由にしてはいけません。
5. 範囲を限定し、機密情報を伏せたサービスログを確認し、カスタムドメインやその他の保持対象設定をデプロイ前のインベントリと照合します。
6. チェックに失敗した場合は、それ以上のロールアウトを中止し、失敗した観測結果を報告して、レビュー済みのロールバック計画を使用します。自動ロールバックとして破壊的なクリーンアップを実行したり、リソースを削除したりしないでください。

デプロイ先、イメージ／リビジョンの識別情報、実際に実施したチェック、失敗した項目、未検証の領域を記録します。プロバイダーへのアクセスがない場合、検証は未完了です。上記のフック例では、リソース ID を明示的に定義する必要があり、定義されていない場合はロールを変更する前に失敗します。

ローカルリソース

追加の Bicep パターン、トラブルシューティングガイド、スキーマファイルは同梱されていません。デプロイの準備を行う前に、インストール済みの Azure Developer CLI および最新の公式 Azure ドキュメントに照らして、プロジェクト構成を検証してください。

重要な注意事項

1. ビルドアーキテクチャを検証する - リモートビルドを使用するか、ローカルのターゲットアーキテクチャを明示的に設定してください。ARM イメージは AMD64 のデプロイに適合しない場合があります。
2. Bicep の出力は .azure//.env に自動入力される - 手動で編集しないでください
3. シークレットを保護する - プロジェクトで承認されたシークレット管理方法を使用し、認証情報のコミット、環境値のダンプ、パラメータのデフォルト値へのシークレットの記載は絶対に行わないでください。
4. サービスのタグ（azd-service-name） - azd が Container Apps を検出するために必要です
5. RBAC の失敗を明示的に処理する - 重複を成功として扱う前に既存の割り当てを確認し、権限または構成の失敗を決して抑制しないでください。

使用する場面

インフラストラクチャ、ビルドアーキテクチャ、マネージド ID、許可されたデプロイ、デプロイ後の検証を確認する際に、Azure Container Apps を対象とする既存の azd プロジェクトで使用します。

制限事項

• 例を使用するには、プロジェクト所有のモジュール、リソース ID、インストール済み CLI バージョンが必要です。アプリケーションやインフラストラクチャの完全なテンプレートは同梱されていません。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、成功基準が不足している場合は、中止して説明を求めてください。

公式コマンドリファレンス

インストール済みのツールバージョンについては、Azure Developer CLI リファレンスおよびContainer Apps ワークフローガイドを確認してください。これらのリンクは API／コマンドの検証に役立つものであり、ツールのインストールやリソースのデプロイを許可するものではありません。