Cloud Scheduler in GCP: What It Is, How It Works, and When to Use It

Cloud Scheduler in plain English

Cloud Scheduler is Google’s managed alarm clock for your cloud infrastructure. You set a time, tell it what to call, and it handles everything else — no servers required.

Here is the mental model in four steps:

1. You write a cron expression, such as 0 9 * * * (every day at 09:00)
2. You pick a target: an HTTP URL, a Pub/Sub topic, or a Cloud Run Job
3. Google fires the trigger on the schedule, with retries if the target fails
4. Every execution is logged automatically — check the result any time

If you have ever maintained a cron job on a Linux VM just to hit an API endpoint every night, Cloud Scheduler removes that entire layer of operational overhead.

How Cloud Scheduler works

Each Cloud Scheduler job has four components. Understanding these makes the gcloud commands much easier to read.

• Schedule: a cron expression that determines when the job fires. Cloud Scheduler uses standard Unix cron syntax.

• Target: where the trigger is sent. Either an HTTP/HTTPS endpoint, a Pub/Sub topic, or the Cloud Run Jobs API.

• Authentication: either none (public endpoint) or an OIDC token generated from a service account identity, attached to the Authorization header automatically.

• Retry policy: how many times to retry on a non-2xx response, with configurable backoff between attempts.

When the schedule fires, Cloud Scheduler sends an HTTP request to the target. For Pub/Sub targets, it publishes a message instead. A 2xx response records the execution as successful. A non-2xx response triggers the retry policy. Execution history is written to Cloud Logging automatically.

What Cloud Scheduler can trigger

HTTP and HTTPS endpoints

The most common target. Cloud Scheduler sends an HTTP request with your chosen method (GET, POST, etc.), headers, and optional body. The endpoint can be any publicly reachable URL: a Cloud Run service, a Cloud Functions endpoint, an App Engine handler, or an external HTTPS URL.

Private Cloud Run and Cloud Functions (authenticated)

For services that should not be publicly callable, Cloud Scheduler attaches an OIDC token to the request. The token proves Cloud Scheduler’s identity. The target validates the token and rejects requests without one. This is the recommended pattern for scheduled batch endpoints — see the authenticated targets section below.

Pub/Sub topics

Cloud Scheduler publishes a message to a Pub/Sub topic on the schedule. One or more subscribers receive it and act on it. This pattern decouples the trigger from the processing and is useful when multiple systems need to react to the same scheduled event.

Cloud Run Jobs (via the API)

Cloud Scheduler triggers a Cloud Run Job by calling the Cloud Run Jobs API endpoint. This is the standard pattern for scheduled batch work: the job container starts, runs to completion, and exits. See the Cloud Run Jobs section below.

When to use Cloud Scheduler

Cloud Scheduler is the right tool for any workload that runs on a predictable, recurring schedule:

• Generating daily or weekly reports and emailing them to stakeholders
• Running nightly data exports from a database to Cloud Storage
• Polling an external API every few minutes and storing the results
• Triggering cleanup jobs: deleting old records, expiring sessions, archiving logs
• Starting a Cloud Run Job for overnight batch processing
• Publishing a Pub/Sub message on a schedule to kick off an event-driven workflow
• Warming caches or pre-computing expensive queries before business hours
• Sending scheduled notifications or digest emails

The key qualifier: you know the execution time in advance, and the job runs repeatedly on that same schedule.

When not to use Cloud Scheduler

Cloud Scheduler is not a general-purpose task queue. It fires one trigger per interval and has no concept of queued items. Avoid it when:

• You need to process many individual items at a controlled rate. If user actions create background tasks that need async processing, use Cloud Tasks. It rate-limits dispatch, deduplicates tasks by name, and lets you schedule each task independently.

• You need queue semantics. Cloud Scheduler does not queue up work items or let tasks wait behind each other.

• You need per-execution deduplication. Cloud Scheduler has no named tasks per execution. Cloud Tasks lets you name individual tasks to prevent double-processing within a 4-hour window.

• The trigger comes from user activity, not a clock. If a user signing up should trigger a welcome email, that is an event. Use Pub/Sub or Cloud Tasks instead.

How to create a Cloud Scheduler job

# Enable the API first
gcloud services enable cloudscheduler.googleapis.com

HTTP job: trigger an endpoint on a schedule

# Trigger a Cloud Run service every day at 09:00 London time
gcloud scheduler jobs create http daily-report \
  --schedule="0 9 * * *" \
  --uri="https://my-service-xyz.run.app/generate-report" \
  --http-method=POST \
  --message-body='{"report":"daily"}' \
  --headers="Content-Type=application/json" \
  --time-zone="Europe/London" \
  --location=us-central1

Pub/Sub job: publish a message on a schedule

# Publish a Pub/Sub message every 5 minutes
gcloud scheduler jobs create pubsub poll-every-5 \
  --schedule="*/5 * * * *" \
  --topic=my-topic \
  --message-body='{"action":"poll"}' \
  --location=us-central1

Cron syntax reference

Cloud Scheduler uses standard Unix cron syntax with five fields:

minute   hour   day-of-month   month   day-of-week

• 0 9 * * *  — every day at 09:00
• 0 9 * * 1  — every Monday at 09:00
• */15 * * * * — every 15 minutes
• 0 0 1 * *  — first day of every month at midnight
• 0 8-18 * * 1-5 — every hour from 08:00 to 18:00, Monday to Friday
• 30 6 * * 1,3,5 — 06:30 on Monday, Wednesday, and Friday

Cloud Scheduler also accepts @hourly, @daily, @weekly, and @monthly as aliases, though explicit cron expressions are clearer for anyone reading the job configuration later.

Authenticated targets

For private Cloud Run services and Cloud Functions, Cloud Scheduler generates a short-lived OIDC token signed with a service account identity and attaches it to the Authorization header. The target service validates the token and rejects requests without one. Read more about identity and service accounts if you are new to service-to-service authentication in GCP.

# Create a dedicated service account for Cloud Scheduler
gcloud iam service-accounts create scheduler-sa \
  --display-name="Cloud Scheduler invoker"

# Grant it permission to invoke the private Cloud Run service
gcloud run services add-iam-policy-binding my-private-service \
  --region=us-central1 \
  --member=serviceAccount:scheduler-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/run.invoker

# Create the job with OIDC authentication
gcloud scheduler jobs create http call-private-service \
  --schedule="0 * * * *" \
  --uri="https://my-private-service-xyz.run.app/process" \
  --http-method=POST \
  --oidc-service-account-email=scheduler-sa@PROJECT_ID.iam.gserviceaccount.com \
  --time-zone="UTC" \
  --location=us-central1

The IAM role roles/run.invoker grants permission to call a Cloud Run service endpoint. Without it, requests return HTTP 403 even with a valid OIDC token.

Managing and testing jobs

Always run a job manually immediately after creating it. A wrong cron expression or misconfigured target URL will not surface until the next scheduled trigger. Manual execution catches these errors straight away.

# List all jobs in a region
gcloud scheduler jobs list --location=us-central1

# Run a job immediately to test it after creation
gcloud scheduler jobs run daily-report --location=us-central1

# Pause a job (it will not fire until resumed)
gcloud scheduler jobs pause daily-report --location=us-central1

# Resume a paused job
gcloud scheduler jobs resume daily-report --location=us-central1

# View last execution status and full configuration
gcloud scheduler jobs describe daily-report --location=us-central1

Triggering Cloud Run Jobs on a schedule

Cloud Run Jobs are the standard way to run batch work in GCP: a container that starts, performs a defined task, and exits. Cloud Scheduler is the standard way to trigger them on a schedule. The pattern is:

1. Build a container that performs the batch work (export, report, migration)
2. Deploy it as a Cloud Run Job
3. Create a Cloud Scheduler job that calls the Cloud Run Jobs API to start an execution

The service account needs roles/run.developer (which includes run.jobs.run) to start Cloud Run Job executions.

# Deploy a Cloud Run Job for nightly batch work
gcloud run jobs create nightly-export \
  --image=us-central1-docker.pkg.dev/PROJECT_ID/my-repo/exporter:latest \
  --region=us-central1 \
  --tasks=1 \
  --task-timeout=3600s

# Create the service account if it does not already exist
gcloud iam service-accounts create scheduler-sa \
  --display-name="Cloud Scheduler invoker"

# Grant it permission to start Cloud Run Job executions
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:scheduler-sa@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/run.developer

# Schedule it to run at 01:00 UTC every night
gcloud scheduler jobs create http run-nightly-export \
  --schedule="0 1 * * *" \
  --uri="https://run.googleapis.com/v2/projects/PROJECT_ID/locations/us-central1/jobs/nightly-export:run" \
  --http-method=POST \
  --oauth-service-account-email=scheduler-sa@PROJECT_ID.iam.gserviceaccount.com \
  --time-zone="UTC" \
  --location=us-central1

Retry behaviour and idempotency

If the target returns a non-2xx HTTP response or times out, Cloud Scheduler retries according to the policy you configure:

• Max retry attempts: up to 5 retries after the initial attempt
• Min and max backoff: how long to wait between retries, starting short and growing
• Max doublings: how many times to double the backoff before capping at the maximum
• Attempt deadline: cancel an attempt if the target has not responded within this window

# Create a job with explicit retry and timeout configuration
gcloud scheduler jobs create http daily-report \
  --schedule="0 9 * * *" \
  --uri="https://my-service-xyz.run.app/generate-report" \
  --http-method=POST \
  --time-zone="Europe/London" \
  --location=us-central1 \
  --max-retry-attempts=3 \
  --min-backoff-duration=5s \
  --max-backoff-duration=60s \
  --max-doublings=3 \
  --attempt-deadline=30m

A practical idempotency pattern: before inserting a daily report record, check whether a record for today already exists. If it does, skip the insert and return HTTP 200. This prevents duplicate records whether the duplication comes from a retry, a manual test run, or an at-least-once delivery event.

Cloud Scheduler vs Cloud Tasks

These two services are often confused because both involve triggering HTTP endpoints. They solve different problems.

Common architecture patterns

Pattern 1: Scheduler triggers a Cloud Run service endpoint

Cloud Scheduler sends an authenticated POST request to a private Cloud Run service. The service runs the job logic, returns HTTP 200, and the scheduler records success. Good for short jobs that complete within the Cloud Run request timeout.

Pattern 2: Scheduler publishes to Pub/Sub, subscribers process

Cloud Scheduler publishes a message to a Pub/Sub topic. One or more subscribers receive it and do the work. Useful when multiple services need to react to the same scheduled event, or when you want the processing logic fully decoupled from the schedule.

Pattern 3: Scheduler triggers a Cloud Run Job

Cloud Scheduler calls the Cloud Run Jobs API. A Cloud Run Job container starts, runs to completion, and exits. The preferred approach for longer batch jobs: not constrained to a request timeout, and able to scale across multiple parallel tasks.