Create jobs

For preview, Cloud Run jobs are available only in the region europe-west9

This page describes how to create and update Cloud Run jobs from an existing container image. Unlike services, which listen for requests, a job does not serve requests but only runs its tasks and exits when finished.

After you create or update a job, you can execute the job as a one-off, on a schedule or as part of a workflow. You can manage individual job executions and view the execution logs.

A job can be structured as a single task or as multiple, independent tasks (up to 10,000 tasks) that are executed in parallel. Each task runs one container instance and can be configured to retry in case of failure. Each task is aware of its index, which is stored in the CLOUD_RUN_TASK_INDEX environment variable. If you are processing data in parallel, your code is responsible for determining which task handles which subset of the data.

All tasks in a job execution must complete successfully for the job execution to be successful. You can set timeouts on tasks and specify the number of retries in case of task failure. If any task exceeds its maximum number of retries, that task is marked as failed and the job is marked as failed. By default, tasks execute in parallel.

By default each task runs for a maximum of 10 minutes: you can change this to a shorter time or a longer time up to 1 hour, by changing the task timeout setting. There is no explicit timeout for a job execution: after all tasks are complete, the job execution is complete.

Jobs use the second generation execution environment.

Permissions required to create and execute

You must have ONE of the following:

Supported container registries and images

You can use container images stored in Container Registry or Artifact Registry. You can use only the following types of container images:

If you are storing container images in another type of container registry, follow the instructions under deploying images from unsupported registries.

Creating a new job

You can create a new job using the gcloud command line.

Command line

To use the command line, you need to have already set up the gcloud CLI.

To create a new job:

  1. Run the command:

    gcloud beta run jobs create JOB_NAME --image IMAGE_URL OPTIONS

    • Replace JOB_NAME with the name of the job you want to create. You can omit this parameter, but you will be prompted for the job name if you omit it.
    • Replace IMAGE_URL with a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/job:latest.
    • Optionally, replace OPTIONS with any of the following options:

      Option Description
      --tasks Accepts integers greater or equal to 1. Defaults to 1; maximum is 10,000. Each task is provided the environment variables CLOUD_RUN_TASK_INDEX with a value between 0 and the number of tasks minus 1, along with CLOUD_RUN_TASK_COUNT, which is the number of tasks
      --max-retries The number of times a failed task is retried. Once any task fails beyond this limit, the entire job is marked as failed. For example, if set to 1, a failed task will be retried once, for a total of two attempts. The default is 3. Accepts integers from 0 to 10.
      --task-timeout Accepts a duration like "2s". Defaults to 10 minutes; maximum is 1h.
      --parallelism The maximum number of tasks that can execute in parallel. By default, tasks will be started as quickly as possible in parallel. Refer to Parallelism for the range of values.
      --execute-now If set, immediately after the job is created, a job execution is started. Equivalent to calling gcloud beta run jobs create followed by gcloud beta run jobs execute.

      In addition to the above options, you can set other optional configuration settings:

  2. Wait for the job creation to finish. Upon successful completion, a success message is displayed

  3. To execute the job see execute jobs or execute jobs on a schedule.

Cloud Run locations

Cloud Run is regional, which means the infrastructure that runs your Cloud Run services is located in a specific region and is managed by Google to be redundantly available across all the zones within that region.

Meeting your latency, availability, or durability requirements are primary factors for selecting the region where your Cloud Run services are run. You can generally select the region nearest to your users but you should consider the location of the other Google Cloud products that are used by your Cloud Run service. Using Google Cloud products together across multiple locations can affect your service's latency as well as cost.

Cloud Run is available in the following regions:

Subject to Tier 1 pricing

  • asia-east1 (Taiwan)
  • asia-northeast1 (Tokyo)
  • asia-northeast2 (Osaka)
  • europe-north1 (Finland) leaf icon Low CO2
  • europe-southwest1 (Madrid) leaf icon Low CO2
  • europe-west1 (Belgium) leaf icon Low CO2
  • europe-west4 (Netherlands)
  • europe-west8 (Milan)
  • europe-west9 (Paris) leaf icon Low CO2
  • us-central1 (Iowa) leaf icon Low CO2
  • us-east1 (South Carolina)
  • us-east4 (Northern Virginia)
  • us-west1 (Oregon) leaf icon Low CO2

Subject to Tier 2 pricing

  • asia-east2 (Hong Kong)
  • asia-northeast3 (Seoul, South Korea)
  • asia-southeast1 (Singapore)
  • asia-southeast2 (Jakarta)
  • asia-south1 (Mumbai, India)
  • asia-south2 (Delhi, India)
  • australia-southeast1 (Sydney)
  • australia-southeast2 (Melbourne)
  • europe-central2 (Warsaw, Poland)
  • europe-west2 (London, UK)
  • europe-west3 (Frankfurt, Germany)
  • europe-west6 (Zurich, Switzerland) leaf icon Low CO2
  • northamerica-northeast1 (Montreal) leaf icon Low CO2
  • northamerica-northeast2 (Toronto) leaf icon Low CO2
  • southamerica-east1 (Sao Paulo, Brazil) leaf icon Low CO2
  • southamerica-west1 (Santiago, Chile)
  • us-west2 (Los Angeles)
  • us-west3 (Salt Lake City)
  • us-west4 (Las Vegas)

If you already created a Cloud Run service, you can view the region in the Cloud Run dashboard in the Cloud console.

When you create a new job, the Cloud Run service agent needs to be able to access the container, which is the case by default.

Updating an existing job

You can update an existing job using the Cloud console, or the gcloud command line.

Note that changing any configuration settings requires you to update the job, even if there is no change to the container image.

Click the tab for instructions using the tool of your choice.

Command line

To use the command line, you need to have already set up the gcloud CLI.

  1. Run the command:

    gcloud beta run jobs update JOB_NAME

    Replace

    • JOB_NAME with the name of the job you want to update.
    • Optionally, replace OPTIONS with the following options:

      Option Description
      --tasks Accepts integers equal or greater than 1. Defaults to 1; maximum is 10,000. Each task is provided the environment variables CLOUD_RUN_TASK_INDEX with a value between 0 and the number of tasks minus 1, along with CLOUD_RUN_TASK_COUNT, which is the number of tasks
      --max-retries The number of times a failed task is retried. Once any task fails beyond this limit, the entire job is marked as failed. For example, if set to 1, a failed task will be retried once, for a total of two attempts. The default is 3. Accepts integers from 0 to 10.
      --task-timeout Accepts a duration like "2s". Defaults to 10 minutes; maximum is 1h.
      --parallelism The maximum number of tasks that can execute in parallel. By default, tasks will be started as quickly as possible, in parallel. Refer to Parallelism for the range of values.
      --execute-now If set, the job will execute immediately after it is created. Equivalent to calling gcloud beta run jobs create and gcloud beta run jobs execute

    In addition to the above options, you can set other optional configuration settings:

    For a full list of available options when creating a job, refer to the gcloud beta run jobs create command line documentation.

  2. Wait for the job update to finish. Upon successful completion, a success message is displayed, similar to the following:

    Job [JOB_NAME] has been successfully updated.
    View details about this job by running `gcloud beta run jobs describe JOB_NAME`.
    See logs for this execution at: https://console.cloud.google.com/logs/viewer?project=PROJECT_ID&resource=cloud_run_revision/service_name/JOB_NAME
    
  3. To execute the job see execute jobs or execute jobs on a schedule.

Cloud Run locations

Cloud Run is regional, which means the infrastructure that runs your Cloud Run services is located in a specific region and is managed by Google to be redundantly available across all the zones within that region.

Meeting your latency, availability, or durability requirements are primary factors for selecting the region where your Cloud Run services are run. You can generally select the region nearest to your users but you should consider the location of the other Google Cloud products that are used by your Cloud Run service. Using Google Cloud products together across multiple locations can affect your service's latency as well as cost.

Cloud Run is available in the following regions:

Subject to Tier 1 pricing

  • asia-east1 (Taiwan)
  • asia-northeast1 (Tokyo)
  • asia-northeast2 (Osaka)
  • europe-north1 (Finland) leaf icon Low CO2
  • europe-southwest1 (Madrid) leaf icon Low CO2
  • europe-west1 (Belgium) leaf icon Low CO2
  • europe-west4 (Netherlands)
  • europe-west8 (Milan)
  • europe-west9 (Paris) leaf icon Low CO2
  • us-central1 (Iowa) leaf icon Low CO2
  • us-east1 (South Carolina)
  • us-east4 (Northern Virginia)
  • us-west1 (Oregon) leaf icon Low CO2

Subject to Tier 2 pricing

  • asia-east2 (Hong Kong)
  • asia-northeast3 (Seoul, South Korea)
  • asia-southeast1 (Singapore)
  • asia-southeast2 (Jakarta)
  • asia-south1 (Mumbai, India)
  • asia-south2 (Delhi, India)
  • australia-southeast1 (Sydney)
  • australia-southeast2 (Melbourne)
  • europe-central2 (Warsaw, Poland)
  • europe-west2 (London, UK)
  • europe-west3 (Frankfurt, Germany)
  • europe-west6 (Zurich, Switzerland) leaf icon Low CO2
  • northamerica-northeast1 (Montreal) leaf icon Low CO2
  • northamerica-northeast2 (Toronto) leaf icon Low CO2
  • southamerica-east1 (Sao Paulo, Brazil) leaf icon Low CO2
  • southamerica-west1 (Santiago, Chile)
  • us-west2 (Los Angeles)
  • us-west3 (Salt Lake City)
  • us-west4 (Las Vegas)

If you already created a Cloud Run service, you can view the region in the Cloud Run dashboard in the Cloud console.

What's next

After you create or update a job, you can do the following: