はじめに

FastAPIで構築しているアプリケーションから、バッチ処理部分を切り出し、Google Cloud Run Jobsで動かすことになりました。

ロジック自体はPythonで実装し、Cloud Spannerへデータを保存する構成です。ローカルでの検証は済んでいたのですが、実際にクラウド環境へデプロイする際にいくつか設定周りで躓くポイントがありました。

そのため備忘録として、一連のデプロイ手順と、作業中に遭遇したエラーや「ハマりポイント」についてまとめます。
内容について、もしより良い方法などお気づきの点がございましたら、お教えいただけますと幸いです。

デプロイ手順

今回は、Artifact RegistryにDockerイメージを保存し、そこからCloud Run Jobsを作成して実行する流れになります。

1. コンテナレジストリの作成

まずはDockerイメージの保存場所を作成します。初回のみ必要な作業です。

gcloud artifacts repositories create 任意のリポジトリ名 \
  --repository-format=docker \
  --location=リージョン \
  --description="リポジトリの情報"

2. Docker イメージのビルド

次に、作成済みのDockerfileを使用してイメージをビルドします。
ここで重要なのが、デプロイ先のアーキテクチャに合わせることです（後述のハマりポイントで詳しく触れます）。

docker build \
  --platform linux/amd64 \
  -f .../Dockerfile \
  -t リージョン-docker.pkg.dev/[PROJECT_ID]/リポジトリ名/イメージ名:タグ \
  .

3. イメージの Push

ビルドしたイメージをArtifact Registryにプッシュします。

docker push リージョン-docker.pkg.dev/[PROJECT_ID]/リポジトリ名/イメージ名:タグ

4. Job の作成と環境変数の設定

Jobの定義を作成し、実行に必要な環境変数を設定します。

gcloud run jobs create ジョブ名 \
  --image リージョン-docker.pkg.dev/[PROJECT_ID]/リポジトリ名/イメージ名:タグ \
  --region リージョン \
  --set-env-vars "必要な環境変数"

5. 手動実行と確認

最後に、作成したJobを手動で実行して動作を確認します。

gcloud run jobs execute ジョブ名 --region リージョン

実際に遭遇したハマりポイントと解決策

手順自体はシンプルに見えますが、実際に進めているといくつかのエラーに引っかかりました。特に以下の3点は注意が必要です。

1. Macユーザーを襲う「exec format error」

ローカルでビルドしてデプロイし、いざCloud Runで実行したところ、ログに exec format error というエラーが出て即座に終了してしまいました。

原因はCPUアーキテクチャの違いでした。私が使用しているMac（M1/M2など）はARM64アーキテクチャですが、Cloud RunはAMD64（x86_64）で動作しています。そのため、そのままビルドしたイメージでは言葉が通じずエラーになっていました。

解決策：
ビルドコマンドに --platform linux/amd64 を明示的に付けることで、クラウド環境用の形式に変換（クロスコンパイル）してあげる必要がありました。

2. 環境変数に「カンマ（,）」が含まれる場合の罠

ALLOWED_DOMAINS=a.com,b.com のように、値の中にカンマを含む環境変数を設定しようとしたところ、意図した通りに設定されませんでした。

これは、gcloud コマンドの --set-env-vars オプションが、デフォルトでカンマを「複数の変数の区切り文字」として認識してしまうためです。

解決策：
区切り文字を変更する特殊な構文 ^:^ を先頭に付けることで解決しました。:が区切り文字となるため、値に含まれるカンマ（,）が区切りとして誤認されず、『カンマを含んだ1つの文字列』として正しく変数に格納されます。

gcloud run jobs update ... --set-env-vars "^:^ALLOWED_DOMAINS=a.com,b.com"

3. CLIコマンドの改行（バックスラッシュ）について

長いコマンドを見やすくしようとバックスラッシュ（\）で改行して実行した際、引数が正しく認識されずにエラーになることがありました。
慣れないうちは無理に改行せず、少し長くても「1行で実行」するのが一番確実で安全だと痛感しました。

まとめ

Cloud Run Jobsへのデプロイ手順と、実作業で遭遇した注意点についてまとめました。

単にコマンドを打つだけでなく、プラットフォームの違いやコマンドラインツールの仕様など、背後にある仕組みを一つ一つ確認して理解しながら実装することが必要だと勉強になりました。