Build and create a Java job in Cloud Run

Learn how to create a simple Cloud Run job, then deploy from source, which automatically packages your code into a container image, uploads the container image to Artifact Registry, and then deploys to Cloud Run. You can use other languages in addition to the ones shown.

Before you begin

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project .

Install the Google Cloud CLI.

Note:If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update .

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

To initialize the gcloud CLI, run the following command:

gcloud  
init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Verify that billing is enabled for your Google Cloud project .

Install the Google Cloud CLI.

Note:If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update .

If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

To initialize the gcloud CLI, run the following command:

gcloud  
init

Enable the Cloud Run Admin API and the Cloud Build API:
```
gcloud  
services  
 enable 
  
run.googleapis.com  
 \ 
  
cloudbuild.googleapis.com
```
After the Cloud Run Admin API is enabled, the Compute Engine default service account is automatically created.

Click to view required roles for the Cloud Build service account

Cloud Build automatically uses the Compute Engine default service account as the default Cloud Build service account to build your source code and Cloud Run resource, unless you override this behavior. For Cloud Build to build your sources, ask your administrator to grant Cloud Run Builder ( roles/run.builder ) to the Compute Engine default service account on your project:

  
gcloud  
projects  
add-iam-policy-binding  
 PROJECT_ID 
  
 \ 
  
--member = 
serviceAccount: PROJECT_NUMBER 
-compute@developer.gserviceaccount.com  
 \ 
  
--role = 
roles/run.builder

Replace PROJECT_NUMBER with your Google Cloud project number, and PROJECT_ID with your Google Cloud project ID. For detailed instructions on how to find your project ID, and project number, see Creating and managing projects .

Granting the Cloud Run builder role to the Compute Engine default service account takes a couple of minutes to propagate .

Note:

The iam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint prevents the Editor role from being automatically granted to default service accounts. If you created your organization after May 3, 2024, this constraint is enforced by default.

We strongly recommend that you enforce this constraint to disable the automatic role grant. If you disable the automatic role grant, you must decide which roles to grant to the default service accounts, and then grant these roles yourself.

If the default service account already has the Editor role, we recommend that you replace the Editor role with less permissive roles.To safely modify the service account's roles, use Policy Simulator to see the impact of the change, and then grant and revoke the appropriate roles .

Review Cloud Run pricing or estimate costs with the pricing calculator .

Writing the sample job

To write a job in Java:

Create a new directory named jobs and change directory into it:
```
  mkdir 
  
 jobs 
 cd 
  
 jobs 
 
```

