Cloud Run jobsでジョブ構成をオーバーライドしてジョブを実行する

記事タイトルとURLをコピーする

G-gen の佐々木です。当記事では Cloud Run jobs のジョブ実行時に利用できる、ジョブ構成のオーバーライド について解説します。

Cloud Run jobs とは

Cloud Run jobs は、サーバーレス コンテナコンピューティング サービスである Cloud Run の 1 機能です。Cloud Run services が HTTP リクエストを処理の起点とするのに対して、Cloud Run jobs はコンテナイメージとして実装したジョブを、手動、スケジュール、ワークフローなど、ユーザの任意タイミングで並列して実行することができます。

Cloud Run jobs の詳細については、以下の記事で解説しています。

blog.g-gen.co.jp

ジョブ構成のオーバーライド

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#(タスク番号)は 0TARGET_ENV 環境変数の値として TARGETdev になっています。

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 All Certifications Engineer。

好きな Google Cloud プロダクトは Cloud Run。