Schedule a workflow using Cloud Scheduler

This page shows you how to use Cloud Scheduler to run a workflow on a particular schedule, such as every Monday at 9 AM or every 15 minutes. You can configure the schedule either in the Google Cloud console or by using the Google Cloud CLI.

Before you begin

1. If you do not already have a workflow that you want to schedule, create and deploy one.

2. Enable the Cloud Scheduler API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

Or, in a terminal, enter the following command:

gcloud services enable cloudscheduler.googleapis.com

Schedule a workflow

1. Create a service account so that Cloud Scheduler can make requests to the Workflows API:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   Replace SERVICE_ACCOUNT_NAME with a name that is between 6 and 30 characters. It can contain lowercase alphanumeric characters and dashes. After you create a service account, you cannot change its name.

2. To allow the principal that will run your Cloud Scheduler commands the ability to act as an Identity and Access Management (IAM) service account, grant a role that allows the principal to impersonate the service account.

3. Grant your new service account the workflows.invoker role so that the account has permission to trigger your workflow:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
     --role roles/workflows.invoker

   Replace the following:

   • PROJECT_ID: the ID of your Google Cloud project.
   • SERVICE_ACCOUNT_NAME: the name of the service account that you previously created.

4. Create a Cloud Scheduler job that triggers your workflow, using the service account you previously created to authenticate.

   Note that if you are applying call logging, you must configure call logging through the Workflows page in the Google Cloud console. For details, refer to the following steps.

   Console

   1. To schedule a workflow, go to the Workflows page in the Google Cloud console:

      Go to Workflows

   2. On the Workflows page, select a workflow to go to its details page.

   3. On the Workflow details page, click Edit.

   4. On the Edit workflow page, select Add new trigger > Cloud Scheduler.

      The Create a Scheduler job pane opens.

   5. Define the schedule:

      1. In the Name field, enter a name for your Cloud Scheduler job. It must be unique across the jobs in the same region.

      2. In the Region list, select an appropriate region; for example, us-central1.

      3. In the Frequency field, specify a time interval that you define in a unix-cron format. For example, to schedule your workflow to execute every 5 minutes, type */5 * * * *.

      4. In the Timezone list, select the time zone that Cloud Scheduler should use to interpret the schedule you provide. You can search by country.

   6. Click Continue.

   7. Configure the execution:

      1. In the Workflow's argument field, specify any runtime arguments to pass to your workflow before execution. Arguments must be in JSON format. For example: {"firstName":"Sherlock", "lastName":"Holmes"}. If your workflow doesn't use runtime arguments, accept the default of {}, or leave the field blank.

      2. In the Workflow's call log level list, select the level of call logging that you want to apply during the execution of the workflow:

         • Not specified: no logging level is specified. This is the default. An execution log level takes precedence over any workflow log level, unless the execution log level is not specified (the default); in that case, the workflow log level applies.
         • Errors only: log all caught exceptions; or when a call is stopped due to an exception.
         • All calls: log all calls to subworkflows or library functions and their results.
         • No logs: no call logging.

      3. In the Service account list, select the service account that you previously created.

   8. Click Create.

      Note that if you are updating an existing workflow, you do not need to redeploy the workflow.

      The Cloud Scheduler job is now listed on the Triggers tab of the Workflow details page.

   9. If you want to update or delete the job, you must edit the workflow:

      1. On the Workflow details page, click Edit.
      2. In the Triggers section, find the job you want to update or delete.
      3. Click Edit resource or Delete resource.

   gcloud

   1. Open a terminal and enter the following command:

      gcloud scheduler jobs create http JOB_NAME \
          --schedule="FREQUENCY" \
          --uri="https://workflowexecutions.googleapis.com/v1/projects/PROJECT_ID/locations/REGION_NAME/workflows/WORKFLOW_NAME/executions" \
          --message-body="{\"argument\": \"DOUBLE_ESCAPED_JSON_STRING\"}" \
          --time-zone="TIME_ZONE" \
          --oauth-service-account-email="SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"

      Replace the following:

      • JOB_NAME: the name you are giving to your Cloud Scheduler job.
      • FREQUENCY: a time interval you define using a unix-cron format. For example, to schedule your workflow to execute every 5 minutes, type */5 * * * *.
      • PROJECT_ID: the ID of your Google Cloud project.
      • REGION_NAME: the region your Workflow is in, such as us-central1.
      • WORKFLOW_NAME: the name of the workflow you want to schedule execution of.
      • DOUBLE_ESCAPED_JSON_STRING: a JSON encoding of any arguments you are passing. The double quotation marks inside the quoted string are escaped using backslashes (\). For example: --message-body="{\"argument\": \"{\\\"foo\\\": \\\"bar\\\"}\"}"
      • TIME_ZONE: the time zone that Cloud Scheduler should use to interpret the schedule you provide. For example: America/New_York.
      • SERVICE_ACCOUNT_NAME: the name of the service account that you previously created.

   2. To list all jobs in a project:

      gcloud scheduler jobs list

   3. To delete a job:

      gcloud scheduler jobs delete JOB_NAME

Your workflow now executes according to the frequency you have defined.

Note: Each execution of a workflow incurs costs, as detailed in Workflows pricing. To stop incurring costs from a scheduled workflow, delete the Cloud Scheduler job.

What's next

• Use IAM to control access
• Pass runtime arguments in an execution request
• Tutorial: Schedule Workflows with Cloud Scheduler