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 or Google Cloud CLI.

Console

To execute a job:

  1. Go to the Cloud Run jobs page

  2. Locate the job you are interested in.

  3. Click the job to display the job details page.

  4. 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:

  • JOB_NAME with the name of the job.
  • REGION with the region in which the resource can be found. 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:

  • ACCESS_TOKEN with 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 with the name of the job.
  • REGION with the Google Cloud region of the job.
  • PROJECT-ID with the Google Cloud project ID.

Execute jobs immediately on job creation

If you use the command line, you can specify job execution immediately after you create a job:

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

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

  1. Go to the Cloud Run jobs page

  2. Locate the job you are interested in.

  3. Click the job to display the job details page.

  4. Click the expander arrow in front of the Edit button and click Execute with overrides to display the Execute job with overrides form.

    image

  5. 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

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": TASK-COUNT, "timeout": "TIMEOUT" }}' \
  https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB-NAME:run

Replace:

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

  1. Go to the Cloud Run jobs page

  2. Click the job to open the job details pane.

  3. Select the job execution you want to cancel.

  4. 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:

  • ACCESS_TOKEN with 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 with the name of the job.
  • EXECUTION-NAME with the name of the job execution.
  • REGION with the Google Cloud region of the job.
  • PROJECT-ID with 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: