デプロイワークフローガイド

インフラストラクチャのデプロイに使用する推奨ワークフローについて説明します。

利用可能なワークフロー

1. org-plan.yml - プラン実行（読み取り専用）

用途: デプロイ前の変更内容の確認（dry-run）

実行内容: 環境変数の差分を計算、イメージの差分を計算、plan.json を生成してアーティファクトとして保存

2. org-env-apply.yml - 環境変数の更新

用途: 環境変数のみを更新（イメージは変更しない）

実行内容: プランを実行、環境変数を Azure App Service/Container Apps に適用、マージモード（既存の環境変数を保持し、新しい環境変数のみを追加・更新）

plan_only モード: plan_only: true を設定すると、実際の適用は行わず、変更内容のみを表示

3. org-deploy.yml - フルデプロイ（完全実装済み）

実行内容: Plan（プランを実行し、変更内容を解析）、Build（イメージが変更された場合、Docker ビルド＆プッシュ）、Apply Env（環境変数を適用、マージモード）、Deploy（新しいイメージをデプロイ）

特徴: plan.json を解析して、必要なアクションのみを実行、Matrix strategy で複数サービスを並列処理、変更がない場合は自動的にスキップ

推奨される使い方

シナリオ 1: 環境変数のみを更新

.env.prod や .env.dev ファイルを更新した場合：

方法: org-env-apply.yml を使用

name: Update Environment Variables

on:
  workflow_dispatch:
    inputs:
      environment:
        type: choice
        options:
          - dev
          - prd

jobs:
  # 1. まず plan で確認
  plan:
    uses: GenerativeX/infra/.github/workflows/org-env-apply.yml@main
    with:
      environment: ${{ inputs.environment }}
      plan_only: true
    secrets: inherit

  # 2. 承認後に適用
  apply:
    needs: plan
    uses: GenerativeX/infra/.github/workflows/org-env-apply.yml@main
    with:
      environment: ${{ inputs.environment }}
      plan_only: false
    secrets: inherit

シナリオ 2: コードとイメージの更新（完全なデプロイ）

方法: org-deploy.yml を使用

name: Full Deployment

on:
  workflow_dispatch:
    inputs:
      mode:
        description: "実行モード"
        type: choice
        options:
          - plan
          - deploy
      environment:
        type: choice
        options:
          - dev
          - prd

jobs:
  plan:
    if: inputs.mode == 'plan'
    uses: GenerativeX/infra/.github/workflows/org-deploy.yml@main
    with:
      environment: ${{ inputs.environment }}
      plan_only: true
    secrets: inherit

  deploy:
    if: inputs.mode == 'deploy'
    uses: GenerativeX/infra/.github/workflows/org-deploy.yml@main
    with:
      environment: ${{ inputs.environment }}
      plan_only: false
    secrets: inherit

実行の流れ:

org-deploy.yml 内部で以下が自動的に実行されます：

1. Plan Job:

   • infra-runner で plan を実行
   • plan.json を解析して deployment matrix を生成
   • 変更があるサービスのみを抽出

2. Build Job (並列実行):

   • イメージが変更されたサービスのみ
   • docker-build-push アクションでビルド＆プッシュ

3. Apply Env Job (並列実行):

   • 環境変数が変更されたサービスのみ
   • azure-env-apply アクションで適用（マージモード）

4. Deploy Job (並列実行):

   • イメージが変更されたサービスのみ
   • azure-deploy アクションで新しいイメージをデプロイ

複数サービスがある場合、各ジョブ内で並列処理されます。

マージモードについて

デフォルトの動作（マージモード）

既存の環境変数を保持し、新しい環境変数のみを追加・更新します。

例:

• 既存: DATABASE_URL=xxx, API_KEY=yyy, DEBUG=false
• .env ファイル: DATABASE_URL=new-url, NEW_VAR=value
• 結果: DATABASE_URL=new-url (更新), API_KEY=yyy (保持), DEBUG=false (保持), NEW_VAR=value (追加)

利点

1. 安全性: Azure Portal や他の方法で手動設定した環境変数が削除されない
2. 柔軟性: 一部の環境変数のみを管理し、他は手動管理できる
3. 段階的移行: 既存の手動設定を残したまま、徐々に IaC 化できる

