[Video](https://www.youtube.com/watch?v=e07TvWMmVI8) This page describes how to create and update Cloud Run jobs from an existing container image. Unlike a Cloud Run service, which listens for and serves requests, a Cloud Run job only runs its tasks and exits when finished. A job does not listen for or serve requests. After you create or update a job, you can do the following: - [Execute the job](https://docs.cloud.google.com/run/docs/execute/jobs) as a one-off, [on a schedule](https://docs.cloud.google.com/run/docs/execute/jobs-on-schedule), or as part of a [workflow](https://docs.cloud.google.com/run/docs/triggering/invoke-jobs-with-workflows). - [Override parameters](https://docs.cloud.google.com/run/docs/execute/jobs#override-job-configuration) configured for a job when you execute a job. - [Manage individual job executions](https://docs.cloud.google.com/run/docs/managing/job-executions) and view the execution logs. You can structure a job as a single task or as multiple, independent tasks (up to 10,000 tasks) that can be 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. The overall count of tasks is stored in the `CLOUD_RUN_TASK_COUNT` environment variable. If you are processing data in parallel, your code is responsible for determining which task handles which subset of the data. 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* . If any tasks failed, the job execution is marked as *failed* after Cloud Run has tried all of the tasks. By default, each task runs for a maximum of 10 minutes. You can modify the default value by [changing the task timeout setting](https://docs.cloud.google.com/run/docs/configuring/task-timeout), up to 168 hours (7 days). For tasks using GPUs, the maximum available timeout is 12 hours. 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](https://docs.cloud.google.com/run/docs/about-execution-environments). ## Required roles To get the permissions that you need to create Cloud Run jobs, ask your administrator to grant you the following IAM roles: - [Cloud Run Developer](https://docs.cloud.google.com/iam/docs/roles-permissions/run#run.developer) (`roles/run.developer`) on the Cloud Run job - [Service Account User](https://docs.cloud.google.com/iam/docs/roles-permissions/iam#iam.serviceAccountUser) (`roles/iam.serviceAccountUser`) on the service identity - [Artifact Registry Reader](https://docs.cloud.google.com/iam/docs/roles-permissions/artifactregistry#artifactregistry.reader) (`roles/artifactregistry.reader`) on the Artifact Registry repository of the container images of the job For a list of IAM roles and permissions that are associated with Cloud Run, see [Cloud Run IAM roles](https://docs.cloud.google.com/run/docs/reference/iam/roles) and [Cloud Run IAM permissions](https://docs.cloud.google.com/run/docs/reference/iam/permissions). If your Cloud Run job interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the [service identity configuration guide](https://docs.cloud.google.com/run/docs/configuring/jobs/service-identity). For more information about granting roles, see [deployment permissions](https://docs.cloud.google.com/run/docs/reference/iam/roles#additional-configuration) and [manage access](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access). ## Supported container registries and images You can directly use container images stored in [Artifact Registry](https://docs.cloud.google.com/artifact-registry/docs/overview), or public images from [Docker Hub](https://hub.docker.com/) or [GitHub Container Registry](https://ghcr.io/). Google recommends the use of Artifact Registry. Public images from GitHub Container Registry and [Docker Hub images](https://docs.cloud.google.com/artifact-registry/docs/pull-cached-dockerhub-images) are cached for up to one hour. You can use container images from other public or private registries (like JFrog Artifactory or Nexus), or private images from GitHub Container Registry, by setting up an [Artifact Registry remote repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/remote-repo). You should only consider [Docker Hub](https://hub.docker.com/) for deploying popular container images such as [Docker Official Images](https://docs.docker.com/docker-hub/official_images/) or [Docker Sponsored OSS images](https://docs.docker.com/docker-hub/dsos-program/). For higher availability, Google recommends deploying these Docker Hub or GitHub Container Registry images using an [Artifact Registry remote repository](https://docs.cloud.google.com/artifact-registry/docs/repositories/remote-repo). Cloud Run does not support container image layers larger than 9.9 GB when deploying from Docker Hub or an Artifact Registry remote repository with an external registry. ## Create a new job You can create a new job using the Google Cloud console, the gcloud CLI, YAML, Terraform, client libraries, or the REST API: ### Console To create a new job, follow these steps: 1. In the Google Cloud console, go to the Cloud Run jobs page: [Go to Cloud Run jobs](https://console.cloud.google.com/run/jobs) 2. Click **Deploy container** to display the **Create job** form. 3. In the form, specify the container image containing the job code or select from a list of containers previously deployed. 4. The job name is automatically generated from the container image. You can edit the job name as needed on the form. After you submit the form, you can't edit the name of the job. 5. In the **Region** field, select the [region](https://docs.cloud.google.com/run/docs/run/docs/locations) for your job. The region selector highlights regions with the [lowest carbon impact](https://cloud.google.com/sustainability/region-carbon#region-picker). 6. Specify the number of tasks to run in the job. All of the tasks must succeed for the job to succeed. By default, the tasks execute in parallel. 7. Click **Containers, Networking, Security** to set additional job properties. 8. In the **Edit container** section, optionally configure the following settings in the appropriate tabs: - [Container configuration](https://docs.cloud.google.com/run/docs/configuring/jobs/containers) - [CPU limits](https://docs.cloud.google.com/run/docs/configuring/jobs/cpu) - [Memory limits](https://docs.cloud.google.com/run/docs/configuring/jobs/memory-limits) - [Secrets](https://docs.cloud.google.com/run/docs/configuring/jobs/secrets) - [Environment variables](https://docs.cloud.google.com/run/docs/configuring/jobs/environment-variables) - [Labels](https://docs.cloud.google.com/run/docs/configuring/jobs/labels) - [Service accounts](https://docs.cloud.google.com/run/docs/configuring/jobs/service-identity) - [Cloud SQL connections](https://docs.cloud.google.com/run/docs/configuring/connect-cloudsql) - [VPC connectivity](https://docs.cloud.google.com/run/docs/configuring/connecting-vpc) 9. In the **Task capacity** section, specify the following: 1. In the **Task timeout** field, specify the maximum amount of time in seconds that the task can run, up to 168 hours (7 days). For tasks using GPUs, the maximum available timeout is 12 hours. Each task must complete within this time. The default is 10 minutes. 2. In the **Number of retries per failed task** field, specify the number of retries in case of task failures. The default is 3 retries. 10. Under **Parallelism** , select **Run as many tasks concurrently as possible** if you need to set a lower limit due to scaling constraints on resources your job accesses, or select **Limit the maximum number of concurrent tasks** and specify the number of concurrent tasks in the **Custom parallelism limit** field. 11. When you are finished configuring your job, click **Create** to create the job in Cloud Run. 12. To execute the job, see [execute jobs](https://docs.cloud.google.com/run/docs/execute/jobs) or [execute jobs on a schedule](https://docs.cloud.google.com/run/docs/execute/jobs-on-schedule). ### gcloud To use the command line, you need to have already [set up the gcloud CLI](https://docs.cloud.google.com/run/docs/setup). To create a new job, follow these steps: 1. Run the command: ```bash gcloud run jobs create JOB --image IMAGE_URL OPTIONS ``` Alternatively, use the deploy command: ```bash gcloud run jobs deploy JOB --image IMAGE_URL OPTIONS ```
Replace the following: - `JOB`: the name of your Cloud Run job. - `IMAGE_URL`: a reference to the [container image](https://docs.cloud.google.com/run/docs/building/containers)---for example, `us-docker.pkg.dev/cloudrun/container/job:latest`. - `OPTIONS` (Optional): 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 168 hours (7 days). For tasks using GPUs, the maximum available timeout is 12 hours. | | `--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](https://docs.cloud.google.com/run/docs/configuring/parallelism) for the range of values. | | `--execute-now` | If set, immediately after the job is created, a [job execution](https://docs.cloud.google.com/run/docs/execute/jobs) is started. Equivalent to calling `gcloud run jobs create` followed by `gcloud run jobs execute`. | In addition to the preceding options, you also specify more configuration such as environment variables or memory limits. For a full list of available options when creating a job, refer to the [gcloud run jobs create](https://docs.cloud.google.com/sdk/gcloud/reference/run/jobs/create) command line documentation. 2. Wait for the job creation to finish. You'll see a success message upon a successful completion. 3. To execute the job, see [execute jobs](https://docs.cloud.google.com/run/docs/execute/jobs) or [execute jobs on a schedule](https://docs.cloud.google.com/run/docs/execute/jobs-on-schedule). ### YAML You can store your job specification in a `YAML` file and then deploy it using the gcloud CLI. 1. Create a new `job.yaml` file with this content: ```yaml apiVersion: run.googleapis.com/v1 kind: Job metadata: name: JOB spec: template: spec: template: spec: containers: - image: IMAGE_URL ``` Replace the following: - `JOB`: the name of your Cloud Run job. - `IMAGE_URL`: a reference to the [container image](https://docs.cloud.google.com/run/docs/building/containers)---for example, `us-docker.pkg.dev/cloudrun/container/job:latest`. You can also specify more configuration such as environment variables or memory limits. 2. Deploy the new job by running the following command: ```bash gcloud run jobs replace job.yaml ``` ### Terraform To learn how to apply or remove a Terraform configuration, see [Basic Terraform commands](https://docs.cloud.google.com/docs/terraform/basic-commands). Add the following to a [`google_cloud_run_v2_job`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_job) resource in your Terraform configuration: resource "google_cloud_run_v2_job" "default" { name = "cloud-run-job" location = "us-central1" deletion_protection = false # set to "true" in production template { template { containers { image = "us-docker.pkg.dev/cloudrun/container/job:latest" } } } } ### Client libraries To create a job from code: - [Go](https://docs.cloud.google.com/go/docs/reference/cloud.google.com/go/run/latest/apiv2#cloud_google_com_go_run_apiv2_JobsClient_CreateJob) - [Java](https://docs.cloud.google.com/java/docs/reference/google-cloud-run/latest/com.google.cloud.run.v2.JobsClient#com_google_cloud_run_v2_JobsClient_createJobAsync_com_google_cloud_run_v2_LocationName_com_google_cloud_run_v2_Job_java_lang_String_) - [Node.js](https://docs.cloud.google.com/nodejs/docs/reference/run/latest/run/v2.jobsclient#_google_cloud_run_v2_JobsClient_createJob_member_1_) - [Python](https://docs.cloud.google.com/python/docs/reference/run/latest/google.cloud.run_v2.services.jobs.JobsClient#google_cloud_run_v2_services_jobs_JobsClient_create_job) - [Ruby](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-run-v2/latest/Google-Cloud-Run-V2-Jobs-Client#Google__Cloud__Run__V2__Jobs__Client_create_job_instance_) - [PHP](https://docs.cloud.google.com/php/docs/reference/cloud-run/latest/V2.Client.JobsClient#_Google_Cloud_Run_V2_Client_JobsClient__createJob__) - [.NET](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Run.V2/latest/Google.Cloud.Run.V2.JobsClient#Google_Cloud_Run_V2_JobsClient_CreateJob_Google_Api_Gax_ResourceNames_LocationName_Google_Cloud_Run_V2_Job_System_String_Google_Api_Gax_Grpc_CallSettings_) ### REST API To create a job, send a `POST` HTTP request to request to the Cloud Run Admin API [`jobs` endpoint](https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.jobs/create). For example, using `curl`: ```bash curl -H "Content-Type: application/json" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -X POST \ -d '{template: {template: {containers: [{image: "IMAGE_URL"}]}}}' \ https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs?jobId=JOB ``` Replace the following: - `ACCESS_TOKEN`: a valid access token for an account that has the [IAM permissions to create jobs](https://docs.cloud.google.com/run/docs/reference/iam/permissions). 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](https://docs.cloud.google.com/run/docs/container-contract#metadata-server). - `IMAGE_URL`: a reference to the [container image](https://docs.cloud.google.com/run/docs/building/containers)---for example, `us-docker.pkg.dev/cloudrun/container/job:latest`. - `PROJECT_ID`: the Google Cloud project ID. - `REGION`: the Google Cloud region of the job. - `JOB`: the name of the job you want to create. ### 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](https://docs.cloud.google.com/docs/geography-and-regions).
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](https://cloud.google.com/about/locations/#locations) 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](https://cloud.google.com/run/pricing#tables) - `asia-east1` (Taiwan) - `asia-northeast1` (Tokyo) - `asia-northeast2` (Osaka) - `asia-south1` (Mumbai, India) - `asia-southeast3 ` (Bangkok) - `europe-north1` (Finland) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `europe-north2` (Stockholm) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `europe-southwest1` (Madrid) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `europe-west1` (Belgium) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `europe-west4` (Netherlands) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `europe-west8` (Milan) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `europe-west9` (Paris) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `me-west1` (Tel Aviv) - `northamerica-south1` (Mexico) - `us-central1` (Iowa) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `us-east1` (South Carolina) - `us-east4` (Northern Virginia) - `us-east5` (Columbus) - `us-south1` (Dallas) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `us-west1` (Oregon) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) #### Subject to [Tier 2 pricing](https://cloud.google.com/run/pricing#tables) - `africa-south1` (Johannesburg) - `asia-east2` (Hong Kong) - `asia-northeast3` (Seoul, South Korea) - `asia-southeast1` (Singapore) - `asia-southeast2 ` (Jakarta) - `asia-south2` (Delhi, India) - `australia-southeast1` (Sydney) - `australia-southeast2` (Melbourne) - `europe-central2` (Warsaw, Poland) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `europe-west10` (Berlin) - `europe-west12` (Turin) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `europe-west2` (London, UK) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `europe-west3` (Frankfurt, Germany) - `europe-west6` (Zurich, Switzerland) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `me-central1` (Doha) - `me-central2` (Dammam) - `northamerica-northeast1` (Montreal) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `northamerica-northeast2` (Toronto) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `southamerica-east1` (Sao Paulo, Brazil) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `southamerica-west1` (Santiago, Chile) ![leaf icon](https://cloud.google.com/sustainability/region-carbon/gleaf.svg) [Low CO~2~](https://cloud.google.com/sustainability/region-carbon#region-picker) - `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 [Google Cloud console](https://console.cloud.google.com/run). When you create a new job, the Cloud Run [service agent](https://docs.cloud.google.com/iam/docs/service-agents) needs to be able to access the container, which is the case by default. ## Update an existing job Changing any configuration settings requires you to update the job, even if there is no change to the container image. Note that for any unchanged settings, the previous settings continue to be used. You can update an existing job using the Google Cloud console, the gcloud CLI, YAML, Terraform, client libraries, or the REST API: ### Console To update an existing job, follow these steps: 1. In the Google Cloud console, go to the Cloud Run jobs page: [Go to Cloud Run jobs](https://console.cloud.google.com/run/jobs) 2. Click the job to display the **Job details** page. 3. Click **View and edit job configuration**. 4. Optional: Change the number of tasks that are in the job if needed. 5. Optional: Click **Containers, Networking, Security** to update any additional job properties: - [Container configuration](https://docs.cloud.google.com/run/docs/configuring/jobs/containers) - [CPU limits](https://docs.cloud.google.com/run/docs/configuring/jobs/cpu) - [Memory limits](https://docs.cloud.google.com/run/docs/configuring/jobs/memory-limits) - [Secrets](https://docs.cloud.google.com/run/docs/configuring/jobs/secrets) - [Environment variables](https://docs.cloud.google.com/run/docs/configuring/jobs/environment-variables) - [Labels](https://docs.cloud.google.com/run/docs/configuring/jobs/labels) - [Service accounts](https://docs.cloud.google.com/run/docs/configuring/jobs/service-identity) - [Cloud SQL connections](https://docs.cloud.google.com/run/docs/configuring/connect-cloudsql) - [VPC connectivity](https://docs.cloud.google.com/run/docs/configuring/connecting-vpc) 6. In the **Task capacity** section, specify the following: 1. In the **Task timeout** field, specify the maximum amount of time in seconds that the task can run, up to 168 hours (7 days). For tasks using GPUs, the maximum available timeout is 12 hours. Each task must complete within this time. The default is 10 minutes. 2. In the **Number of retries per failed task** field, specify the number of retries in case of task failures. The default is 3 retries. 7. Under **Parallelism** , select **Run as many tasks concurrently as possible** if you need to set a lower limit due to scaling constraints on resources your job accesses, or select **Limit the maximum number of concurrent tasks** and specify the number of concurrent tasks in the **Custom parallelism limit** field. 8. When you are finished configuring your job, click **Update** to modify the job in Cloud Run and wait for the job creation to finish. 9. To execute the job, see [execute jobs](https://docs.cloud.google.com/run/docs/execute/jobs) or [execute jobs on a schedule](https://docs.cloud.google.com/run/docs/execute/jobs-on-schedule). ### gcloud 1. In the Google Cloud console, activate Cloud Shell. [Activate Cloud Shell](https://console.cloud.google.com/?cloudshell=true) At the bottom of the Google Cloud console, a [Cloud Shell](https://docs.cloud.google.com/shell/docs/how-cloud-shell-works) session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize. 2. Run the following command: ```bash gcloud run jobs update JOB ```
Replace the following: - `JOB`: the name of your Cloud Run job. - `OPTIONS` (Optional): 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 168 hours (7 days). | | `--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](https://docs.cloud.google.com/run/docs/configuring/parallelism) for the range of values. | In addition to the previous options, you can set other optional configuration settings: - [Container configuration](https://docs.cloud.google.com/run/docs/configuring/jobs/containers) - [CPU limits](https://docs.cloud.google.com/run/docs/configuring/jobs/cpu) - [Memory limits](https://docs.cloud.google.com/run/docs/configuring/jobs/memory-limits) - [Secrets](https://docs.cloud.google.com/run/docs/configuring/jobs/secrets) - [Environment variables](https://docs.cloud.google.com/run/docs/configuring/jobs/environment-variables) - [Labels](https://docs.cloud.google.com/run/docs/configuring/jobs/labels) - [Service accounts](https://docs.cloud.google.com/run/docs/configuring/jobs/service-identity) - [Cloud SQL connections](https://docs.cloud.google.com/run/docs/configuring/connect-cloudsql) - [VPC connection](https://docs.cloud.google.com/run/docs/configuring/connecting-vpc) For a full list of available options when creating a job, refer to the [gcloud run jobs create](https://docs.cloud.google.com/sdk/gcloud/reference/run/jobs/create) command line documentation. 3. Wait for the job update to finish. Upon successful completion, a success message is displayed, similar to the following: ```bash Job [JOB] has been successfully updated. View details about this job by running `gcloud run jobs describe JOB`. See logs for this execution at: https://console.cloud.google.com/logs/viewer?project=PROJECT_ID&resource=cloud_run_revision/service_name/JOB ``` 4. To execute the job, see [execute jobs](https://docs.cloud.google.com/run/docs/execute/jobs) or [execute jobs on a schedule](https://docs.cloud.google.com/run/docs/execute/jobs-on-schedule). ### YAML > [!CAUTION] > **Caution:** The following instructions replaces your existing job configuration with the one specified in the YAML file. So if you use YAML to make changes, you should avoid also using the Google Cloud console or gcloud CLI to make configuration changes because those can be overwritten when you use YAML. 1. If you need to download or view the configuration of an existing job, run the following command to save results to a YAML file: ```bash gcloud run jobs describe JOB --format export > job.yaml ``` 2. Modify any `spec.template` child attributes as needed, then redeploy by running the following command: ```bash gcloud run jobs replace job.yaml ``` The `gcloud run jobs replace` command defaults to using `job.yaml` file if present. 3. To execute the job, see [execute jobs](https://docs.cloud.google.com/run/docs/execute/jobs) or [execute jobs on a schedule](https://docs.cloud.google.com/run/docs/execute/jobs-on-schedule). ### Terraform Make changes to your job configuration in your `main.tf` file using the `terraform apply` command. Detailed Terraform instructions are available for: - [Parallelism](https://docs.cloud.google.com/run/docs/configuring/parallelism#terraform) - [Max retries](https://docs.cloud.google.com/run/docs/configuring/max-retries#terraform) - [Timeouts](https://docs.cloud.google.com/run/docs/configuring/task-timeout#terraform) For more information, refer to the [`terraform apply`](https://developer.hashicorp.com/terraform/cli/commands/apply) command line options. ### Client libraries To update an existing job from code: - [Go](https://docs.cloud.google.com/go/docs/reference/cloud.google.com/go/run/latest/apiv2#cloud_google_com_go_run_apiv2_JobsClient_UpdateJob) - [Java](https://docs.cloud.google.com/java/docs/reference/google-cloud-run/latest/com.google.cloud.run.v2.JobsClient#com_google_cloud_run_v2_JobsClient_updateJobAsync_com_google_cloud_run_v2_Job_) - [Node.js](https://docs.cloud.google.com/nodejs/docs/reference/run/latest/run/v2.jobsclient#_google_cloud_run_v2_JobsClient_updateJob_member_1_) - [Python](https://docs.cloud.google.com/python/docs/reference/run/latest/google.cloud.run_v2.services.jobs.JobsClient#google_cloud_run_v2_services_jobs_JobsClient_update_job) - [Ruby](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-run-v2/latest/Google-Cloud-Run-V2-Jobs-Client#Google__Cloud__Run__V2__Jobs__Client_update_job_instance_) - [PHP](https://docs.cloud.google.com/php/docs/reference/cloud-run/latest/V2.Client.JobsClient#_Google_Cloud_Run_V2_Client_JobsClient__updateJob__) - [.NET](https://docs.cloud.google.com/dotnet/docs/reference/Google.Cloud.Run.V2/latest/Google.Cloud.Run.V2.JobsClient#Google_Cloud_Run_V2_JobsClient_UpdateJob_Google_Cloud_Run_V2_Job_Google_Api_Gax_Grpc_CallSettings_) ### REST API To update a job, send a `PATCH` HTTP request to request to the Cloud Run Admin API [`jobs` endpoint](https://docs.cloud.google.com/run/docs/reference/rest/v2/projects.locations.jobs/patch). For example, using `curl`: ```bash curl -H "Content-Type: application/json" \ -H "Authorization: Bearer ACCESS_TOKEN" \ -X PATCH \ -d '{template: {template: {containers: [{image: "IMAGE_URL"}]}}}' \ https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB ``` Replace the following: - `ACCESS_TOKEN`: a valid access token for an account that has the [IAM permissions to update jobs](https://docs.cloud.google.com/run/docs/reference/iam/permissions). 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](https://docs.cloud.google.com/run/docs/container-contract#metadata-server). - `IMAGE_URL`: a reference to the [container image](https://docs.cloud.google.com/run/docs/building/containers)---for example, `us-docker.pkg.dev/cloudrun/container/job:latest`. - `PROJECT_ID`: the Google Cloud project ID. - `REGION`: the Google Cloud region of the job. - `JOB`: the name of your job you want to update. ## Sample code For code samples showing jobs, see the [language-specific quickstarts](https://docs.cloud.google.com/run/docs/quickstarts#build-and-create-a-job). ## Deploy multiple containers to a job (sidecars) In a Cloud Run job deployment with multiple containers (sidecars), there is one main job container that encapsulates the job configuration and one or more *sidecar* containers. You can deploy up to 10 containers per instance including the main job container. All containers within an instance share the same network namespace and can share files using an in-memory shared volume. ### Use cases Sidecars are commonly used for the following use cases: - Fetching custom metrics from Cloud Run jobs and sending them to a specified backend of your choice using collector agents, such as [Prometheus](https://docs.cloud.google.com/stackdriver/docs/managed-prometheus/cloudrun-sidecar) or [Opentelemetry](https://docs.cloud.google.com/run/docs/tutorials/custom-metrics-opentelemetry-sidecar). - Letting applications without Hashicorp Vault logic built in to use static and dynamic secrets sourced from Vault using [Vault sidecar](https://developer.hashicorp.com/vault/docs/platform/k8s/injector). ### Deploy a job with sidecar containers > [!NOTE] > **Note:** To require that all deployments use a specific sidecar, create [custom organization policies](https://docs.cloud.google.com/run/docs/securing/custom-constraints#require-prefix). You can deploy multiple sidecars to a Cloud Run job using the Google Cloud console, the gcloud CLI, YAML, or Terraform: ### Console 1. In the Google Cloud console, go to the Cloud Run jobs page: [Go to Cloud Run jobs](https://console.cloud.google.com/run/jobs) 2. To deploy to an existing job, click **Jobs** . Locate the job in the jobs list, and click to open it. Then click **View and edit configuration** to display the edit job form. 3. For a new job, click **Deploy container**. Supply the container image URL and the job name. 4. Click **Containers, Networking, Security** 5. In the **Edit container** card, configure the main job container as needed. 6. Click **Add container** and configure a sidecar container you want to add alongside the main job container. If the sidecar [depends on another container in the service](https://docs.cloud.google.com/run/docs/configuring/jobs/containers#container-ordering), indicate this in the **Container start-up order** drop-down menu. Repeat this step for each sidecar container you are deploying. 7. Click **Create** for a new service or **Update** for an existing job, then wait for the deployment to finish. ### gcloud 1. In the Google Cloud console, activate Cloud Shell. [Activate Cloud Shell](https://console.cloud.google.com/?cloudshell=true) At the bottom of the Google Cloud console, a [Cloud Shell](https://docs.cloud.google.com/shell/docs/how-cloud-shell-works) session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize. 2. To deploy multiple containers to a job, run the following command: ```bash gcloud run jobs create JOB \ --container JOB_CONTAINER_NAME \ --image='IMAGE_URL' \ --container SIDECAR_CONTAINER_NAME \ --image='SIDECAR_IMAGE' ``` Replace the following: - `JOB`: the name of your Cloud Run job. - `JOB_CONTAINER_NAME`: a name for the main job container. - `IMAGE_URL`: a reference to the [container image](https://docs.cloud.google.com/run/docs/building/containers)---for example, `us-docker.pkg.dev/cloudrun/container/job:latest`. - `SIDECAR_CONTAINER_NAME`: a name for the sidecar container---for example `sidecar`. - `SIDECAR_IMAGE`: a reference to the sidecar container image. If you want to configure each container in the deploy command, supply each container's configuration after the `container` parameters, for example: ```bash gcloud run jobs create JOB \ --container CONTAINER_1_NAME \ --image='IMAGE_URL' \ --set-env-vars=KEY=VALUE \ --container SIDECAR_CONTAINER_NAME \ --image='SIDECAR_IMAGE' \ --set-env-vars=KEY_N=VALUE_N ``` > [!IMPORTANT] > **Important:** When you use the `--container` flag, you must specify all non-container-level flags before the container-level flags, otherwise the deploy command fails with an error message to that effect. 3. Wait for the jobs deployment to finish. Upon successful completion, a success message is displayed. ### YAML 1. If you are creating a new job, skip this step. If you are updating an existing job, download its [YAML configuration](https://docs.cloud.google.com/run/docs/reference/yaml/v1#job): ```bash gcloud run jobs describe JOB --format export > job.yaml ``` 2. Update the `containers:` attributes: apiVersion: run.googleapis.com/v1 kind: Job metadata: name: JOB spec: template: spec: containers: - image: IMAGE_URL - image: SIDECAR_IMAGE Replace the following: - `JOB`: the name of your Cloud Run job. - `IMAGE_URL`: a reference to the [container image](https://docs.cloud.google.com/run/docs/building/containers)---for example, `us-docker.pkg.dev/cloudrun/container/job:latest`. - `SIDECAR_IMAGE`: a reference to the sidecar container image. 3. Create or update the job using the following command: ```bash gcloud run jobs replace job.yaml ``` The `gcloud run jobs replace` command defaults to using `job.yaml` file if present. ### Terraform To learn how to apply or remove a Terraform configuration, see [Basic Terraform commands](https://docs.cloud.google.com/docs/terraform/basic-commands). Add the following to a [`google_cloud_run_v2_job`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_run_v2_job) resource in your Terraform configuration: resource "google_cloud_run_v2_job" "default" { name = "JOB" location = "europe-west1" template { template { containers { name = "CONTAINER_NAME" image = "IMAGE_URL" } containers { name = "SIDECAR_CONTAINER_NAME" image = "SIDECAR_IMAGE_URL" } } } } Replace the following: - `JOB`: the name of your Cloud Run job. - `CONTAINER_NAME`: the name of the container. - `IMAGE_URL`: a reference to the [container image](https://docs.cloud.google.com/run/docs/building/containers)---for example, `us-docker.pkg.dev/cloudrun/container/job:latest`. - `SIDECAR_CONTAINER_NAME`: the name of the sidecar container. - `SIDECAR_IMAGE_URL`: a reference to the sidecar container image. ### Features available to deployments with sidecars You can specify the [container start up order](https://docs.cloud.google.com/run/docs/configuring/jobs/containers#container-ordering) within a deployment with multiple containers, if you have dependencies that require some containers to start up before other containers in the deployment. If you have containers that depend on other containers, you must use [startup healthchecks](https://docs.cloud.google.com/run/docs/configuring/jobs/healthchecks) in your deployment. If you use healthchecks, Cloud Run follows the container startup order and inspects the health of each container, making sure each passes successfully before Cloud Run starts up the next container in the order. If you don't use healthchecks, healthy containers will start up even if the containers they depend on are not running. Multiple containers within a single instance can access a shared [in-memory volume](https://docs.cloud.google.com/run/docs/configuring/jobs/in-memory-volume-mounts), which is accessible to each container using mount points that you create. ### Limitations If your job connects to Cloud SQL instances using Cloud Run's built-in feature, refer to the known issue on [Built-in Cloud SQL connections](https://docs.cloud.google.com/run/docs/known-issues#built-in-cloud-sql-connections). ## What's next After you create or update a job, you can do the following: - [Execute a job](https://docs.cloud.google.com/run/docs/execute/jobs) - [Execute a job on a schedule](https://docs.cloud.google.com/run/docs/execute/jobs-on-schedule) - [Manage jobs](https://docs.cloud.google.com/run/docs/managing/jobs) - [Manage job executions](https://docs.cloud.google.com/run/docs/managing/job-executions) - [View job logs](https://docs.cloud.google.com/run/docs/logging) - [Monitor job performance](https://docs.cloud.google.com/run/docs/monitoring) - [Set memory limits](https://docs.cloud.google.com/run/docs/configuring/jobs/memory-limits) - [Set environment variables](https://docs.cloud.google.com/run/docs/configuring/jobs/environment-variables)