In a subdirectory directory named src/main/java/com/example , create a JobsExample.java file for the actual job code. Copy the following sample lines into it:

  package 
  
 com.example 
 ; 
 abstract 
  
 class 
 JobsExample 
  
 { 
  
 // These values are provided automatically by the Cloud Run Jobs runtime. 
  
 private 
  
 static 
  
 String 
  
 CLOUD_RUN_TASK_INDEX 
  
 = 
  
 System 
 . 
 getenv 
 (). 
 getOrDefault 
 ( 
 "CLOUD_RUN_TASK_INDEX" 
 , 
  
 "0" 
 ); 
  
 private 
  
 static 
  
 String 
  
 CLOUD_RUN_TASK_ATTEMPT 
  
 = 
  
 System 
 . 
 getenv 
 (). 
 getOrDefault 
 ( 
 "CLOUD_RUN_TASK_ATTEMPT" 
 , 
  
 "0" 
 ); 
  
 // User-provided environment variables 
  
 private 
  
 static 
  
 int 
  
 SLEEP_MS 
  
 = 
  
 Integer 
 . 
 parseInt 
 ( 
 System 
 . 
 getenv 
 (). 
 getOrDefault 
 ( 
 "SLEEP_MS" 
 , 
  
 "0" 
 )); 
  
 private 
  
 static 
  
 float 
  
 FAIL_RATE 
  
 = 
  
 Float 
 . 
 parseFloat 
 ( 
 System 
 . 
 getenv 
 (). 
 getOrDefault 
 ( 
 "FAIL_RATE" 
 , 
  
 "0.0" 
 )); 
  
 // Start script 
  
 public 
  
 static 
  
 void 
  
 main 
 ( 
 String 
 [] 
  
 args 
 ) 
  
 { 
  
 System 
 . 
 out 
 . 
 println 
 ( 
  
 String 
 . 
 format 
 ( 
  
 "Starting Task #%s, Attempt #%s..." 
 , 
  
 CLOUD_RUN_TASK_INDEX 
 , 
  
 CLOUD_RUN_TASK_ATTEMPT 
 )); 
  
 try 
  
 { 
  
 runTask 
 ( 
 SLEEP_MS 
 , 
  
 FAIL_RATE 
 ); 
  
 } 
  
 catch 
  
 ( 
 RuntimeException 
  
 | 
  
 InterruptedException 
  
 e 
 ) 
  
 { 
  
 System 
 . 
 err 
 . 
 println 
 ( 
  
 String 
 . 
 format 
 ( 
  
 "Task #%s, Attempt #%s failed." 
 , 
  
 CLOUD_RUN_TASK_INDEX 
 , 
  
 CLOUD_RUN_TASK_ATTEMPT 
 )); 
  
 // Catch error and denote process-level failure to retry Task 
  
 System 
 . 
 exit 
 ( 
 1 
 ); 
  
 } 
  
 } 
  
 static 
  
 void 
  
 runTask 
 ( 
 int 
  
 sleepTime 
 , 
  
 float 
  
 failureRate 
 ) 
  
 throws 
  
 InterruptedException 
  
 { 
  
 // Simulate work 
  
 if 
  
 ( 
 sleepTime 
 > 
 0 
 ) 
  
 { 
  
 Thread 
 . 
 sleep 
 ( 
 sleepTime 
 ); 
  
 } 
  
 // Simulate errors 
  
 if 
  
 ( 
 failureRate 
 < 
 0 
  
 || 
  
 failureRate 
 > 
 1 
 ) 
  
 { 
  
 System 
 . 
 err 
 . 
 println 
 ( 
  
 String 
 . 
 format 
 ( 
  
 "Invalid FAIL_RATE value: %s. Must be a float between 0 and 1 inclusive." 
 , 
  
 failureRate 
 )); 
  
 return 
 ; 
  
 } 
  
 if 
  
 ( 
 Math 
 . 
 random 
 () 
 < 
 failureRate 
 ) 
  
 { 
  
 throw 
  
 new 
  
 RuntimeException 
 ( 
 "Task Failed." 
 ); 
  
 } 
  
 System 
 . 
 out 
 . 
 println 
 ( 
 String 
 . 
 format 
 ( 
 "Completed Task #%s" 
 , 
  
 CLOUD_RUN_TASK_INDEX 
 )); 
  
 } 
 }

Cloud Run jobs allows users to specify the number of tasks the job is to execute. This sample code shows how to use the built-in CLOUD_RUN_TASK_INDEX environment variable. Each task represents one running copy of the container. Note that tasks are usually executed in parallel. Using multiple tasks is useful if each task can independently process a subset of your data.

Each task is aware of its index, stored in the CLOUD_RUN_TASK_INDEX environment variable. The built-in CLOUD_RUN_TASK_COUNT environment variable contains the number of tasks supplied at job execution time via the --tasks parameter.

The code shown also shows how to retry tasks, using the built-in CLOUD_RUN_TASK_ATTEMPT environment variable, which contains the number of times this task has been retried, starting at 0 for the first attempt and incrementing by 1 for every successive retry, up to --max-retries .

The code also lets you generate failures as a way to test retries and to generate error logs so you can see what those look like.

Create a pom.xml file with the following contents:

 < ? 
 xml 
  
 version 
 = 
 "1.0" 
  
 encoding 
 = 
 "UTF-8" 
 ? 
>
< !-- 
 Copyright 
  
 2021 
  
 Google 
  
 LLC 
 Licensed 
  
 under 
  
 the 
  
 Apache 
  
 License 
 , 
  
 Version 
  
 2.0 
  
 ( 
 the 
  
 "License" 
 ); 
 you 
  
 may 
  
 not 
  
 use 
  
 this 
  
 file 
  
 except 
  
 in 
  
 compliance 
  
 with 
  
 the 
  
 License 
 . 
 You 
  
 may 
  
 obtain 
  
 a 
  
 copy 
  
 of 
  
 the 
  
 License 
  
 at 
 http 
 : 
 //www.apache.org/licenses/LICENSE-2.0 
 Unless 
  
 required 
  
 by 
  
 applicable 
  
 law 
  
 or 
  
 agreed 
  
 to 
  
 in 
  
 writing 
 , 
  
 software 
 distributed 
  
 under 
  
 the 
  
 License 
  
 is 
  
 distributed 
  
 on 
  
 an 
  
 "AS IS" 
  
 BASIS 
 , 
 WITHOUT 
  
 WARRANTIES 
  
 OR 
  
 CONDITIONS 
  
 OF 
  
 ANY 
  
 KIND 
 , 
  
 either 
  
 express 
  
 or 
  
 implied 
 . 
 See 
  
 the 
  
 License 
  
 for 
  
 the 
  
 specific 
  
 language 
  
 governing 
  
 permissions 
  
 and 
 limitations 
  
 under 
  
 the 
  
 License 
 . 
 -- 
