# Schedule and run a cron job using Terraform

This quickstart shows you how to use Terraform to create a Cloud Scheduler
cron job. Terraform is an infrastructure as code (IaC) tool that lets you
predictably create, change, and improve your cloud infrastructure by using code.
You can learn more about
[using Terraform](https://docs.cloud.google.com/docs/terraform.md.txt)
to provision infrastructure on Google Cloud.

Cloud Scheduler has a free tier and running this quickstart shouldn't
result in any costs. For more information, see
[Pricing](https://cloud.google.com/scheduler/pricing).

In this quickstart, you:

1. Use Terraform to create a cron job for Cloud Scheduler.
2. Set a recurring schedule for the job.
3. Specify a Pub/Sub topic as the job target.
4. Run the job.
5. Verify that the job has run successfully.

## Before you begin

Security constraints defined by your organization might prevent you from completing the
following steps. For troubleshooting information, see
[Develop applications in a constrained Google Cloud environment](https://docs.cloud.google.com/resource-manager/docs/organization-policy/develop-apps-constrained-environment).

1. Cloud Shell has Terraform already integrated. If you need to install Terraform, see the [HashiCorp Terraform documentation](https://developer.hashicorp.com/terraform/tutorials/gcp-get-started/install-cli).

### Required roles


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

ask your administrator to grant you the
following IAM roles on your project:

- [Cloud Scheduler Admin](https://docs.cloud.google.com/iam/docs/roles-permissions/cloudscheduler.md.txt#cloudscheduler.admin) (`roles/cloudscheduler.admin`)
- [Pub/Sub Editor](https://docs.cloud.google.com/iam/docs/roles-permissions/pubsub.md.txt#pubsub.editor) (`roles/pubsub.editor`)


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

## Create a Terraform configuration file

To use Terraform with Cloud Scheduler, you need to create a
configuration file to describe your infrastructure and create an execution plan.
You then apply the configuration file to your platform or service to perform
operations that provision your infrastructure.

Complete the following steps to create a Terraform configuration file called
`main.tf`:

1. Open a terminal and create a directory:

   ```bash
   mkdir terraform
   ```
2. Go to the `terraform` directory:

   ```bash
   cd terraform
   ```
3. Add a new file, `main.tf`, to the directory:

   ```bash
   nano main.tf
   ```
4. Add the following
   [Terraform provider for Google Cloud](https://registry.terraform.io/providers/hashicorp/google/latest/docs)
   resources to the `main.tf` file:

   1. Enable the Cloud Scheduler and Pub/Sub APIs:

      ```terraform
      # Enable Cloud Scheduler API
      resource "google_project_service" "scheduler" {
        service            = "cloudscheduler.googleapis.com"
        disable_on_destroy = false
      }
      # Enable Pub/Sub API
      resource "google_project_service" "pubsub" {
        service            = "pubsub.googleapis.com"
        disable_on_destroy = false
      }
      ```
   2. Create a Pub/Sub topic as a resource to which messages can be
      sent by publishers:

      ```terraform
      # Create Pub/Sub topic
      resource "google_pubsub_topic" "default" {
        name = "pubsub_topic"
      }
      ```

      This creates a topic called `pubsub_topic`.
   3. Create a subscription to receive messages published to the
      Pub/Sub topic:

      ```terraform
      # Create Pub/Sub subscription
      resource "google_pubsub_subscription" "default" {
        name  = "pubsub_subscription"
        topic = google_pubsub_topic.default.name
      }
      ```
   4. Create a cron job using the
      [`google_cloud_scheduler_job`](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_scheduler_job) resource:

      ```terraform
      # Create a cron job using Cloud Scheduler
      resource "google_cloud_scheduler_job" "default" {
        name        = "test-job"
        description = "test job"
        schedule    = "30 16 * * 7"
        region      = "us-east1"

        pubsub_target {
          topic_name = google_pubsub_topic.default.id
          data       = base64encode("Hello world!")
        }
      }
      ```

      The following arguments are used in the sample:
      - `name`: the name of the job.
      - `description`: a description for the job.
      - `schedule`: the frequency for the job, using a format based on unix-cron.

        In this sample, `30 16 * * 7` means that the job will run at 16:30 on
        Sundays. For more information, see
        [Cron job format and time zone](https://docs.cloud.google.com/scheduler/docs/configuring/cron-job-schedules.md.txt).
      - `region`: the region where the job resides.

      - `pubsub_target`: the Pub/Sub topic target, including the
        full resource name of the topic (`topic_name`) to which the message
        payload (`data`) is published when the job is run.

      Other arguments are supported. For details, see the
      [Terraform Registry argument reference](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloud_scheduler_job#argument-reference).

For another example of using Terraform with Cloud Scheduler, see
[Running Cloud Run services on a schedule](https://docs.cloud.google.com/run/docs/triggering/using-scheduler.md.txt).

## Create the cron job

Deploy your Terraform resources to create the cron job.

1. Open a terminal and in the `terraform` directory, initialize Terraform:

   ```bash
   terraform init
   ```
2. Check that the changes you propose with Terraform match the expected plan:

   ```bash
   terraform plan
   ```

   You can ignore the note regarding not using the `-out` option.
3. Create the cron job:

   ```bash
   terraform apply
   ```
4. At the **Enter a value** prompt, type `yes` to proceed with the creation of
   resources.

5. Confirm that a job is created:

   ```bash
   gcloud scheduler jobs describe test-job --location=us-east1
   ```

   The output should be similar to the following:

   ```bash
   description: test job
   lastAttemptTime: '2024-04-04T13:56:00.669530Z'
   name: projects/PROJECT_ID/locations/us-east1/jobs/test-job
   pubsubTarget:
   data: dGVzdA==
   topicName: projects/PROJECT_ID/topics/pubsub_topic
   schedule: '30 16 * * 7'
   scheduleTime: '2024-04-04T13:58:00.737907Z'
   state: ENABLED
   ```

You've created a job that sends a message to a Pub/Sub topic
at 16:30 on Sundays. You can now run the job.

## Run your job

In addition to executing according to its specified schedule, you can force your
job to execute immediately by running the following command.

```bash
gcloud scheduler jobs run test-job --location=us-east1
```

Note that due to some initial configuration, the first job created in a
project can take a few minutes to run.

## Verify the results

Verify that your Pub/Sub topic is receiving messages from your job.

1. Pull Pub/Sub messages from a subscription:

   ```bash
   gcloud pubsub subscriptions pull pubsub_subscription --limit 5
   ```

   If there are no messages pulled initially, run the command again.
2. View the results of running your job. The output should look similar to the
   following:

   ```bash
   DATA: Hello world!
   MESSAGE_ID: 5028933846601543
   ORDERING_KEY:
   ATTRIBUTES:
   DELIVERY_ATTEMPT:
   ACK_ID: RFAGFixdRkhRNxkIaFEOT14jPzUgKEUQAgVPAihdeTFXLkFacGhRDRlyfWB9[...]
   ```

## Clean up


To avoid incurring charges to your Google Cloud account for
the resources used on this page, delete the Google Cloud project with the
resources.

1. Deleting your Google Cloud project stops billing for all the resources used within that project. Note that by default, any files in your Cloud Shell home directory (for example, any Terraform files) persist between sessions.

   > [!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.

   Delete a Google Cloud project:

   ```
   gcloud projects delete PROJECT_ID
   ```
2. Alternatively, you can delete all the resources you created with
   Terraform.

   The `terraform destroy` command terminates all the resources
   specified in your
   [Terraform state](https://developer.hashicorp.com/terraform/language/state). It doesn't destroy
   resources that aren't managed by the current Terraform project. Your
   Terraform configuration file is not destroyed. For more information, see
   [Destroy infrastructure](https://developer.hashicorp.com/terraform/tutorials/gcp-get-started/google-cloud-platform-destroy).

   ```bash
   terraform destroy
   ```

## What's next

- [What is Terraform?](https://developer.hashicorp.com/terraform/intro)
- [Viewing Cloud Scheduler logs](https://docs.cloud.google.com/scheduler/docs/viewing-logs.md.txt)