This page describes how to execute Cloud Run jobs on a schedule using
Cloud Scheduler.

## Required roles

To get the permissions that you need for the operations described on this page,
ask your administrator to grant you the IAM roles on your
Cloud Run job:

- [Cloud Scheduler Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudscheduler.md.txt#cloudscheduler.admin) (`roles/cloudscheduler.admin`), or a custom role with the `cloudscheduler.jobs.create` permission.
- [Cloud Run Invoker](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.invoker) (`roles/run.invoker`) to execute jobs using the Google Cloud CLI, or [Cloud Run Developer](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.developer) (`roles/run.developer`) to execute jobs using the Google Cloud console.

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.md.txt)
and [Cloud Run IAM permissions](https://docs.cloud.google.com/run/docs/reference/iam/permissions.md.txt).
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.md.txt).
For more information about granting roles, see
[deployment permissions](https://docs.cloud.google.com/run/docs/reference/iam/roles.md.txt#additional-configuration)
and [manage access](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

## Before you begin

1. [Create a Cloud Run job](https://docs.cloud.google.com/run/docs/create-jobs.md.txt) if you have not created one yet.
2. Enable the Cloud Scheduler API for your project:

   ```bash
   gcloud services enable cloudscheduler.googleapis.com
   ```

## Configure a Cloud Run job to execute on a schedule

You can configure a Cloud Run job to execute on a schedule using the
Google Cloud console, the gcloud CLI, 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. Click the job you want to execute on a schedule.

3. Click the **Triggers** tab.

4. Click **Add Scheduler Trigger**.

5. In the Cloud Scheduler job form, follow these steps:

   1. For **Name**, enter a name for your Cloud Scheduler job.

   2. For **Region**, select a region for your Cloud Scheduler job.
      It does not need to match the region used for the Cloud Run
      job.

   3. Specify the **frequency** for your job execution, using the [unix-cron](http://man7.org/linux/man-pages/man5/crontab.5.html) format, for example, `0 12 * * *`

   4. Select your **Timezone**.

   5. Click **Continue**.

   6. In the **Configure the execution** section, select the service account
      that has permission to invoke the current Cloud Run job.

6. Click **Create** to create the Cloud Scheduler job that will execute
   the Cloud Run job at the specified frequency.

### gcloud

Run the following command:

```bash
  gcloud scheduler jobs create http SCHEDULER_JOB_NAME \
      --location SCHEDULER_REGION \
      --schedule="SCHEDULE" \
      --uri="https://run.googleapis.com/v2/projects/PROJECT_ID/locations/CLOUD_RUN_REGION/jobs/JOB:run" \
      --http-method POST \
      --oauth-service-account-email PROJECT_NUMBER-compute@developer.gserviceaccount.com
```

Replace the following:

- `SCHEDULER_JOB_NAME`: the name you want to give your scheduler job.
- `SCHEDULER_REGION`: a region supported by Cloud Scheduler---for example, `europe-west2`.
- `SCHEDULE`: the necessary frequency, for example `0 12 * * *`.
- `PROJECT_ID`: your project ID.
- `CLOUD_RUN_REGION`: the region for your Cloud Run job. For example, `europe-west1`.
- `JOB`: the name of your Cloud Run job.
- `PROJECT_NUMBER`: your project number.

### Terraform

To learn how to apply or remove a Terraform configuration, see
[Basic Terraform commands](https://docs.cloud.google.com/docs/terraform/basic-commands.md.txt).
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:  

```terraform
resource "google_cloud_scheduler_job" "job" {
  name             = "schedule-job"
  description      = "test http job"
  schedule         = "*/8 * * * *"
  attempt_deadline = "320s"
  region           = "us-central1"
  project          = data.google_project.project.project_id

  retry_config {
    retry_count = 3
  }

  http_target {
    http_method = "POST"
    uri         = "https://run.googleapis.com/v2/projects/${data.google_project.project.project_id}/locations/${google_cloud_run_v2_job.default.location}/jobs/${google_cloud_run_v2_job.default.name}:run"
    body        = base64encode("{}")

    headers = {
      "Content-Type" = "application/json"
    }

    oauth_token {
      service_account_email = google_service_account.cloud_run_invoker_sa.email
    }
  }

  depends_on = [resource.google_project_service.cloudscheduler_api, resource.google_cloud_run_v2_job.default, resource.google_cloud_run_v2_job_iam_binding.binding]
}
```

Cloud Scheduler will execute the Cloud Run job at the specified
frequency. To prevent duplicate job executions when Cloud Scheduler
retries a request, see
[Prevent duplicate requests to Google Cloud API targets](https://docs.cloud.google.com/scheduler/docs/configuring/deduplicate-job-requests.md.txt#deduplicate-google-api-targets).

## Schedule your job inside a VPC Service Controls perimeter

If your Google Cloud project is inside a VPC Service Controls perimeter in a
Virtual Private Cloud network, the Cloud Scheduler integration with
VPC Service Controls supports Cloud Run jobs as a target using
the following URI format:

```bash
https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB:run
```

Replace the following:

- `PROJECT_ID`: the Google Cloud project ID.
- `REGION`: the Google Cloud region of the job.
- `JOB`: the name of your Cloud Run job.

For more information on configuring VPC Service Controls for
Cloud Run, see
[Using VPC Service Controls (VPC SC)](https://docs.cloud.google.com/run/docs/securing/using-vpc-service-controls.md.txt).
For more information on using Cloud Scheduler with VPC Service Controls,
see [Secure cron jobs with VPC Service Controls](https://docs.cloud.google.com/scheduler/docs/secure-with-vpcsc.md.txt).

## What's next

After you use this feature, you can do the following:

- [View job logs](https://docs.cloud.google.com/run/docs/logging.md.txt)
- [Monitor job performance](https://docs.cloud.google.com/run/docs/monitoring.md.txt)
- [Create a job](https://docs.cloud.google.com/run/docs/create-jobs.md.txt)
- [Execute a job](https://docs.cloud.google.com/run/docs/execute/jobs.md.txt)
- [Manage jobs](https://docs.cloud.google.com/run/docs/managing/jobs.md.txt)
- [Manage job executions](https://docs.cloud.google.com/run/docs/managing/job-executions.md.txt)

- [Set memory limits](https://docs.cloud.google.com/run/docs/configuring/jobs/memory-limits.md.txt)

- [Set environment variables](https://docs.cloud.google.com/run/docs/configuring/jobs/environment-variables.md.txt)