# Schedule and run a cron job using the gcloud CLI

This quickstart shows you how to use the gcloud CLI to perform some
basic operations using Cloud Scheduler.

In this quickstart, you:

1. Create a Pub/Sub topic to set up as your Cloud Scheduler job target.
2. Create a cron job using Cloud Scheduler, and configure a recurring schedule for the job.
3. Run your job.
4. Verify that the job has run successfully.

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

## Before you begin

<br />

### 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 Pub/Sub topic and subscription

A Pub/Sub topic is a resource to which publishers can send messages.
To receive messages published to a topic, you must create a subscription to
that topic.

1. Set up a Pub/Sub topic to use as a target for your cron job:

   ```bash
   gcloud pubsub topics create cron-topic
   ```

   This creates a topic called `cron-topic`.
2. To receive messages and view the results of your job, create a
   Pub/Sub subscription:

   ```bash
   gcloud pubsub subscriptions create cron-sub --topic cron-topic
   ```

## Create a cron job using Cloud Scheduler

Use the [`gcloud scheduler jobs create pubsub`](https://docs.cloud.google.com/sdk/gcloud/reference/scheduler/jobs/create/pubsub)
command to set up a unit of work known as a *cron job* that is sent to a
Pub/Sub target on a recurring schedule. The schedule is specified
using a format based on unix-cron. For more information, see
[Cron job format and time zone](https://docs.cloud.google.com/scheduler/docs/configuring/cron-job-schedules.md.txt).

```bash
gcloud scheduler jobs create pubsub my-cron-job \
    --schedule="30 16 * * 7" \
    --topic=cron-topic \
    --location="us-east1" \
    --message-body="Hello world"
```

You've created a job that sends a "Hello world" message to your 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 run immediately:

```bash
gcloud scheduler jobs run my-cron-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.

Next, you can verify that your Pub/Sub topic received the message.

## Verify the results in Pub/Sub

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 cron-sub --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:

   ```yaml
   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.

> [!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.
>
>
> If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects
> can help you avoid exceeding project quota limits.

1. Delete a Google Cloud project:

```
gcloud projects delete PROJECT_ID
```

<br />

Alternatively, delete the resources you created for this quickstart:

1. Delete the cron job. In Cloud Shell or on the machine where you installed
   the gcloud CLI, run the command:

   ```bash
   gcloud scheduler jobs delete MY_JOB \
       --location="LOCATION"
   ```

   Replace the following:
   - `MY_JOB`: the name of the job to be deleted.
   - `LOCATION`: the location of the job. By default, uses the location of the current project's App Engine app if there is an associated app.
2. Delete the Pub/Sub topic. In Cloud Shell or on the
   machine where you installed the gcloud CLI, run the command:

   ```bash
   gcloud pubsub topics delete TOPIC_ID
   ```

   Replace `TOPIC_ID` with the ID of the
   Pub/Sub topic to be deleted.
3. Delete the Pub/Sub subscription. In Cloud Shell or on
   the machine where you installed the gcloud CLI, run the command:

   ```bash
   gcloud pubsub subscriptions delete SUBSCRIPTION_ID
   ```

   Replace `SUBSCRIPTION_ID` with the ID of the
   Pub/Sub subscription to be deleted.

## What's next

- Learn more about [Cloud Scheduler](https://docs.cloud.google.com/scheduler/docs/overview.md.txt)

- Learn how to
  [view Cloud Scheduler logs](https://docs.cloud.google.com/scheduler/docs/viewing-logs.md.txt)