【Cloud Run】ジョブのタスクタイムアウトを延ばす方法

Cloud Run ジョブのタスクが途中で止められるときに、タスクタイムアウトを延ばす方法をまとめます。既定では1つのタスクは最大10分で止められ、設定を変えると最大168時間（7日）まで延ばせます。gcloud CLI・YAML・Terraform での設定と、1回の実行だけ延ばす方法を扱います。前提は Cloud Run ジョブ（gcloud run jobs）と、Terraform の google_cloud_run_v2_job リソースです。2026年11月時点の公式ドキュメントで確かめた内容です。

タスクタイムアウトの決まりを先に押さえる
gcloud で設定する
1回の実行だけタイムアウトを変える
YAML で設定する
Terraform で設定する
コンソールで設定する
動作を確認する
うまくいかないとき
参考

タスクタイムアウトの決まりを先に押さえる

既定は10分、最大は168時間

タスクタイムアウトは、タスクの1回の試行が動いてよい最長の時間です。既定は10分で、それより短くすることも、最大168時間（7日）まで延ばすこともできます。GPU を使うタスクは最大12時間です（プレビュー）。

ジョブの実行（execution）全体には明示的なタイムアウトがありません。すべてのタスクが終わった時点で、その実行が終わります。

タイムアウトは試行ごとに効く

リトライを有効にしているジョブでは、タイムアウトはタスクの試行1回ごとに適用されます。時間内に終わらなかった試行は止められ、最大リトライ回数（--max-retries）が残っていれば次の試行が始まります。

最大リトライ回数の既定は 3 で、0 から 10 の整数を指定できます。0 にすると、タスクは1回だけ実行され、失敗しても再試行されません。たとえばタイムアウトが1時間で最大リトライ回数が 3 のジョブは、毎回タイムアウトすると最初の1回と再試行3回で合計4時間ぶん動くことになります。

値の書き方

gcloud のフラグには、時間と単位を続けて書きます。

書き方	意味
`10m5s`	10分5秒
`2h`	2時間
`3600`	3600秒（単位を省くと秒として扱われる）

YAML とコンソールでは、秒・分・時のいずれかの整数で指定します。YAML の timeoutSeconds は秒数で、10分5秒なら 605 です。

gcloud で設定する

1. 今の設定を確かめる

gcloud run jobs describe JOB_NAME --region=REGION

JOB_NAME はジョブの名前、REGION はジョブのリージョン（asia-northeast1 など）です。返ってきた設定の中から、タスクタイムアウトの値を探します。

2. 既存のジョブのタイムアウトを変える

例として、1時間に延ばします。

gcloud run jobs update JOB_NAME \
  --region=REGION \
  --task-timeout=1h

3. 新しく作るジョブに設定する

ジョブを作るときに同じフラグを付けます。

gcloud run jobs create JOB_NAME \
  --region=REGION \
  --image=IMAGE_URL \
  --task-timeout=1h

IMAGE_URL はコンテナイメージの参照です（us-docker.pkg.dev/cloudrun/container/job:latest など）。

1回の実行だけタイムアウトを変える

ジョブの設定は変えずに、その実行だけ長くしたいときは、実行のコマンドに --task-timeout を付けます。処理時間が入力によって大きく変わるジョブに向いています。

gcloud run jobs execute JOB_NAME \
  --region=REGION \
  --task-timeout=3h

ここで指定した値はその実行にだけ効き、ジョブの定義は変わりません。次に --task-timeout を付けずに実行すると、ジョブに設定してある値が使われます。同じ方法で、引数（--args）・環境変数（--update-env-vars）・タスク数（--tasks）も実行ごとに上書きできます。

YAML で設定する

1. 今の設定を書き出す

gcloud run jobs describe JOB_NAME --region=REGION --format export > job.yaml

2. timeoutSeconds を書き換える

apiVersion: run.googleapis.com/v1
kind: Job
metadata:
  name: JOB_NAME
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - image: IMAGE_URL
          timeoutSeconds: 3600

