Skip to content

Repository navigation

AWS Backend Setup

Jump to bottom
284_vd0w0bv edited this page Jun 5, 2026 · 9 revisions

AWS バックエンド設定マニュアル (WhisperX 連携機能)

本マニュアルは、本ソフトにおけるバックエンドの AWS 連携機能について、概要・アーキテクチャ・必要な AWS リソース・環境変数・ローカル/本番でのセットアップ手順・トラブルシューティングを説明します。

対象読者: AWS（S3 / DynamoDB / AWS Batch / Lambda / API Gateway）と Terraform の基本操作ができる開発者・インフラ担当者を想定しています。

目次

  1. 概要とアーキテクチャ
  2. 前提条件
  3. 必要な AWS リソースと要件
  4. バックエンド環境変数一覧
  5. ローカル開発環境から AWS リソースを利用する手順
  6. 接続テストとトラブルシューティング
  7. AWS Batch (Worker) の CPU / GPU 設定切り替え
  8. IAM ポリシーの最小構成
  9. ワーカーイメージのビルドと ECR への push

このページから参照するソースコード・インフラ定義は、いずれも GitHub リポジトリ matsuolab/lecture_subtitle_translator の main ブランチを指します。

1. 概要とアーキテクチャ

バックエンドの動作モードを aws に設定すると、Web API と文字起こし処理（Worker）が分離された非同期分散型アーキテクチャに切り替わります。

flowchart TD
    Client["クライアント (Tauri / Web)"]
    APIGW["HTTP API Gateway"]
    Lambda["Lambda Managed API<br/>(backend.lambda_handler.handler)"]
    S3Input["S3 Input Bucket<br/>(音声・動画アップロード)"]
    S3Result["S3 Result Bucket<br/>(結果JSON格納)"]
    DynamoDB["DynamoDB Jobs Table<br/>(ステータス台帳)"]
    SecretsManager["AWS Secrets Manager<br/>(Bearerトークン)"]
    BatchQueue["AWS Batch Job Queue"]
    BatchEnv["AWS Batch Compute Environment"]
    Worker["WhisperX Worker (EC2 Container)<br/>(backend.aws_worker)"]

    %% 1. アップロード & ジョブ作成
    Client -->|"1. 接続確認 & アップロード要求"| APIGW
    APIGW --> Lambda
    Lambda -->|"2. 署名付きURL生成"| Client
    Client -->|"3. 音声ファイルPUT"| S3Input
    Client -->|"4. ジョブ開始リクエスト"| APIGW
    Lambda -->|"5. ジョブ初期データ登録"| DynamoDB
    Lambda -->|"6. ジョブ投入 (submit_job)"| BatchQueue

    %% 2. ジョブ実行
    BatchQueue --> BatchEnv
    BatchEnv -->|"7. ジョブ実行"| Worker
    Worker -->|"8. 音声ダウンロード"| S3Input
    Worker -->|"9. ステータス更新 (running)"| DynamoDB
    Worker -->|"10. 処理実行 (WhisperX)"| Worker
    Worker -->|"11. 結果JSONアップロード"| S3Result
    Worker -->|"12. ステータス更新 (success/failed)"| DynamoDB

    %% 3. 結果取得
    Client -->|"13. ポーリング (状態確認)"| APIGW
    Lambda -->|"14. ジョブ状態読み込み"| DynamoDB
    Client -->|"15. 完了検知 -> 結果取得"| APIGW
    Lambda -->|"16. 結果JSON読み込み"| S3Result
    Lambda -->|"17. 結果返却"| Client

    %% その他
    Lambda -.->|"認証トークン取得"| SecretsManager
Loading

2. 前提条件

本マニュアルは「Terraform で AWS インフラが既に展開済み」であることを前提に、その利用方法を説明します。インフラ未展開の場合は、先に Terraform を適用してください。

必要なツール