注意点

• 不要になった環境変数は自動的に削除されません
• 必要に応じて Azure Portal から手動で削除してください

トラブルシューティング

エラー: "Deploy mode requires workflow orchestration"

原因: infra-runner アクションを deploy モード（plan_only: false）で直接実行しようとしている

解決策:

• 環境変数のみの更新: org-env-apply.yml を使用
• フルデプロイ: Product リポジトリで独自のワークフローを実装（上記のシナリオ 2 を参照）

プランで "X removed" と表示される

原因: 古いバージョンの infra-runner を使用している

解決策: 最新版を使用していることを確認

uses: GenerativeX/infra/actions/infra-runner@main

最新版では、マージモードがデフォルトで有効になっており、削除は表示されません：

✅ Found 9 changes (9 added, 0 modified) - merge mode: existing vars preserved

ワークフローの内部動作

org-deploy.yml のアーキテクチャ

org-deploy.yml は 4 つのジョブで構成されています：

org-deploy.yml
  │
  ├─ Job 1: Plan
  │    ├─ infra-runner (plan.json 生成)
  │    └─ Deployment matrix 生成
  │
  ├─ Job 2: Build (matrix strategy)
  │    └─ docker-build-push (並列実行)
  │
  ├─ Job 3: Apply Env (matrix strategy)
  │    └─ azure-env-apply (並列実行)
  │
  └─ Job 4: Deploy (matrix strategy)
       └─ azure-deploy (並列実行)

処理フロー:

1. Plan ジョブ が plan.json を解析し、各サービスに必要なアクションを判断
2. 判断結果を deployment matrix として出力
3. 後続のジョブは matrix に基づいて並列実行
4. 各サービスで不要なステップは自動的にスキップ

利点:

• ✅ 自動化: plan の結果に基づいて必要なアクションのみ実行
• ✅ 並列処理: 複数サービスを同時にビルド・デプロイ
• ✅ 効率性: 変更がないサービスは自動的にスキップ
• ✅ 再利用可能: Product リポジトリから簡単に呼び出し可能

技術的な背景

GitHub Actions の制約と解決策

課題:

• JavaScript アクションは実行中に他のアクションを呼び出せない
• infra-runner 内から docker-build-push を動的に実行することは不可能

解決策:

• ワークフロー YAML レベルで複数ジョブに分離
• Plan ジョブで deployment matrix を生成
• 後続ジョブが matrix に基づいて必要なアクションを実行

個別アクションの使用例

docker-build-push アクションの使用

- name: Build and Push Docker Image
  uses: GenerativeX/infra/actions/docker-build-push@main
  with:
    login_server: gxsharedacr.azurecr.io
    repository: my-app/frontend
    context: ./frontend
    dockerfile: ./frontend/Dockerfile
    tags: '["${{ github.sha }}", "latest", "v1.0.0"]'
    build_args: '{"NODE_ENV": "production", "VERSION": "1.0.0"}'
    cache_from: '["gxsharedacr.azurecr.io/my-app/frontend:cache"]'
    cache_to: "type=inline"

azure-env-apply アクションの使用

- name: Apply Environment Variables
  uses: GenerativeX/infra/actions/azure-env-apply@main
  with:
    target: container_apps
    resource_group: rg-myapp-prd
    resource_name: ca-myapp-frontend-prd
    env_json: |
      {
        "NODE_ENV": "production",
        "API_URL": "https://api.example.com",
        "DATABASE_URL": "${{ secrets.DATABASE_URL }}"
      }
    merge_mode: true # 既存の環境変数を保持

azure-deploy アクションの使用

- name: Deploy Container Image
  uses: GenerativeX/infra/actions/azure-deploy@main
  with:
    target: container_apps
    resource_group: rg-myapp-prd
    resource_name: ca-myapp-frontend-prd
    image: gxsharedacr.azurecr.io/my-app/frontend:${{ github.sha }}
    replicas: "3"
    cpu: "1.0"
    memory: "2.0Gi"
    health_check: true

参考リンク

• 環境変数の管理
• GitHub Actions ワークフロー設計