# Build and create a Go 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.

<br />

## Before you begin

1.


   Enable the Cloud Run Admin API and Cloud Build APIs, if any are not already enabled:


   **Roles required to enable APIs**


   To enable APIs, you need the `serviceusage.services.enable` permission. If you
   created the project, then you likely already have this permission through the
   Owner role (`roles/owner`). Otherwise, you can get this permission through the
   Service Usage Admin role (`roles/serviceusage.serviceUsageAdmin`).
   [Learn how to grant roles](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

   ```bash
   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.
2. Review [Cloud Run
   pricing](https://cloud.google.com/run/pricing) or estimate costs with the [pricing calculator](https://cloud.google.com/products/calculator).

<br />

### Required roles


To get the permissions that
you need to complete this quickstart,

ask your administrator to grant you the
following IAM roles:

- [Cloud Run Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.admin) (`roles/run.admin`) on the project
- [Cloud Run Source Developer](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.sourceDeveloper) (`roles/run.sourceDeveloper`) on the project
- [Service Account User](https://docs.cloud.google.com/iam/docs/roles-permissions/iam.md.txt#iam.serviceAccountUser) (`roles/iam.serviceAccountUser`) on the service identity
- [Logs Viewer](https://docs.cloud.google.com/iam/docs/roles-permissions/logging.md.txt#logging.viewer) (`roles/logging.viewer`) on the project


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

### Grant the Cloud Build service account access to your project

Cloud Build automatically uses the [Compute Engine default
service account](https://docs.cloud.google.com/build/docs/cloud-build-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, grant the Cloud Build service
account the [Cloud Run
Builder](https://docs.cloud.google.com/iam/docs/roles-permissions/run#run.builder)
(`roles/run.builder`) role on your project:

```bash
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS \
    --role=roles/run.builder
```

Replace `PROJECT_ID` with your Google Cloud
project ID and `SERVICE_ACCOUNT_EMAIL_ADDRESS` with the
email address of the Cloud Build service account. If you're using the
Compute Engine default service account as the Cloud Build service account, then
use the following format for the service account email address:

```bash
PROJECT_NUMBER-compute@developer.gserviceaccount.com
```

Replace `PROJECT_NUMBER` with your Google Cloud
project number.

For detailed instructions on how to find your project ID, and project number,
see [Creating
and managing projects](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects).

Granting the Cloud Run builder role takes a couple of minutes to [propagate](https://docs.cloud.google.com/iam/docs/access-change-propagation.md.txt).

## Writing the sample job

<br />

To write a job in Go:

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

       mkdir jobs
       cd jobs

2. In the same directory, create a `main.go` file for the actual job code. Copy
   the following sample lines into it:

   ```go
   package main

   import (
   	"fmt"
   	"log"
   	"math/rand"
   	"os"
   	"strconv"
   	"time"
   )

   type Config struct {
   	// Job-defined
   	taskNum    string
   	attemptNum string

   	// User-defined
   	sleepMs  int64
   	failRate float64
   }

   func configFromEnv() (Config, error) {
   	// Job-defined
   	taskNum := os.Getenv("CLOUD_RUN_TASK_INDEX")
   	attemptNum := os.Getenv("CLOUD_RUN_TASK_ATTEMPT")
   	// User-defined
   	sleepMs, err := sleepMsToInt(os.Getenv("SLEEP_MS"))
   	failRate, err := failRateToFloat(os.Getenv("FAIL_RATE"))

   	if err != nil {
   		return Config{}, err
   	}

   	config := Config{
   		taskNum:    taskNum,
   		attemptNum: attemptNum,
   		sleepMs:    sleepMs,
   		failRate:   failRate,
   	}
   	return config, nil
   }

   func sleepMsToInt(s string) (int64, error) {
   	sleepMs, err := strconv.ParseInt(s, 10, 64)
   	return sleepMs, err
   }

   func failRateToFloat(s string) (float64, error) {
   	// Default empty variable to 0
   	if s == "" {
   		return 0, nil
   	}

   	// Convert string to float
   	failRate, err := strconv.ParseFloat(s, 64)

   	// Check that rate is valid
   	if failRate < 0 || failRate > 1 {
   		return failRate, fmt.Errorf("Invalid FAIL_RATE value: %f. Must be a float between 0 and 1 inclusive.", failRate)
   	}

   	return failRate, err
   }

   func main() {
   	config, err := configFromEnv()
   	if err != nil {
   		log.Fatal(err)
   	}

   	log.Printf("Starting Task #%s, Attempt #%s ...", config.taskNum, config.attemptNum)

   	// Simulate work
   	if config.sleepMs > 0 {
   		time.Sleep(time.Duration(config.sleepMs) * time.Millisecond)
   	}

   	// Simulate errors
   	if config.failRate > 0 {
   		if failure := randomFailure(config); failure != nil {
   			log.Fatalf("%v", failure)
   		}
   	}

   	log.Printf("Completed Task #%s, Attempt #%s", config.taskNum, config.attemptNum)
   }

   // Throw an error based on fail rate
   func randomFailure(config Config) error {
   	rand.Seed(time.Now().UnixNano())
   	randomFailure := rand.Float64()

   	if randomFailure < config.failRate {
   		return fmt.Errorf("Task #%s, Attempt #%s failed.", config.taskNum, config.attemptNum)
   	}
   	return nil
   }
   ```

   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 `go.mod` file with the following contents:

   ```go
   module github.com/GoogleCloudPlatform/golang-samples/run/jobs

   go 1.25.0
   ```

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

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

```bash
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 <var translate="no">PROJECT_ID</var> is your project ID and <var translate="no">REGION</var> 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:

<br />

```bash
gcloud run jobs execute job-quickstart --region REGION
```

<br />

Replace <var translate="no">REGION</var> with the region you used when you created and deployed
the job, for example `europe-west1`.

> [!TIP]
> **Success:** You created and executed a job using the Go runtime in Cloud Run.

## 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](https://cloud.google.com/artifact-registry/pricing). To delete Artifact Registry repositories,
follow the steps in [Delete
repositories](https://docs.cloud.google.com/artifact-registry/docs/manage-repos#delete) 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:

1. In the Google Cloud console, go to Cloud Run:

   [Go to Cloud Run](https://console.cloud.google.com/run/jobs)
2. Locate the job you want to delete in the jobs list, and click
   its checkbox to select it.

3. Click **Delete**. This terminates all the job executions in progress and
   all running container instances.

### gcloud

To delete a job, run the following command:

```bash
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:

> [!CAUTION]
> **Caution** : Deleting a project has the following effects:
>
> - **Everything in the project is deleted.** If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
> - **Custom project IDs are lost.** When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an `appspot.com` URL, delete selected resources inside the project instead of deleting the whole project.

1. Delete a Google Cloud project:

```
gcloud projects delete PROJECT_ID
```

<br />

## What's next

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

- [Developing Cloud Run services](https://docs.cloud.google.com/run/docs/developing.md.txt)
- [Building Containers](https://docs.cloud.google.com/run/docs/building/containers.md.txt)
- [Test a Cloud Run service locally](https://docs.cloud.google.com/run/docs/testing/local.md.txt)
- [Deploying from source code](https://docs.cloud.google.com/run/docs/deploying-source-code.md.txt)