ツール 用途
AWS CLI v2 認証情報の設定・各種確認
Terraform インフラの構築（infra/terraform/aws_dev/）
Python 3.13 + venv バックエンド API のローカル実行
Docker WhisperX Worker コンテナのビルド・ECR push

Terraform 適用時に指定が必須の変数

variables.tf のうち デフォルト値がない変数は terraform apply 時に必ず指定する必要があります。

変数名 内容
private_subnet_ids AWS Batch / Lambda を配置するプライベートサブネット ID のリスト
batch_security_group_ids Batch コンピュート環境に付与するセキュリティグループ ID のリスト
budget_alert_email コストアラート（Budgets / Cost Anomaly Detection）の通知先メールアドレス
managed_service_bearer_token Secrets Manager に格納する Bearer トークン（sensitive）

リージョン・インスタンスタイプ・ライフサイクル日数などその他の変数はデフォルト値を持ちます。詳細は variables.tf を参照してください。

3. 必要な AWS リソースと要件

インフラ定義ファイル main.tf に基づく、必要な AWS リソースの要件です。

① S3 バケット (2つ)

  1. 入力用バケット (MANAGED_SERVICE_AWS_INPUT_BUCKET)
    • CORS 設定: ブラウザ（Web / dev）から Presigned URL 経由で直接 PUT アップロードできるようにするため、以下の CORS 許可が必要です。
      • 許可するオリジン: http://127.0.0.1:5173, http://localhost:5173, http://tauri.localhost, https://tauri.localhost
      • 許可するメソッド: PUT, GET, HEAD
      • 許可するヘッダー: *
      • 露出するヘッダー: ETag
      • キャッシュ時間 (max_age_seconds): 300

    • [!NOTE] S3 は tauri://localhost を CORS オリジンとして受け付けません。そのため macOS / Linux の Tauri アプリでは、ブラウザの fetch（CORS 対象）ではなく Rust 側の HTTP クライアント（tauriFetch）経由で S3 に直接 PUT します。この経路は Origin ヘッダーを送らず CORS の対象外となるため、S3 CORS に tauri://localhost を含める必要はありません（pipelineClient.ts 参照）。

    • ライフサイクル: アップロードされた音声ファイルは一時ファイルであるため、1日後に自動削除するように構成します（s3_input_expiration_days = 1）。
  2. 結果出力用バケット (MANAGED_SERVICE_AWS_RESULT_BUCKET)
    • ライフサイクル: コスト削減のため、30日後に低頻度アクセスストレージ（STANDARD_IA）へ移行し（s3_result_transition_days = 30）、120日後に自動削除します（s3_result_expiration_days = 120）。

② DynamoDB テーブル (MANAGED_SERVICE_AWS_JOBS_TABLE)

  • プライマリキー: job_id (文字列 / S)
  • 課金モード: PAY_PER_REQUEST（オンデマンド）。
  • レコードのスキーマ: アプリケーション側から以下のキーが読み書きされます。
    • job_id (S, Hash Key)
    • status (S): queued -> running -> success / failed
    • current_step (S): 進捗ステップ (例: queued, transcribe)
    • completed_steps (L): 完了したステップのリスト
    • source_name (S): 入力元のファイル名
    • input_key (S): S3上の入力ファイルキー
    • workflow (S): 使用したワークフロー名
    • batch_job_id (S): AWS Batch のジョブID
    • result_key (S): S3上の結果JSONキー (成功時)
    • error (S): エラーログ (失敗時)
    • created_at / updated_at (S): UTCタイムスタンプ（YYYY-MM-DDTHH:MM:SSZ）

③ AWS Secrets Manager (MANAGED_SERVICE_BEARER_TOKEN_SECRET_NAME)

  • 認証モードが bearer_token に設定されている場合、API Gateway 経由のリクエストを検証するための静的トークンをシークレット値として安全に保管します。

