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.

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. Install the Google Cloud CLI.

  3. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

  5. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Cloud Scheduler, Pub/Sub APIs: 

    gcloud services enable cloudscheduler.googleapis.com pubsub.googleapis.com

  8. Install the Google Cloud CLI.

  9. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

    gcloud init

  11. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  12. Verify that billing is enabled for your Google Cloud project.

  13. Enable the Cloud Scheduler, Pub/Sub APIs: 

    gcloud services enable cloudscheduler.googleapis.com pubsub.googleapis.com

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:

    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:

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

Create a cron job using Cloud Scheduler

Use the gcloud 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.

gcloud scheduler jobs create pubsub my-cron-job \
    --schedule="30 16 * * 7" \
    --topic=cron-topic \
    --location="us-central1" \
    --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:

gcloud scheduler jobs run my-cron-job --location="us-central1"

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:

    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:

    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.

    Delete a Google Cloud project:

    gcloud projects delete PROJECT_ID

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:

    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:

    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:

    gcloud pubsub subscriptions delete SUBSCRIPTION_ID

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

What's next