timeoutSeconds は containers と同じ階層に書きます。

3. 反映する

gcloud run jobs replace job.yaml --region=REGION

Terraform で設定する

google_cloud_run_v2_job の内側の template ブロックに timeout を書きます。値は s で終わる秒数の文字列です。

resource "google_cloud_run_v2_job" "batch" {
  name     = "batch-job"
  location = "asia-northeast1"

  template {
    template {
      timeout     = "3600s"
      max_retries = 3

      containers {
        image = "us-docker.pkg.dev/cloudrun/container/job:latest"
      }
    }
  }
}

template が2段になっている点に注意してください。外側が実行（execution）のテンプレート、内側がタスクのテンプレートで、timeout と max_retries は内側に書きます。

コンソールで設定する

Google Cloud コンソールの Cloud Run のページで、メニューから Jobs を選ぶ
対象のジョブを選び、View and edit job configuration をクリックする
Containers, Connections, Security をクリックして設定を開く
Task timeout に時間を入力し、Time unit で秒・分・時のいずれかを選ぶ
Update をクリックする

動作を確認する

設定を書き出して、timeoutSeconds の行を見ます。

gcloud run jobs describe JOB_NAME --region=REGION --format export | grep timeoutSeconds

1時間に設定していれば、timeoutSeconds の値が 3600 になっています。

あわせて、実際に長い処理を1回流し、10分を過ぎてもタスクが止められずに最後まで終わることを確かめます。

gcloud run jobs execute JOB_NAME --region=REGION --wait

--wait を付けると、実行が終わるまでコマンドが待ちます。付けない場合は、実行が始まった時点でコマンドが終わります。

うまくいかないとき

延ばしたはずなのに、次の実行でまた10分で止まる

gcloud run jobs execute --task-timeout で指定した値は、その実行にしか効きません。毎回長くしたい場合は、gcloud run jobs update --task-timeout でジョブの設定を変えます。

Terraform で管理しているジョブを gcloud やコンソールで変えた場合は、次の terraform apply で Terraform に書いた値に戻ります。Terraform の timeout を直してください。

設定を変えようとすると権限エラーになる

ジョブの設定を変えるには、ジョブに対する Cloud Run デベロッパー（roles/run.developer）と、ジョブが使うサービスアカウントに対するサービスアカウントユーザー（roles/iam.serviceAccountUser）のロールが必要です。

実行するだけなら Cloud Run 起動元（roles/run.invoker）で足りますが、実行時に --task-timeout などで設定を上書きするには roles/run.developer が必要です。

タイムアウトを延ばしたのに、長い処理が途中で失敗する

タイムアウトは「ここまで動いてよい」という上限で、その時間まで中断なく動くことを保証するものではありません。タスクが長く動くほど、接続先の障害やメモリ不足、基盤側の問題に当たる可能性が上がります。公式ドキュメントは、長時間のタスクを持つジョブではとくにリトライを有効にすることを勧めています。

再試行はタスクを最初からやり直すので、途中経過を外部のストレージに書き出し、再試行のときに続きから始められる作りにしておくと、やり直しの時間を減らせます。

長時間のタスクで、外部への接続が途中で切れる

GPU を使わないタスクは、基盤のメンテナンスのときに別のインスタンスへライブマイグレーションされます。タスクの状態は引き継がれますが、VPC ネットワークへの外向きの接続はこのとき切れます。接続のリセットを扱えるクライアントライブラリを使うか、切れたら接続し直す処理を入れます。

移行の10秒前に SIGTSTP、再開の直後に SIGCONT のシグナルがタスクに届くので、これを受け取ってログに残しておくと、接続が切れた時刻と移行の時刻を突き合わせられます。

GPU を使うジョブで12時間より長くできない

GPU を使うタスクのタイムアウトは最大12時間です（プレビュー）。また、GPU を使うタスクはライブマイグレーションされず、メンテナンスのときに終了させられます。数時間のタイムアウトを設定したタスクは、完了までに少なくとも1回は中断されるものとして、定期的に途中経過を保存する作りにします。