④ ECR リポジトリ

  • WhisperX 実行環境をコンテナ化した Docker イメージを格納します。

  • [!IMPORTANT] イメージは自動ではビルドされません。 Terraform は空の ECR リポジトリを作成するだけで、ワーカーイメージのビルドと push は手動で行う必要があります（§9 ワーカーイメージのビルドと ECR への push 参照）。イメージを push する前に Batch ジョブを実行すると、イメージを pull できずに失敗します。

  • ライフサイクルポリシー:
    • untagged（タグなし）イメージは1日後に自動削除。
    • リポジトリに保持するタグ付きイメージは最大 ecr_keep_image_count 件（デフォルト 5件）に制限し、ストレージコストを抑制します。

⑤ AWS Batch 構成

  • Compute Environment (計算環境): 以下の 3つ を定義しています。
    • *-gpu: GPU スポット（g4dn.xlarge / SPOT_CAPACITY_OPTIMIZED）。
    • *-gpu-ondemand: GPU オンデマンド（g4dn.xlarge / BEST_FIT_PROGRESSIVE）。
    • *-cpu-ondemand: CPU オンデマンド（フォールバック用）。batch_include_cpu_fallback = true のときのみキューに組み込まれます。GPU Quota 制限時の経路確認テスト用途として、m7i.xlarge などの CPU インスタンスを定義可能。
    • いずれも Fargate ではなく EC2 計算環境です。理由は、WhisperX のベースコンテナイメージが大きいため、EC2 の ECS コンテナエージェントによるキャッシュ（ECS_IMAGE_PULL_BEHAVIOR = prefer-cached）を有効にして、2回目以降のジョブ起動（コンテナプル時間）を高速化するためです。
  • Job Queue (ジョブキュー):
    • 投入されたジョブの待機列。計算環境を優先順位付きでマッピングします: ① GPU オンデマンド → ② GPU スポット →（任意）③ CPU オンデマンド（フォールバック）。
  • Job Definition (ジョブ定義):
    • プラットフォーム: EC2
    • 実行コマンド: ["python", "-m", "backend.aws_worker"]
    • 各種 WhisperX 動作用環境変数を設定（§7 参照）。

4. バックエンド環境変数一覧

バックエンドが AWS 連携モードで動作する際に必要な環境変数の一覧です。設定の解決ロジックは backend/managed/settings.py を参照してください。

必須設定 (AWS モード動作時)

環境変数名 設定値の例 説明
MANAGED_SERVICE_BACKEND aws バックエンドの動作モードを AWS 連携に指定。
AWS_REGION ap-northeast-1 AWS リソースが配置されているリージョン。AWS_DEFAULT_REGION でも代替可。
MANAGED_SERVICE_AWS_INPUT_BUCKET matsuo-subtitle-pipeline-dev-input アップロード用 S3 バケット名。
MANAGED_SERVICE_AWS_RESULT_BUCKET matsuo-subtitle-pipeline-dev-result 結果保存用 S3 バケット名。
MANAGED_SERVICE_AWS_JOBS_TABLE matsuo-subtitle-pipeline-dev-jobs ジョブ状態を保存する DynamoDB テーブル名。
MANAGED_SERVICE_AWS_BATCH_JOB_QUEUE matsuo-subtitle-pipeline-dev-queue ジョブを投入する AWS Batch のジョブキュー名。
MANAGED_SERVICE_AWS_BATCH_JOB_DEFINITION matsuo-subtitle-pipeline-dev-worker 実行する AWS Batch のジョブ定義名。

オプション・カスタマイズ設定

環境変数名 デフォルト値 説明
MANAGED_SERVICE_AWS_INPUT_PREFIX input-audio/ S3 入力バケット内のフォルダプレフィックス。
MANAGED_SERVICE_AWS_RESULT_PREFIX results/ S3 結果バケット内のフォルダプレフィックス。
MANAGED_SERVICE_AUTH_MODE none 認証方式。none または bearer_token。
MANAGED_SERVICE_BEARER_TOKEN (なし) auth_mode が bearer_token 時の静的なトークン文字列（テスト・直書き用）。
MANAGED_SERVICE_BEARER_TOKEN_SECRET_NAME (なし) Secrets Manager から Bearer トークンを取得する場合のシークレット名。
MANAGED_SERVICE_AWS_JOB_PAYLOAD_ENV AWS_MANAGED_JOB_PAYLOAD AWS Batch コンテナにジョブデータを引き渡す環境変数名。⚠ 後述の注意参照。
MANAGED_SERVICE_MAX_UPLOAD_SIZE_BYTES 5368709120 (5GB) 最大アップロードサイズ（バイト）。

