Execute jobs

This page describes how to execute Cloud Run jobs. Executing a job creates a job execution in which all tasks must run to completion successfully in order for the job execution to be successful. Job executions write logs to Cloud Logging and send monitoring data to Cloud Monitoring.

In addition to these logging features, you can also view job execution details for the most recent 1,000 executions of a job using the execution details pane, along with any executions that occurred within the last seven days. Older execution details are removed and are no longer visible in the execution details pane. However, the logs and monitoring data for older executions are still available in Cloud Logging and Cloud Monitoring, subject to the retention policies for those products.

Required roles

To get the permissions that you need for the operations described on this page, ask your administrator to grant you one of the following IAM roles on your Cloud Run job:

To execute jobs using the Google Cloud CLI: Cloud Run Invoker (roles/run.invoker) on the Cloud Run job
To execute jobs using the Google Cloud console, to override job configurations, or to cancel job executions: Cloud Run Developer (roles/run.developer) on the Cloud Run job

For a list of IAM roles and permissions that are associated with Cloud Run, see Cloud Run IAM roles and Cloud Run IAM permissions. If your Cloud Run job interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the service identity configuration guide. For more information about granting roles, see deployment permissions and manage access.

Execute jobs

You can execute jobs using the Google Cloud console, the Google Cloud CLI, client libraries, or REST API.

Console

To execute a job:

In the Google Cloud console, go to the Cloud Run Jobs page:

Go to Cloud Run jobs
Locate the job you are interested in.
Click the job to display the job details page.
Click Execute.

gcloud

To execute an existing job:

gcloud run jobs execute JOB_NAME

If you want the command to wait until the execution completes, use

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

Replace the following:

JOB_NAME: the name of the job.
REGION: the region in which the resource can be found. For example, europe-west1. Alternatively, set the run/region property.

Client libraries

To execute an existing job from code:

REST API

To execute an existing job, send a POST HTTP request to the jobs.run API method.

For example, using curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB_NAME:run

Replace the following:

ACCESS_TOKEN: a valid access token for an account that has the IAM permissions to execute a job. For example, if you are logged into gcloud, you can retrieve an access token using gcloud auth print-access-token. From within a Cloud Run container instance, you can retrieve an access token using the container instance metadata server.
JOB_NAME: the name of the job.
REGION: the Google Cloud region of the job.
PROJECT_ID: the Google Cloud project ID.

Execute jobs immediately

Console

To execute a job immediately:

In the Google Cloud console, go to the Cloud Run Jobs page:

Go to Cloud Run jobs
If you have an existing job, click the job to display the job details page, then select View & edit job configuration. If you are creating a new job, select Deploy container.
Go to the bottom of the page and check the Execute job immediately box before creating or updating the job.

gcloud

You can specify the --execute-now flag when creating or updating a job:

Creating a job:

gcloud run jobs create JOB_NAME \
  --image IMAGE_URL \
  --execute-now \
  --region=REGION

Updating a job:

gcloud run jobs update JOB_NAME --execute-now --region=REGION

Replace the following:

JOB_NAME: the name of the job.
IMAGE_URL: a reference to the container image—for example, us-docker.pkg.dev/cloudrun/container/job:latest.
REGION: the region in which the resource can be found. For example, europe-west1.

YAML

You can store your job specification in a YAML file and then deploy it using the gcloud CLI.

If you are creating a new job, skip this step. If you are updating an existing job, download its YAML configuration:
```
gcloud run jobs describe JOB_NAME --format export > job.yaml
```
Configure the startExecutionToken attribute as shown:
```
apiVersion: run.googleapis.com/v2
kind: Job
metadata:
  name: JOB_NAME
spec:
  template:
    spec:
      template:
        spec:
          containers:
          - image: IMAGE_URL
  startExecutionToken: START_EXECUTION_SUFFIX
```
Replace the following:
- JOB_NAME: the name of your Cloud Run job. Job names must be 49 characters or less and must be unique per region and project.
- IMAGE_URL: a reference to the container image—for example, us-docker.pkg.dev/cloudrun/container/job:latest.
- START_EXECUTION_SUFFIX: a unique string used as a suffix for creating a new execution. The job will become ready when the execution is successfully started. The sum of job name and token length must be fewer than 63 characters.
You can also specify more configuration such as environment variables or memory limits.
Create or update the job using the following command:
```
gcloud run jobs replace job.yaml
```

Terraform

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

Add the following to a google_cloud_run_v2_job resource in your Terraform configuration:

resource "google_cloud_run_v2_job" "default" {
   provider = google-beta
   name     = "cloudrun-job"
   location = "REGION"
   deletion_protection = false
   start_execution_token = "START_EXECUTION_SUFFIX"
   template {
      template {
         containers {
         image = "us-docker.pkg.dev/cloudrun/container/job"
         }
      }
   }
}

Replace the following:

REGION: the Google Cloud region. For example, europe-west1.
START_EXECUTION_SUFFIX: a unique string used as a suffix for creating a new execution. The job will become ready when the execution is successfully started. The sum of job name and token length must be fewer than 63 characters.

Client libraries

To immediately execute a job from code using Cloud Client Libraries:

REST API

To execute jobs immediately on creation, send a POST HTTP request to the Cloud Run Admin API jobs endpoint.