>
< project 
  
 xmlns 
 = 
 "http://maven.apache.org/POM/4.0.0" 
  
 xmlns 
 : 
 xsi 
 = 
 "http://www.w3.org/2001/XMLSchema-instance" 
  
 xsi 
 : 
 schemaLocation 
 = 
 "http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" 
>  
< modelVersion>4 
 .0.0 
< / 
 modelVersion 
>  
< groupId>com 
 . 
 example 
 . 
 run 
< / 
 groupId 
>  
< artifactId>jobs 
 - 
 example 
< / 
 artifactId 
>  
< version>0 
 .0.1 
< / 
 version 
>  
< packaging>jar 
< / 
 packaging 
>  
< !-- 
  
 The 
  
 parent 
  
 pom 
  
 defines 
  
 common 
  
 style 
  
 checks 
  
 and 
  
 testing 
  
 strategies 
  
 for 
  
 our 
  
 samples 
 . 
  
 Removing 
  
 or 
  
 replacing 
  
 it 
  
 should 
  
 not 
  
 affect 
  
 the 
  
 execution 
  
 of 
  
 the 
  
 samples 
  
 in 
  
 anyway 
 . 
  
 -- 
>  
< parent 
>  
< groupId>com 
 . 
 google 
 . 
 cloud 
 . 
 samples 
< / 
 groupId 
>  
< artifactId>shared 
 - 
 configuration 
< / 
 artifactId 
>  
< version>1 
 .2.0 
< / 
 version 
>  
< / 
 parent 
>  
< properties 
>  
< project 
 . 
 build 
 . 
 sourceEncoding>UTF 
 - 
 8 
< / 
 project 
 . 
 build 
 . 
 sourceEncoding 
>  
< project 
 . 
 reporting 
 . 
 outputEncoding>UTF 
 - 
 8 
< / 
 project 
 . 
 reporting 
 . 
 outputEncoding 
>  
< maven 
 . 
 compiler 
 . 
 target>17 
< / 
 maven 
 . 
 compiler 
 . 
 target 
>  
< maven 
 . 
 compiler 
 . 
 source>17 
< / 
 maven 
 . 
 compiler 
 . 
 source 
>  
< / 
 properties 
>  
< dependencyManagement 
>  
< dependencies 
>  
< dependency 
>  
< artifactId>libraries 
 - 
 bom 
< / 
 artifactId 
>  
< groupId>com 
 . 
 google 
 . 
 cloud 
< / 
 groupId 
>  
< scope>import 
< / 
 scope 
>  
< type>pom 
< / 
 type 
>  
< version>26 
 .32.0 
< / 
 version 
>  
< / 
 dependency 
>  
< / 
 dependencies 
>  
< / 
 dependencyManagement 
>  
< dependencies 
>  
< dependency 
>  
< groupId>junit 
< / 
 groupId 
>  
< artifactId>junit 
< / 
 artifactId 
>  
< version>4 
 .13.2 
< / 
 version 
>  
< scope>test 
< / 
 scope 
>  
< / 
 dependency 
>  
< dependency 
>  
< groupId>com 
 . 
 google 
 . 
 truth 
< / 
 groupId 
>  
< artifactId>truth 
< / 
 artifactId 
>  
< version>1 
 .4.0 
< / 
 version 
>  
< scope>test 
< / 
 scope 
>  
< / 
 dependency 
>  
< dependency 
>  
< groupId>com 
 . 
 google 
 . 
 cloud 
< / 
 groupId 
>  
< artifactId>google 
 - 
 cloud 
 - 
 logging 
< / 
 artifactId 
>  
< scope>test 
< / 
 scope 
>  
< / 
 dependency 
>  
< / 
 dependencies 
>  
< build 
>  
< plugins 
>  
< plugin 
>  
< groupId>org 
 . 
 apache 
 . 
 maven 
 . 
 plugins 
< / 
 groupId 
>  
< artifactId>maven 
 - 
 jar 
 - 
 plugin 
< / 
 artifactId 
>  
< version>3 
 .3.0 
< / 
 version 
>  
< configuration 
>  
< archive 
>  
< manifest 
>  
< addClasspath>true 
< / 
 addClasspath 
>  
< mainClass>com 
 . 
 example 
 . 
 JobsExample 
< / 
 mainClass 
>  
< / 
 manifest 
>  
< / 
 archive 
>  
< / 
 configuration 
>  
< / 
 plugin 
>  
< / 
 plugins 
>  
< / 
 build 
>
< / 
 project 
>

Create a project.toml file with the following contents, to build with the Java version supported by Buildpack:

  # 
  
 Default 
  
 version 
  
 is 
  
 Java 
  
 11 
 # 
  
 - 
  
 See 
  
 https 
 : 
 //cloud.google.com/docs/buildpacks/java#specify_a_java_version 
 # 
  
 Match 
  
 the 
  
 version 
  
 required 
  
 in 
  
 pom 
 . 
 xml 
  
 by 
  
 setting 
  
 it 
  
 here 
 # 
  
 - 
  
 See 
  
 https 
 : 
 //cloud.google.com/docs/buildpacks/set-environment-variables#build_the_application_with_environment_variables 
 [[ 
 build 
 . 
 env 
 ]] 
  
 name 
  
 = 
  
 "GOOGLE_RUNTIME_VERSION" 
  
 value 
  
 = 
  
 "17"

Your code is complete and ready to be packaged in a container.

Build jobs container, send it to Artifact Registry and deploy to Cloud Run

Important: This quickstart assumes that you have owner or editor roles in the project you are using for the quickstart. Otherwise, refer to the Cloud Run Source Developer role for the required permissions for deploying a Cloud Run resource from source.

This quickstart uses deploy from source, which builds the container, uploads it to Artifact Registry, and deploys the job to Cloud Run:

gcloud  
run  
 jobs 
  
deploy  
job-quickstart  
 \ 
  
--source  
.  
 \ 
  
--tasks  
 50 
  
 \ 
  
--set-env-vars  
 SLEEP_MS 
 = 
 10000 
  
 \ 
  
--set-env-vars  
 FAIL_RATE 
 = 
 0 
.1  
 \ 
  
--max-retries  
 5 
  
 \ 
  
--region  
 REGION 
  
 \ 
  
--project = 
 PROJECT_ID

where PROJECT_ID is your project ID and REGION is your region, for example, europe-west1 . Note that you can change the various parameters to whatever values you want to use for your testing purposes. SLEEP_MS simulates work and FAIL_RATE causes X % of tasks to fail so you can experiment with parallelism and retrying failing tasks.

Execute a job in Cloud Run

To execute the job you just created:

gcloud  
run  
 jobs 
  
execute  
job-quickstart  
--region  
 REGION

Replace REGION with the region you used when you created and deployed the job, for example europe-west1 .

Clean up

To avoid additional charges to your Google Cloud account, delete all the resources you deployed with this quickstart.

Delete your repository

Cloud Run only charges for the time your job executes. However, you might still be charged for storing the container image in Artifact Registry . To delete Artifact Registry repositories, follow the steps in Delete repositories in the Artifact Registry documentation.

Delete your job

Cloud Run jobs only incur cost when a job task is executing. To delete your Cloud Run job, follow one of these steps:

Console

To delete a job:

In the Google Cloud console, go to Cloud Run:

Go to Cloud Run
Locate the job you want to delete in the jobs list, and click its checkbox to select it.
Click Delete. This terminates all the job executions in progress and all running container instances.

gcloud

To delete a job, run the following command:

gcloud  
run  
 jobs 
  
delete  
 JOB_NAME

Replace JOB_NAME with the name of the job.

Delete your test project

Deleting your Google Cloud project stops billing for all resources in that project. To release all Google Cloud resources in your project, follow these steps:

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete .
In the dialog, type the project ID, and then click Shut down to delete the project.

What's next

For more information on building a container from code source and pushing to a repository, see: