G-gen の佐々木です。当記事では Cloud Run jobs のジョブ実行時に利用できる、ジョブ構成のオーバーライド について解説します。
Cloud Run jobs とは
Cloud Run jobs は、サーバーレス コンテナコンピューティング サービスである Cloud Run の 1 機能です。Cloud Run services が HTTP リクエストを処理の起点とするのに対して、Cloud Run jobs はコンテナイメージとして実装したジョブを、手動、スケジュール、ワークフローなど、ユーザの任意タイミングで並列して実行することができます。
Cloud Run jobs の詳細については、以下の記事で解説しています。
ジョブ構成のオーバーライド
Cloud Run jobs では、ジョブの作成時に環境変数、タスク数（処理を並列実行する数。各実行は タスク と呼ばれる）、タイムアウトなどの値をジョブ構成として設定します。
これらのジョブ構成のうちのいくつかは、ジョブを実行する際にオーバーライドすることが可能です。つまり、ジョブ構成として設定された値を変更することなく、一度のジョブ実行でのみ有効な値を設定する ことができます。
ジョブ構成のうちオーバーライド可能なパラメータは以下の 4つです。
- コンテナのエントリポイントとなるコマンドに渡す引数
- ジョブの環境変数
- タスク数（タスクの並列実行数）
- タスクのタイムアウト（最大実行時間）
ジョブ構成のオーバーライドは以下のようなユースケースが考えられます。
- 日付や処理対象テーブルなどを引数や環境変数に設定し、ジョブに処理させるデータの範囲を実行ごとに切り替える
- ジョブに処理させるデータ量が通常より多い場合に、並列実行数やタイムアウトの値を増やす
参考：ジョブを実行する | 特定の実行のジョブ構成をオーバーライドする
ジョブ構成のオーバーライドを試してみる
使用するコード（Go）
当記事では、オーバーライド可能な各種パラメータを標準出力するだけのシンプルな処理を実行するコードを使用し、ジョブ構成のオーバーライドを試してみます。
コード内でオーバーライドの対象となっているのは、ジョブ実行時の引数となる --user の値と、ジョブ自体に設定する TARGET_ENV 環境変数の値です。これらを標準出力するだけのシンプルな処理となっています。
また、ジョブの実行時に タスク数 と タイムアウト の値もオーバーライドします。Cloud Run jobs でタスクを並列実行する際、CLOUD_RUN_TASK_INDEX 環境変数からタスク番号を取得できるため、これもあわせて出力します。
package main import ( "flag" "fmt" "os" ) func main() { // 引数の定義と値の取得 var u = flag.String("user", "unknown", "user name") // --userオプション（デフォルト値：unknown） flag.Parse() taskNum := os.Getenv("CLOUD_RUN_TASK_INDEX") // 並列実行タスクのタスク番号（インデックス） userName := *u // ジョブ実行時に与えた引数 targetEnv := os.Getenv("TARGET_ENV") // ユーザーが設定した環境変数 // タスク番号、引数、環境変数を標準出力 fmt.Printf("TASK#%v USER:%v TARGET:%v\n", taskNum, userName, targetEnv) }
Cloud Run ジョブのデプロイ
gcloud run jobs deploy コマンドで Cloud Run jobs のジョブをデプロイします。
以下のコマンドを使用することで、Dockerfile を用意することなくソースコードからジョブをデプロイすることができます（参考）。
当記事では「run-jobs-override」という名前でジョブをデプロイします。
# ソースコードから Cloud Run ジョブをデプロイする $ gcloud run jobs deploy {ジョブ名} \ --source . \ --tasks 1 \ --set-env-vars TARGET_ENV=dev \ --region asia-northeast1 \ --project {プロジェクトID} ---出力例--- $ gcloud run jobs deploy run-jobs-override \ --source . \ --tasks 1 \ --set-env-vars TARGET_ENV=dev \ --region asia-northeast1 \ --project myproject This command is equivalent to running `gcloud builds submit --pack image=[IMAGE] .` and `gcloud run jobs deploy run-jobs-override --image [IMAGE]` Building using Buildpacks and deploying container to Cloud Run job [run-jobs-override] in project [myproject] region [asia-northeast1] ✓ Building and creating job... Done. ✓ Uploading sources... ✓ Building Container... Logs are available at [https://console.cloud.google.com/cloud-build/builds/2350151f-1af8-4ef8-99b4-980ce5f761ea?project=xxxxxxxxxxxx]. Done. Job [run-jobs-override] has successfully been deployed. To execute this job, use: gcloud run jobs execute run-jobs-override
なお、上記のコマンドでジョブをデプロイすると、ビルドされたコンテナイメージは「cloud-run-source-deploy」という名前の Artifact Registry リポジトリに格納されます。このリポジトリがプロジェクトにまだ存在していない場合、ジョブのデプロイ時にリポジトリを新規作成するかどうか確認されます。
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [asia-northeast1] will be created. Do you want to continue (Y/n)? Y
デフォルトのジョブ構成でジョブを実行する
まず、デプロイしたジョブをそのまま実行してみます。
ジョブの実行には gcloud run jobs execute コマンドを使用し、ジョブをデプロイしたリージョンのみオプションに指定して実行します。
# ジョブ構成の通りにジョブを実行する $ gcloud run jobs execute {ジョブ名} --region asia-northeast1 ---出力例--- $ gcloud run jobs execute run-jobs-override --region asia-northeast1 ✓ Creating execution... Done. ✓ Provisioning resources... Done. Execution [run-jobs-override-94g9h] has successfully started running. View details about this execution by running: gcloud run jobs executions describe run-jobs-override-94g9h Or visit https://console.cloud.google.com/run/jobs/executions/details/asia-northeast1/run-jobs-override-94g9h/tasks?project=xxxxxxxxxxxx
出力内の View details about this execution by running: に記載されている gcloud run jobs executions describe コマンドで、実行したジョブの詳細を確認します。
以下のように、並列実行タスク数（Tasks）、タイムアウト（Task Timeout）がそれぞれデフォルトの値に、TARGET_ENV 環境変数（Env vars: TARGET_ENV）がデプロイ時に指定した値になっていることがわかります。
| 項目 | 値 |
|---|---|
| Tasks | 1 |
| Task Timeout | 600s |
| Env vars: TARGET_ENV | dev |
$ gcloud run jobs executions describe {ジョブの実行ID} ---出力例--- # 実行したジョブの詳細を確認する $ gcloud run jobs executions describe run-jobs-override-94g9h --region asia-northeast1 ✔ Execution run-jobs-override-94g9h in region asia-northeast1 1 task completed successfully Elapsed time: 12 seconds Log URI: https://console.cloud.google.com/logs/viewer?project=myproject&advancedFilter=resource.type%3D%22cloud_run_job%22%0Aresource.labels.job_name%3D%22run-jobs-override%22%0Aresource.labels.location%3D%22asia-northeast1%22%0Alabels.%22run.googleapis.com/execution_name%22%3D%22run-jobs-override-94g9h%22 Image: asia-northeast1-docker.pkg.dev/myproject/cloud-run-source-deploy/run-jobs-override Tasks: 1 Memory: 512Mi CPU: 1000m Task Timeout: 600s Max Retries: 3 Parallelism: 1 Service account: xxxxxxxxxxxx-compute@developer.gserviceaccount.com Env vars: TARGET_ENV dev
出力されたジョブ詳細の Log URI: に記載されている URL から Cloud Logging のコンソールに遷移してログ出力を確認します。
タスクが 1つしか実行されていないため、コード内の fmt.Printf 関数から出力されたログは以下の 1件のみとなっています。
TASK#0 USER:unknown TARGET:dev
タスクが 1つなので TASK#（タスク番号）は 0、TARGET_ENV 環境変数の値として TARGET が dev になっています。
USER はジョブ実行時に --user 引数を指定しなかったため、デフォルトに設定しておいた unknown になっていることがわかります。
ジョブ構成をオーバーライドしてジョブを実行する
次に、ジョブ構成をオーバーライドしてジョブを実行してみます。
以下のオプションを使用して各種パラメータをオーバーライドすることができます。
| オプション | 説明 |
|---|---|
| --args | コンテナのエントリポイントとなるコマンドに渡す引数 |
| --update-env-vars | ジョブの環境変数 （ {KEY1}={VALUE1},{KEY2}={VALUE2} の形式で指定） |
| --tasks | タスクの並列実行数 |
| --task-timeout | タスクの最大実行時間 （たとえば 10分の場合、 10m もしくは 600s の形式で指定） |
--user 引数に sasashun を指定し、TARGET_ENV 環境変数を prod、並列実行タスク数を 3、タイムアウトを 10m30s でオーバーライドしてジョブを実行します。
# ジョブ構成をオーバーライドしてジョブを実行する $ gcloud run jobs execute {ジョブ名} \ --region asia-northeast1 \ --args="--user=sasashun" \ --update-env-vars TARGET_ENV=prod \ --tasks 3 \ --task-timeout 10m30s ---出力例--- $ gcloud run jobs execute run-jobs-override \ --region asia-northeast1 \ --args="--user=sasashun" \ --update-env-vars TARGET_ENV=prod \ --tasks 3 \ --task-timeout 10m30s ✓ Creating execution... Done. ✓ Provisioning resources... Done. Execution [run-jobs-override-cd2f8] has successfully started running. View details about this execution by running: gcloud run jobs executions describe run-jobs-override-cd2f8 Or visit https://console.cloud.google.com/run/jobs/executions/details/asia-northeast1/run-jobs-override-cd2f8/tasks?project=xxxxxxxxxxxx
gcloud run jobs executions describe コマンドで実行したジョブの詳細を確認します。
出力例にあるように、実行時にオーバーライドした値が反映されていることがわかります。
| 項目 | ジョブ構成の値 | オーバーライドした値 |
|---|---|---|
| Tasks | 1 | 3 |
| Task Timeout | 600s | 10m30s |
| Env vars: TARGET_ENV | dev | prod |
# 実行したジョブの詳細を確認する $ gcloud run jobs executions describe run-jobs-override-cd2f8 --region asia-northeast1 ---出力例--- $ gcloud run jobs executions describe run-jobs-override-cd2f8 --region asia-northeast1 ✔ Execution run-jobs-override-cd2f8 in region asia-northeast1 3 tasks completed successfully Elapsed time: 18 seconds Log URI: https://console.cloud.google.com/logs/viewer?project=myproject&advancedFilter=resource.type%3D%22cloud_run_job%22%0Aresource.labels.job_name%3D%22run-jobs-override%22%0Aresource.labels.location%3D%22asia-northeast1%22%0Alabels.%22run.googleapis.com/execution_name%22%3D%22run-jobs-override-cd2f8%22 Image: asia-northeast1-docker.pkg.dev/myproject/cloud-run-source-deploy/run-jobs-override Tasks: 3 Args: --user=sasashun Memory: 512Mi CPU: 1000m Task Timeout: 10m30s Max Retries: 3 Parallelism: 3 Service account: xxxxxxxxxxxx-compute@developer.gserviceaccount.com Env vars: TARGET_ENV prod
ジョブ詳細の Log URI: に記載されている URL から Cloud Logging のコンソールに遷移してログ出力を確認します。
オーバーライドされたタスク数である 3タスクが実行され、--user 引数と TARGET_ENV 環境変数の値がジョブに反映されていることがわかります。
TASK#0 USER:sasashun TARGET:prod TASK#1 USER:sasashun TARGET:prod TASK#2 USER:sasashun TARGET:prod
トラブルシューティング (CLI)
ジョブ構成のオーバーライドは 2023年 10月に GA となった機能であり、使用している gcloud CLI のバージョンによっては各種オプションが指定できない場合があります。
gcloud CLI のバージョンが古くオプションが指定できない場合、以下のようなエラーメッセージが出力されます。
ERROR: (gcloud.run.jobs.execute) unrecognized arguments: --args flag is available in one or more alternate release tracks. Try: gcloud alpha run jobs execute --args gcloud beta run jobs execute --args --args=--user=sasashun (did you mean '--async'?)
このようなエラーにより CLI からのジョブ実行が上手くいかない場合、まずは gcloud run jobs execute --help でオーバーライドに関するオプション（--args など）が表示されているか確認してください。
# 使用できるオプションを確認する $ gcloud run jobs execute --help NAME gcloud run jobs execute - qexecute a job SYNOPSIS gcloud run jobs execute [JOB] [--args=[ARG,...]] [--region=REGION] [--task-timeout=TASK_TIMEOUT] [--tasks=TASKS] [--update-env-vars=[KEY=VALUE,...]] [--async | --wait] [GCLOUD_WIDE_FLAG ...] ~~~以下省略~~~
オプションが無い場合、使用している gcloud CLI のバージョンによっては gcloud bata run jobs execute もしくは gcloud alpha run jobs execute コマンドでオプションを指定して実行することができますが、可能であれば gcloud CLI をアップグレードすることを推奨します。
佐々木 駿太 (記事一覧)
G-gen最北端、北海道在住のクラウドソリューション部エンジニア
2022年6月にG-genにジョイン。Google Cloud Partner Top Engineer 2024に選出。好きなGoogle CloudプロダクトはCloud Run。
趣味はコーヒー、小説（SF、ミステリ）、カラオケなど。
Follow @sasashun0805