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.

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.

Command line

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

Replace JOB_NAME with the name of the job.

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

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. You need the run.jobs.runWithOverrides permission to use this feature. The Cloud Run Admin and Cloud Run Developer roles have this permission.

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.

Command line

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:

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. Locate the job execution you want to cancel.

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

  4. Click Cancel.

Command line

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.

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: