Build and create a Java job in Cloud Run

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

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

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Install the Google Cloud CLI.

5. To initialize the gcloud CLI, run the following command:

   gcloud init

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

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

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

7. Make sure that billing is enabled for your Google Cloud project.

8. Install the Google Cloud CLI.

9. To initialize the gcloud CLI, run the following command:

   gcloud init

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

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

11. For Cloud Build to be able to build your sources, grant the Cloud Build Service Account role to the Compute Engine default service account by running the following:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:[e-mail] \
        --role=roles/cloudbuild.builds.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 Build Service Account 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.

Writing the sample job

To write a job in Java:

1. Create a new directory named jobs and change directory into it:

   mkdir jobs
   cd jobs
   

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

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

4. 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, us-central1. 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 us-central1.

What's next

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

• Developing Cloud Run services
• Building Containers
• Test a Cloud Run service locally
• Deploying from source code