For example, using curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '{
     "template": {
        "template": {
           "containers":
              {
                 "image": "IMAGE_URL"
              }
        }
     },
     "startExecutionToken": "START_EXECUTION_SUFFIX"
  }' \
  "https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs?jobId=JOB_NAME"

Replace the following:

ACCESS_TOKEN: a valid access token for an account that has the IAM permissions to create jobs. For example, if you are logged into gcloud, you can retrieve an access token using gcloud auth print-access-token. From within a Cloud Run container instance, you can retrieve an access token using the container instance metadata server.
IMAGE_URL: a reference to the container image—for example, us-docker.pkg.dev/cloudrun/container/job:latest.
START_EXECUTION_SUFFIX: a unique string used as a suffix for creating a new execution. The job will become ready when the execution is successfully started. The sum of job name and token length must be fewer than 63 characters.
PROJECT_ID: the Google Cloud project ID.
REGION: the Google Cloud region of the job.
JOB_NAME: the name of the job you want to create.

Override job configuration for a specific execution

You can override the arguments, environment variables, number of tasks, and task timeout configured for a job when you execute a job by setting these parameters when you start a new job execution. The parameters you specify affect only this execution and not subsequent ones, because the underlying job definition remains unchanged.

Some common use cases include:

You execute the job programmatically from your code, and want to override arguments and/or environment variables, for example to tell the job where the input data is located for this execution.
You have a job where each task is intended to only process one piece of input data. You want to override the number of tasks based on the number of inputs to be processed.
The running time of your job varies between executions. You want to override the task timeout based on the expected running time of the job.

To override job configuration for an execution:

Console

Go to the Cloud Run jobs page
Locate the job you are interested in.
Click the job to display the job details page.
Click the expander arrow in front of the Edit button and click Execute with overrides to display the Execute job with overrides form.
Change the arguments, environment variables, number of tasks, and/or task timeout configuration for this execution as desired, then click Execute.

gcloud

Use the command:

gcloud run jobs execute JOB_NAME \
     --args ARGS \
     --update-env-vars KEY=VALUE>,KEY_N=VALUE_N \
     --tasks TASKS \
     --task-timeout TIMEOUT

Replace the following:

JOB_NAME: the name of the job.
ARGS: the job arguments.
KEY and VALUE pairs: the environment variables.
TASKS: the number of tasks.
TIMEOUT: the task timeout.

Client libraries

To execute an existing job from code, overriding the job configuration:

REST API

To override job configuration for an existing job, send a POST HTTP request to request to the Cloud Run Admin API jobs endpoint

For example, using curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '{"overrides": {"containerOverrides": [{"args": ["ARGS"], "env": [{"name": "KEY", "value": "VALUE"}]}], "taskCount": TASKS, "timeout": "TIMEOUT" }}' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB_NAME:run

Replace the following:

ACCESS_TOKEN: a valid access token for an account that has the IAM permissions to execute job overrides. For example, if you are logged into gcloud, you can retrieve an access token using gcloud auth print-access-token. From within a Cloud Run container instance, you can retrieve an access token using the container instance metadata server.
JOB_NAME: the name of the job.
ARGS: job arguments.
KEY and VALUE pairs: environment variables.
TASKS: the number of tasks.
TIMEOUT: the task timeout.
REGION: the Google Cloud region of the job.
PROJECT_ID: the Google Cloud project ID.

Cancel job execution

To stop a currently running Cloud Run job execution, use the cancel feature. Cancelling a job execution stops the current job execution. Cancelled executions have the status cancelled. You will still be able to view the execution, including its configuration data, logs, and monitoring data.

Cancelling a job execution does not reverse the charges for any Cloud Run jobs usage for the time that the job was executing.

To cancel an execution:

Console

Go to the Cloud Run jobs page
Click the job to open the job details pane.
Select the job execution you want to cancel.
Under the Actions menu, click the ellipsis icon, then click Cancel.

gcloud

Use the command:

gcloud run jobs executions cancel EXECUTION_NAME

Replace EXECUTION_NAME with the name of the execution.

This command asks for confirmation, so respond to the prompt by entering y to confirm.

Client libraries

To cancel a job execution from code:

REST API

To cancel a job execution, send a POST HTTP request to request to the Cloud Run Admin API jobs endpoint

For example, using curl:

curl -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -X POST \
  -d '' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB_NAME/executions/EXECUTION-NAME:cancel

Replace the following:

ACCESS_TOKEN: a valid access token for an account that has the IAM permissions to cancel job executions. For example, if you are logged into gcloud, you can retrieve an access token using gcloud auth print-access-token. From within a Cloud Run container instance, you can retrieve an access token using the container instance metadata server.
JOB_NAME: the name of the job.
EXECUTION-NAME: the name of the job execution.
REGION: the Google Cloud region of the job.
PROJECT_ID: the Google Cloud project ID.

Delete a job execution

You can delete a job execution, even if it is currently executing. If you delete an execution, it stops the execution from continuing. For details, see Delete a job execution.

What's next

After you execute a job, you can do the following:

Execute jobs Stay organized with collections Save and categorize content based on your preferences.

Required roles

Execute jobs

Console

gcloud

Client libraries

REST API

Execute jobs immediately

Console

gcloud

YAML

Terraform

Client libraries

REST API

Override job configuration for a specific execution

Console

gcloud

Client libraries

REST API

Cancel job execution

Console

gcloud

Client libraries

REST API

Delete a job execution

What's next

Execute jobs