Warning

MANAGED_SERVICE_AWS_JOB_PAYLOAD_ENV は実質的に変更不可です。 ジョブを投入する API 側（aws_adapter.py）はこの設定に従いますが、 受け取る Worker 側（aws_worker.py）は環境変数名 AWS_MANAGED_JOB_PAYLOAD をハードコードしています。 デフォルト値から変更すると Worker がペイロードを読めずに失敗するため、既定値のまま使用してください。

5. ローカル開発環境から AWS リソースを利用する手順

AWS 上に Terraform でインフラが展開されていれば、ローカルの Python 開発環境から AWS 上の S3・DynamoDB・AWS Batch をターゲットにしてデバッグできます。

ステップ 1: AWS CLI 認証情報の設定

ローカルマシンに AWS CLI をインストールし、適切な権限（§8 IAM ポリシーの最小構成 を参照）を持つ IAM ユーザーまたはロールの認証情報をセットアップします。

# 認証プロファイルを作成（例: dev プロファイル）
aws configure --profile dev

ステップ 2: ローカル環境変数の設定

プロジェクトのルートまたはバックエンド実行環境に、以下の環境変数を設定した .env ファイルを作成するか、シェルにエクスポートします。

# AWS 接続用の認証プロファイル指定
export AWS_PROFILE=dev

# バックエンドを AWS 連携モードに設定
export MANAGED_SERVICE_BACKEND=aws
export AWS_REGION=ap-northeast-1

# Terraform 適用後に生成された AWS リソース名を指定
export MANAGED_SERVICE_AWS_INPUT_BUCKET=matsuo-subtitle-pipeline-dev-input
export MANAGED_SERVICE_AWS_RESULT_BUCKET=matsuo-subtitle-pipeline-dev-result
export MANAGED_SERVICE_AWS_JOBS_TABLE=matsuo-subtitle-pipeline-dev-jobs
export MANAGED_SERVICE_AWS_BATCH_JOB_QUEUE=matsuo-subtitle-pipeline-dev-queue
export MANAGED_SERVICE_AWS_BATCH_JOB_DEFINITION=matsuo-subtitle-pipeline-dev-worker

# 認証設定（開発時は none 推奨）
export MANAGED_SERVICE_AUTH_MODE=none

ステップ 3: バックエンドの起動

環境変数を読み込ませた状態で、バックエンド API サーバーを起動します。

# venv が有効な状態で実行
python -m uvicorn backend.api:app --reload --port 8000

起動後、ブラウザで http://localhost:8000/docs (Swagger UI) にアクセスし、AWS 連携 API の動作を確認できます。

6. 接続テストとトラブルシューティング

バックエンド API には、AWS リソースへの接続・アクセス権限を診断する専用エンドポイントが実装されています（backend/api.py）。

関連エンドポイント

メソッド・パス 用途
GET /health プロセスの死活確認（{"status":"ok"}）。
GET /v1/service-config サービス設定（バージョン・認証モード等）の取得。checks は含みません。
GET /v1/connection-check AWS リソースへの接続・権限診断。下記の checks 付き JSON を返します。

auth_mode = bearer_token の場合は、上記 /v1/* エンドポイントへのリクエストに Authorization: Bearer <token> ヘッダーが必要です。

接続の確認方法

GET /v1/connection-check を実行します。内部では以下のチェックが上から順に実行され、接続の可否を判定します（aws_adapter.py の check_connection）。

# 内部の診断ロジック (aws_adapter.py)
s3.head_bucket(Bucket=input_bucket)        # 入力バケットへのアクセス権確認
s3.head_bucket(Bucket=result_bucket)       # 結果バケットへのアクセス権確認
ddb.describe_table(TableName=jobs_table)   # DynamoDB テーブルの存在確認
batch.describe_job_queues(...)             # ジョブキューの状態 (ENABLED かつ VALID か)
batch.describe_job_definitions(...)        # ジョブ定義の存在 (ACTIVE か)

返却される JSON レスポンス例：

{
  "service": "subtitle-managed-service",
  "version": "0.3.0",
  "auth": { "mode": "none" },
  "upload": { "strategy": "s3-presigned-put", "max_size_bytes": 5368709120 },
  "jobs": { "workflow": "managed_transcript_v1" },
  "ok": true,
  "checks": [
    { "name": "input_bucket", "ok": true, "detail": "matsuo-subtitle-pipeline-dev-input" },
    { "name": "result_bucket", "ok": true, "detail": "matsuo-subtitle-pipeline-dev-result" },
    { "name": "jobs_table", "ok": true, "detail": "matsuo-subtitle-pipeline-dev-jobs" },
    { "name": "batch_job_queue", "ok": true, "detail": "matsuo-subtitle-pipeline-dev-queue" },
    { "name": "batch_job_definition", "ok": true, "detail": "matsuo-subtitle-pipeline-dev-worker" }
  ]
}

トラブルシューティング

"ok": false が返ってきた場合の確認ポイント（失敗したチェックは checks[].ok = false と detail の例外内容で特定できます）：

失敗したチェック 主な原因 対策
input_bucket / result_bucket 1. バケット名が環境変数と不一致
2. IAM の S3 操作権限不足		 ・S3 バケット名を確認
・ポリシーに s3:ListBucket（head_bucket に必要）/ s3:GetObject / s3:PutObject が含まれているか確認
jobs_table 1. テーブル名が不一致
2. IAM の DynamoDB 操作権限不足		 ・DynamoDB テーブル名を確認
・ポリシーに dynamodb:DescribeTable が含まれているか確認
batch_job_queue 1. キューが存在しない
2. キューのステータスが ENABLED 以外
3. キューが VALID 以外（計算環境の紐付けエラーなど）		 ・AWS Batch 管理画面でキューの状態を確認
・ひもづく Compute Environment の状態をチェック
batch_job_definition 1. 指定された名前のジョブ定義がない
2. ジョブ定義が ACTIVE 状態ではない		 ・ジョブ定義名が正しいか、最新のリビジョンが ACTIVE になっているか確認

7. AWS Batch (Worker) の CPU / GPU 設定切り替え

AWS Batch のコンテナ上で動作する WhisperX worker（aws_worker.py）は、環境変数によって CPU 処理と GPU 処理を切り替えられます。

GPU quota の申請中などで、一時的に CPU 動作で経路確認テストを行う場合は、AWS Batch のジョブ定義（Job Definition）で以下の環境変数を書き換えます。

環境変数名 GPU モード (本番推奨) CPU モード (暫定テスト用) 説明
WHISPERX_DEVICE cuda cpu 実行する演算デバイス。
WHISPERX_COMPUTE_TYPE float16 int8 演算精度。CPU モード時は int8 必須。
WHISPERX_BATCH_SIZE 4 (または 8) 1 並列処理バッチサイズ。CPU 時は負荷軽減のため 1 を推奨。

Terraform 変数での切り替え

Terraform で構築する際は、variables.tf の以下の変数を terraform.tfvars などで上書きして適用します。

# CPU フォールバックテスト時の設定例 (terraform.tfvars)
batch_include_cpu_fallback = true            # CPU 計算環境をキューに組み込む
batch_instance_types       = ["m7i.xlarge"]  # CPU インスタンス
batch_ec2_image_type       = "ECS_AL2023"    # GPU 用 NVIDIA AMI から非 GPU AMI へ変更
batch_gpu_count            = 0
whisperx_device            = "cpu"
whisperx_compute_type      = "int8"
whisperx_batch_size        = 1

Note

batch_ec2_image_type のデフォルトは ECS_AL2023_NVIDIA（GPU 用）です。CPU インスタンスを使う場合は、上記のように非 GPU の AMI タイプへ変更してください。変更しないと NVIDIA ドライバ込みの不要なイメージで起動します。

8. IAM ポリシーの最小構成

API (Lambda) および Worker (Batch Job) が動作するために必要な IAM ポリシーの定義です。実体は main.tf の aws_iam_role_policy で管理されています。

A. API / Lambda 用 IAM ポリシー (lambda-managed-service)

API の受付、S3 Presigned URL 発行、AWS Batch へのジョブ送信、状態管理に必要な権限です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::<INPUT_BUCKET_NAME>/*",
        "arn:aws:s3:::<RESULT_BUCKET_NAME>/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::<INPUT_BUCKET_NAME>",
        "arn:aws:s3:::<RESULT_BUCKET_NAME>"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:DescribeTable",
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:UpdateItem"
      ],
      "Resource": "arn:aws:dynamodb:<REGION>:<ACCOUNT_ID>:table/<JOBS_TABLE_NAME>"
    },
    {
      "Effect": "Allow",
      "Action": [
        "batch:DescribeJobDefinitions",
        "batch:DescribeJobQueues",
        "batch:SubmitJob"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:<SECRET_NAME>"
    }
  ]
}

B. Worker / AWS Batch ジョブ用 IAM ポリシー (batch-job-access)

コンテナが音声ファイルをダウンロードし、結果をアップロードし、進捗を更新するために必要な権限です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::<INPUT_BUCKET_NAME>/*",
        "arn:aws:s3:::<RESULT_BUCKET_NAME>/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:UpdateItem"
      ],
      "Resource": "arn:aws:dynamodb:<REGION>:<ACCOUNT_ID>:table/<JOBS_TABLE_NAME>"
    }
  ]
}

Note

現状の Worker（aws_worker.py）が実際に使用する DynamoDB 操作は UpdateItem のみです。上記ポリシーは Terraform 定義に合わせて GetItem も含めていますが、より厳密に絞る場合は dynamodb:UpdateItem のみでも動作します。

Important

ジョブコンテナにアタッチする IAM ロールには、上記の「B. Worker 用ポリシー」を設定した jobRoleArn を指定してください。ECR からコンテナイメージを取得するために使用される executionRoleArn (ECSTaskExecutionRole) とは別のロールになります。

9. ワーカーイメージのビルドと ECR への push

WhisperX ワーカーのコンテナイメージは CI などで自動ビルドされません。AWS バックエンド環境を構築・運用する担当者（管理者）が、ビルドして ECR に push する必要があります。Terraform で ECR リポジトリを作成した後、かつ Batch ジョブを初めて実行する前に実施してください。

ビルド場所には次の2通りがあります。どちらか一方を実施すれば構いません。

  • 方法A: ローカルマシンでビルド — 手元に Docker があれば手軽。ただし大型イメージの pull / push で回線・ディスクを消費します。
  • 方法B: EC2 インスタンス上でビルド（大型イメージ向け・推奨） — AWS 内で完結するため、ECR への push が高速かつ安定。ローカルのディスク/回線を圧迫しません。

Note

ベースイメージ ghcr.io/jim60105/whisperx:large-v3-ja（Dockerfile）は GPU 向けで large-v3 モデルを同梱しているため非常に大きいです。ビルド環境には十分なディスク容量（数十 GB 規模）を用意してください。 なお、イメージ自体の ビルドに GPU は不要です（パッケージングのみ）。WHISPERX_DEVICE などの実行時挙動は Batch のジョブ定義の環境変数で上書きされるため、CPU フォールバック（§7）でも同一イメージを使えます。

共通: 変数の準備

どちらの方法でも、以下の変数を使います。

ACCOUNT_ID=<your-account-id>
REGION=ap-northeast-1
REPO=matsuo-subtitle-pipeline-dev-worker   # = <project_name>-<environment>-worker
ECR=${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com

方法A: ローカルマシンでビルド

# 1. ECR ログイン
aws ecr get-login-password --region ${REGION} --profile dev \
  | docker login --username AWS --password-stdin ${ECR}

# 2. ビルド（Dockerfile が COPY backend ... を行うため、ビルドコンテキストはリポジトリルート）
docker build \
  --platform linux/amd64 \
  -f infra/docker/aws_batch_worker/Dockerfile \
  -t ${ECR}/${REPO}:latest \
  .

# 3. push
docker push ${ECR}/${REPO}:latest

Note

Batch の EC2 インスタンス（g4dn.xlarge 等）は amd64 です。Apple Silicon など arm64 マシンでビルドする場合は --platform linux/amd64 の指定が必須です。

方法B: EC2 インスタンス上でビルド（大型イメージ向け・推奨）

AWS 内でビルドするため、ECR への push が同一リージョン内で完結します。ローカルの回線・ディスクを使いません。

ビルド用 EC2 の要件:

  • アーキテクチャ: x86_64 (amd64)。Batch 実行環境と同じため --platform 指定が不要。GPU は不要なので汎用インスタンス（例: c6i.xlarge / m6i.xlarge）で十分。
  • ルート EBS: 大型イメージに備え 十分な容量（例: gp3 100 GB 以上）。
  • IAM インスタンスプロファイル: ECR への push 権限（ecr:GetAuthorizationToken〔Resource: *〕, および対象リポジトリへの ecr:BatchCheckLayerAvailability / ecr:InitiateLayerUpload / ecr:UploadLayerPart / ecr:CompleteLayerUpload / ecr:PutImage）。これを付与しておけば、インスタンス上では --profile 指定なしで認証されます。
# ── EC2 インスタンスへ SSH / Session Manager で接続後 ──

# 1. Docker と git を導入（Amazon Linux 2023 の例）
sudo dnf install -y docker git
sudo systemctl enable --now docker

# 2. リポジトリを取得（プライベートリポジトリの場合は認証情報が必要）
git clone https://github.com/matsuolab/lecture_subtitle_translator.git
cd lecture_subtitle_translator

# 3. ECR ログイン（インスタンスプロファイルの権限で認証）
aws ecr get-login-password --region ${REGION} \
  | sudo docker login --username AWS --password-stdin ${ECR}

# 4. ビルド（amd64 ネイティブのため --platform は不要）
sudo docker build \
  -f infra/docker/aws_batch_worker/Dockerfile \
  -t ${ECR}/${REPO}:latest \
  .

# 5. push
sudo docker push ${ECR}/${REPO}:latest

Important

ビルド用 EC2 は push が終わったら停止または削除してください。起動したままだと課金が継続します。

共通: Terraform からイメージを参照させる

main.tf のジョブ定義は、変数 batch_worker_image_reference でイメージを指定します。

  • :latest を使う場合: batch_worker_image_reference を空のままにすると、<ECRリポジトリURL>:latest が自動的に参照されます。
  • digest 固定で運用する場合（再現性重視・推奨）: push 後に digest を取得し、terraform.tfvars に貼り付けます。
# push したイメージの digest を取得
aws ecr describe-images --repository-name ${REPO} --region ${REGION} --profile dev \
  --image-ids imageTag=latest --query 'imageDetails[0].imageDigest' --output text
# terraform.tfvars （digest 固定の例）
batch_worker_image_reference = "<ACCOUNT_ID>.dkr.ecr.ap-northeast-1.amazonaws.com/matsuo-subtitle-pipeline-dev-worker@sha256:<digest>"

Note

backend/ のコードや backend/requirements.txt を変更した場合は、ワーカーイメージにも反映するため再ビルド・再 push が必要です。digest 固定運用の場合は、新しい digest を terraform.tfvars に反映して terraform apply してください。

Clone this wiki locally