Start with the simple idea: some work must start because of the clock, not because someone asked.

Work that follows the calendar

Most software waits for a person to click something or for another program to call it. But a large amount of useful work has no such trigger. Nobody clicks “make the nightly report.” It simply has to happen at two in the morning. This kind of work is called scheduled work or a batch job. Typical examples are backups, report building, data clean-up, cache refreshes, billing runs and health checks.

The old way: cron on a computer

For decades, engineers solved this with a tool called cron, which comes with Linux and similar systems. You write a list of lines, each saying “at this time, run this command.” The computer checks the list every minute and starts whatever is due.

Cron is wonderful and simple, but it has a hidden weakness: it lives on one computer. If that computer is switched off, crashes, is being updated or runs out of disk space, the jobs silently stop. Nobody notices until a customer asks why the report never arrived. If you run two computers to be safe, both may start the same job and create double work. And somebody must patch, secure and monitor that computer forever.

So what is Cloud Scheduler?

Cloud Scheduler is a fully managed, enterprise-grade cron job service in Google Cloud. “Fully managed” means Google runs the servers, keeps them available and fixes them when they fail. You create a job that says three things: when to run (the schedule), what to call (the target) and how to prove who you are (the authentication). At the scheduled moment, Cloud Scheduler sends a request to the target. That is all it does, and that narrow focus is why it is dependable.

Notice what Cloud Scheduler is not. It does not run your code itself. It does not process your data. It simply knocks on a door at the right time, and the thing behind the door, such as a Cloud Run service, a Cloud Run function, a Pub/Sub topic or a web address, does the real work.

A short history

Before Cloud Scheduler, teams on Google Cloud used a feature of App Engine, the older platform, which let you list recurring tasks in a configuration file. That worked only for App Engine applications. Cloud Scheduler appeared around 2018 in beta and reached general availability around 2019, opening the same idea to everything: any HTTP address, any Pub/Sub topic, and through Google’s own APIs, nearly any Google Cloud service. Over the years it gained better authentication options, more control over retries and a larger set of regions.

Why teams choose it

Teams choose Cloud Scheduler because it removes a whole category of chores. There is no server to rent, no operating system to update and no single point of failure. Jobs can be paused, tested with a “run now” button, retried automatically and watched through the same logging and monitoring tools as the rest of Google Cloud.

A handful of words appear everywhere in this topic. Learn them once and the rest becomes easy.

Job, schedule and target

A job is the complete instruction stored in Cloud Scheduler. It has a name, a place (region), a schedule that says when, and a target that says what to call. Think of a job as one line in a very reliable calendar.

Cron expression

A cron expression is the compact notation for a schedule. It is made of five fields separated by spaces that stand for minute, hour, day of the month, month and day of the week. It looks cryptic at first, but Chapter 4 shows that only a few patterns cover nearly every real need.

Time zone

A time zone tells Cloud Scheduler which clock to follow. “Nine in the morning” means different moments in Delhi and in London. Every job carries a time zone name from a standard list known as the tz database, such as Asia/Kolkata or America/New_York.

Attempt, retry and deadline

Each time Cloud Scheduler calls the target, that call is an attempt. If the attempt fails, Cloud Scheduler may try again, which is a retry. An attempt deadline is the longest time Cloud Scheduler will wait for an answer before deciding the attempt has failed.

Idempotency

A piece of work is idempotent when doing it twice leaves the same result as doing it once. Setting a thermostat to 22 degrees is idempotent. Adding one to a counter is not. This word matters a great deal because a scheduled job can, in rare cases, be run more than once.

A quick glossary table

Scheduled versus event-driven

One idea trips up many beginners. Scheduled work starts because of time: “every night.” Event-driven work starts because something happened: “a file arrived.” Both are useful, and good systems use each where it fits. If you find yourself scheduling a job every minute just to check “has anything new arrived?”, an event-driven tool such as Eventarc or Pub/Sub is probably a better fit.

Every Cloud Scheduler job is built from the same few parts. Know them and you can read any job at a glance.

The building blocks

The payload

For HTTP targets you can choose the method (such as GET or POST), add headers (small labelled notes sent with the request) and include a body (the content of the request). The body is how you pass a small instruction, for example “build the report for the previous day in format PDF.” For Pub/Sub targets the body becomes the message data, and you can add attributes, which are small labels attached to the message.

Locations matter

Every job lives in a region, which you choose when you create it, and it cannot be moved later. If you need the job elsewhere, you create a new one. Keep jobs in the same region as the services they call when you can, because it shortens the path and makes it easier to follow data-residency rules (laws or company policies about where data may be handled). For App Engine targets, the job’s region must match the region of the App Engine application.

Job states

A job can be enabled, which means it fires on schedule, or paused, which means it exists but does not fire. Pausing is like taking the batteries out of the alarm clock without throwing the clock away. A job can also show a failed state if an update did not apply correctly, in which case you should fix and save it again. Check the current documentation for the exact list of states.

Cron notation looks like a secret code until you see its five boxes. After that it is just filling in blanks.

The five boxes

A cron expression has five fields, always in the same order. Each field says which values are allowed. A star means “every value.” A number means exactly that value. A comma lists several values. A dash gives a range. A slash gives a step, such as “every fifth.”

Everyday examples

The famous day-of-month and day-of-week surprise

In classic cron, if you fill in both the day-of-month and the day-of-week fields with something other than a star, the job runs when either matches, not when both match. Someone who writes “the 13th, if it is a Friday” will actually get every 13th and every Friday. If you need a rare combination like that, schedule on the simpler pattern and let your code check the other condition.

Also supported: plain-language intervals

Because Cloud Scheduler grew out of the App Engine cron service, it also understands a friendly style for simple rhythms, such as “every 5 minutes” or “every monday 09:00.” Many teams still prefer standard cron because it is universal, but the friendly style can be easier for newcomers. Check the current documentation for the exact phrases supported.

Time zones and daylight saving

Every job has a time zone. Cloud Scheduler follows that zone’s rules, including daylight saving time, the practice of moving clocks forward and back in some countries. This creates two tricky moments each year in those places. When clocks jump forward, one hour does not exist, so a job set inside that hour may not run at its usual time. When clocks fall back, one hour happens twice, which can make an hourly job appear to run twice.

• If exactness matters, set the job’s time zone to UTC, which never changes, and convert in your head or in your code.
• If the job must match a local business time, such as “9 a.m. for the Delhi office,” use the local zone, which for India has no daylight saving.
• Avoid scheduling important jobs in the hour that moves around during daylight saving changes.

How often is too often?

The smallest rhythm is one minute. There is no way to schedule every second. If you need something faster, that is no longer a schedule, and you should use a queue, a stream or an event-driven design. Also remember that a job does not fire at the exact stroke of the second. It usually starts within a short time after the scheduled moment, so never build logic that depends on second-level precision.

Choosing the target type is the first big design decision. It decides what can be reached, how you prove identity and how failures look.

1. HTTP targets

An HTTP target is the most flexible. Cloud Scheduler sends a web request to an address you give it. You choose the method, headers and body. That address can be a Cloud Run service, a Cloud Run function with an HTTP trigger, a service in another cloud, or a Google Cloud API. In general the address must be reachable over the internet, so if your service lives on a private network, you will usually put a Pub/Sub topic or another bridge in between. Check the current documentation for any newer private-network options.

An attempt counts as successful when the target answers with a success status, which in web language means a code in the 200 range. Other answers count as failures and may be retried.

2. Pub/Sub targets

Pub/Sub is Google Cloud’s messaging service, where a publisher sends a message to a topic and any number of subscribers receive it. With a Pub/Sub target, Cloud Scheduler publishes a message to your topic at the scheduled time. The attempt succeeds when the publish succeeds. From there, subscribers, such as Cloud Run functions or services behind push subscriptions, react.

This type is ideal when several things should happen at the same moment, when the work lives on a private network, or when you want the buffering and retry behaviour that Pub/Sub adds.

3. App Engine HTTP targets

This type sends the request to a service inside an App Engine application in the same project. It is a legacy-friendly option. For new designs, most teams choose HTTP targets pointing at Cloud Run, because Cloud Run is more flexible.

Calling Google APIs directly

A neat trick is that an HTTP target can call a Google Cloud API itself. Because Google’s APIs are just web addresses, a job can start a workflow execution, run a Cloud Run job, start a virtual machine or trigger a Dataflow template, with no code of yours in the middle. For these calls you use a type of token called OAuth, which Chapter 8 explains.

Comparing the target types

Now put the pieces on one map, so you can see how a scheduled call travels from the clock to your code.

The big picture

The picture is simple on purpose. On the left is the schedule, a cron expression plus a time zone. In the middle is the Cloud Scheduler job, which is a stored record watched by Google’s own scheduling machinery. On the right are the targets. Between the job and the target sits an authentication step that attaches proof of identity to the call.

flowchart LR
  A["Cron Schedule and Time Zone"] --> B["Cloud Scheduler Job"]
  B --> C["Fires at Scheduled Time"]
  C --> D["HTTP Target"]
  C --> E["Pub/Sub Topic"]
  C --> F["App Engine HTTP"]
  D --> G["Cloud Run Service or Function"]
  D --> H["Google API such as Workflows or Cloud Run Jobs"]
  D --> I["Any Public HTTPS Endpoint"]
  E --> J["Subscribers"]

Walking through the map

The schedule is only data. It does nothing until Cloud Scheduler’s machinery reads it. That machinery keeps track of the next due time for every job in a region and, when the moment comes, creates an attempt. The attempt builds the request, attaches a token if you asked for one, and sends it to the target. The result, success or failure, is then recorded in the logs and, if it failed, handled according to your retry settings.

The identities involved

Three identities take part, and mixing them up is a very common source of errors.

• The job’s service account is the identity you choose. Cloud Scheduler uses it to create the token that proves who is calling.
• The Cloud Scheduler service agent is a Google-managed identity used behind the scenes to do things such as mint the token for your service account.
• The person who creates the job needs permission to create jobs and to act as the chosen service account.

Regional design

Jobs are stored in a region. Google runs the scheduling machinery in a way that tolerates the loss of individual machines, so a single hardware failure does not stop your job. Even so, a whole-region problem is possible in theory. For the most important schedules, some teams create a matching job in a second region that calls a second copy of the service, and design the work so that either copy can run it safely without doing double work.

What Cloud Scheduler does not do

It does not run your code. It does not queue work for later retrying beyond its own retry settings. It does not track whether a previous run is still going. It does not chain steps together, wait for one job to finish before starting another or pass results from one job to the next. Knowing these limits helps you decide which extra pieces you need, such as Workflows for multi-step processes.

Follow one nightly run, from the clock reaching two in the morning to the report being written.

The step-by-step journey

sequenceDiagram
  participant C as Scheduler Clock
  participant J as Cloud Scheduler Job
  participant T as Token Service
  participant S as Target Service
  C->>J: Scheduled time reached
  J->>T: Request identity token for service account
  T-->>J: Signed token
  J->>S: HTTP request with token and job headers
  S-->>J: Error response 503
  Note over J,S: Wait using backoff then retry
  J->>S: Retry the same request
  S-->>J: Success response 200
  J->>J: Record attempt results in logs

The identifying headers

For HTTP targets, Cloud Scheduler adds some headers so your service can tell where a request came from. They include a header marking the call as coming from Cloud Scheduler, the name of the job and the scheduled time. The scheduled time is very useful: even if a retry happens a minute later, it carries the same scheduled time as the original attempt. Your code can use it as a natural identifier for “which run is this,” and as a way to spot a repeat.

Waiting for the answer

Cloud Scheduler waits for your target to answer, up to the attempt deadline. The default is a few minutes, and you can raise it to a larger limit, but not without bound. If your work takes longer than the deadline, Cloud Scheduler decides the attempt failed, even though your code may still be running. This leads to a classic problem: the retry starts a second copy of a job that was actually fine. The cure, which Chapter 9 explains, is to reply quickly and let the heavy work continue elsewhere.

Why the next run is planned first

Cloud Scheduler decides the next due time before or independently of how the current run ends. The result is that a slow or failed run does not push the schedule back. If your five-minute job takes six minutes, the next run still starts on its five-minute mark. That is good for punctuality, but it is also why overlapping runs can happen, which is a warning you will see again in the anti-patterns chapter.

A target that anyone can call is a target anyone can abuse. Authentication is how Cloud Scheduler proves it is the one calling.

Why authentication matters

Suppose your Cloud Run service creates a report and emails it to customers. If anyone on the internet can call it, a stranger could trigger a thousand reports and a thousand emails. By requiring a signed token, you make sure only the scheduled job, acting as the identity you chose, can trigger it.

Two kinds of token

Picking the wrong kind is one of the top reasons a new job fails with an “unauthorized” answer. A simple rule helps: your own service, use OIDC; a Google API, use OAuth.

The audience

An OIDC token carries an audience, which is the intended recipient. For Cloud Run, the audience is usually the service’s address. The service checks that the token was made for it and for no one else. If the audience does not match, the service rejects the call. When the audience is left blank, Cloud Scheduler often defaults to the target address, but check the current documentation for your target type.

The permissions chain

Exact role names can change, so follow the current setup guide for your target.

Do not leave the door open

A tempting shortcut is to allow unauthenticated calls to the Cloud Run service so that “it just works.” This means anyone who learns the address can trigger your work. Keep authentication on, and let only the job’s service account call the service. Your service should also check the token it receives, which Cloud Run does for you when you keep the service private.

This is the chapter that separates a demo from a dependable production job.

The three delivery promises

Messaging and scheduling systems usually offer one of three promises. At-most-once means a run happens zero or one time, so it can be missed but never repeated. At-least-once means one or more times, so it is never dropped on purpose but may repeat. Exactly-once means one time only, which is very hard to guarantee between separate systems. Cloud Scheduler aims for at-least-once. In rare cases, a job may be delivered more than once, so your target should be ready for repeats.

The retry settings

Defaults are sensible for many jobs, but check the current documentation for exact values and limits. Cloud Scheduler stops retrying once the count or duration limit is reached, whichever comes first, and the run is then recorded as failed until the next scheduled time.

Idempotency: doing the same thing twice safely

Because repeats can happen, make the work idempotent. Many tasks can be made safe with small tricks.

• Use the scheduled time header as a run identifier and record it. If you see the same one twice, skip the second.
• Use “create or replace” style writes that end in the same state however many times they run.
• Name output files after the run’s identifier, so a repeat overwrites the same file instead of making a second.
• Use a unique key in your database so a second insert is rejected.

Failures and what happens next

Overlapping runs

Cloud Scheduler does not wait for the previous run to finish before the next one is due. If your job takes longer than the gap between runs, two copies can work at once and step on each other, for example both rewriting the same file. Guard against this with a lock, which is a marker saying “someone is already doing this,” kept in a database or storage object. A run that finds the lock held simply exits quickly with success.

Catching up after a missed run

If a run is lost to a long outage, Cloud Scheduler does not make it up later. The best protection is to make each run process “everything since the last successful run” instead of “only the last hour.” Then a missed run is quietly recovered by the next one.

Creating a job is the easy part. Living with a hundred jobs is the real skill.

The everyday operations

Keeping jobs under control with code and review

When a team has many jobs, clicking in a console becomes risky because nobody can see who changed what. A better habit is infrastructure as code, which means describing your jobs in version-controlled files and letting a tool such as Terraform create them. Changes then go through review, and you can recreate the whole setup in a new project in minutes. This guide gives no code, but the idea is worth knowing: jobs are configuration, and configuration deserves the same care as software.

Separate environments

Keep test and production schedules apart. A test project can run its jobs every minute to prove they work, while production runs them nightly. Never let a test job point at a production target by mistake. Using different projects, different service accounts and clear name prefixes such as test- and prod- prevents such accidents.

Ownership and documentation

Every job should answer four questions in its description: what it does, who owns it, what breaks if it stops and where its runbook (a short step-by-step guide for fixing it) lives. A job without an owner is a job that will fail quietly for months.

A scheduler holds the keys to start powerful actions at any hour of the night, so every lock matters.

Identity and Access Management (IAM)

IAM is Google Cloud’s permission system. It answers the question, “Who is allowed to do what to which resource?” Permissions are grouped into roles, and roles are given to principals, such as people and service accounts. A service account is an identity for a program rather than a person.

Two separate questions

Security around Cloud Scheduler has two halves that are easy to confuse.

• Who can manage jobs? This is about people and automation who create, change, pause or run jobs. Give the job-management roles only to the small group that needs them.
• What can a job do when it fires? This is about the service account the job uses. It should hold only the exact permission needed to call its target.

The danger of power by proxy

Here is a subtle risk. Anyone who can create a job and act as a powerful service account can make that account call anything it is allowed to call, at any time. In effect, the ability to create jobs plus the ability to use a strong identity equals the strong identity’s power. This is why the permission to “act as” a service account must be handed out carefully, and why each job should use a service account with the narrowest possible reach.

Least privilege

The principle of least privilege says to give every identity only the permissions it truly needs. Create one service account per job or per group of similar jobs. A job that only needs to publish to one Pub/Sub topic should be allowed to publish to that topic and nothing else. If one account is compromised or misused, the damage stays small.

Protect the target as well

• Require authentication on the target and let only the job’s service account call it.
• Verify the token if your service is not on Cloud Run, including its audience and issuer.
• Do not trust the request body blindly. Validate it as you would any other input, because anyone who can edit a job can change the body.
• Keep secrets out of jobs. Headers and bodies are stored as plain configuration and can be seen by anyone with view permission.

Audit and control

Google Cloud keeps an audit trail of who created, changed or deleted jobs. Watch for unexpected changes, such as a new job calling an unknown address. Organization policies, which are company-wide rules, can also limit which service accounts may be used or where resources may live.

Network and data protection

Data is encrypted in transit and at rest by default. HTTP targets generally need to be reachable from Google’s network, so protect them with authentication rather than by hiding them. For private services, a Pub/Sub topic or another controlled bridge is a common pattern. Check the current documentation for newer private-connectivity options and for compatibility with VPC Service Controls, which draw a protective boundary around Google Cloud services.

A scheduler works quietly. That is a gift when it works and a trap when it fails, because nobody notices silence.

Three questions to answer

Good monitoring of scheduled work answers three simple questions. Did the job fire on time? Did the target accept and complete the work? Was the result what the business expected? Every dashboard and alert should map to one of these.

Where to look

Alerts worth having

• A rise in failed attempts for any production job.
• A job that has failed several runs in a row.
• The absence of a successful run for longer than expected, called a dead-man’s switch. If a daily job has not succeeded in twenty-six hours, someone should be told.
• Target latency growing close to the attempt deadline, a warning of duplicate runs to come.

The business check

A green tick from Cloud Scheduler only says the call was made and answered. It does not say the report is correct or the table has fresh data. For important jobs, add a business-level check: after the nightly load, a small query confirms that today’s rows exist, and an alert fires if they do not.

Correlation: following one run

When something goes wrong at 3 a.m., you will want to ask, “What happened to the run scheduled for 2 a.m.?” That is only easy if you planned for it. Put the job name and scheduled time into every log line of the target, and pass them along to any next service you call. With these two habits, a single search tells the full story.

What can you count on, what can you not, and what does it cost to keep a schedule running?

Timing precision

Cloud Scheduler is built for minute-level schedules. A job normally starts within a short time of its due moment, but not at an exact second, and brief delays are possible under load. If a task needs to happen at an exact instant, such as a market opening to the second, do not depend on a scheduler alone. Start a little early and have your code wait for the exact moment.

Reliability

The scheduling machinery is a managed, replicated service, so the loss of single machines does not stop it. Even so, treat three failure types as normal: the target is down, the network is briefly unreliable, and a run is delivered twice. A reliable design assumes all three and has a plan for each.

Limits to be aware of

Cloud Scheduler has quotas, which are caps on things like the number of jobs in a project and the allowed retry settings. The shortest rhythm is one minute. The longest attempt deadline is bounded. A job’s body has a size limit. These numbers change over time, so read the current quotas page before designing at large scale, and request an increase well before you need it.

The thundering herd

Suppose a hundred jobs are all set to fire at midnight. At 00:00, a hundred requests hit your systems at once, databases strain and everything slows down. This pile-up is called a thundering herd. Spread schedules across minutes, use odd minutes rather than round ones, and add a small random wait at the start of heavy jobs, known as jitter.

Cost

Cloud Scheduler is billed mainly per job per month, with a small free allowance, rather than per run. This makes it very cheap compared with keeping a virtual machine on just to run cron. Pricing can change, so read the current pricing page. Remember the costs around it: the target’s run time on Cloud Run, Pub/Sub messages, log volume and any downstream database calls. A schedule that fires every minute and starts heavy work will cost far more in the target than in the scheduler.

Scale in plain numbers

Because every job is its own record, Cloud Scheduler suits tens or hundreds of recurring tasks, not millions of one-off timers. If your application needs a separate reminder for each of a million users, a job per user is the wrong tool. Cloud Tasks, which can schedule an individual task for a future time, or a database-driven design, is a better fit.

No tool is perfect. A fair look at both sides helps you decide when Cloud Scheduler is the right fit.

The big trade-offs in plain words

Simplicity against control. Cloud Scheduler hides the machinery, which makes it simple. In return, you cannot tune it the way you could tune your own scheduler software.

Reliability against exactness. The service rings the bell dependably, but it does not promise the exact second or that the bell rings only once.

Narrow focus against power. It only fires requests. For multi-step processes, dependencies, waiting and complex retries, you add Workflows or a full orchestrator.

Convenience against safety. Pointing a job straight at a powerful Google API saves code, but it also puts a lot of power in a service account. Use the narrowest role you can.

A pattern is a proven way to solve a common problem. These are the ones you will use again and again.

Useful patterns

flowchart LR
  S["Cloud Scheduler Job at 02:07"] --> P["Pub/Sub Topic nightly-tick"]
  P --> A["Cleanup Function"]
  P --> B["Report Builder Service"]
  P --> C["Cache Warmer"]
  B --> D["Report Stored in Cloud Storage"]

Time-window design

Do not write code that says “process data from one hour ago until now.” If a run is late, retried or skipped, the window drifts and data is missed or counted twice. Use the scheduled time to define the window precisely: the 02:00 run handles the data from 01:00 to 02:00, whenever it actually starts. Then every retry processes the same window and gives the same answer, which is idempotency in action.

Heartbeat jobs

A heartbeat job does almost nothing except prove the system is alive. It might write a timestamp to a database every five minutes. A separate alert fires if the timestamp becomes stale. This is a cheap way to watch not only the scheduler but the whole path behind it.

An anti-pattern is a tempting mistake that causes trouble later. These are the most common ones.

sequenceDiagram
  participant S as Scheduler
  participant R1 as First Run
  participant R2 as Second Run
  S->>R1: Start heavy job
  Note over R1: Job takes 8 minutes
  S->>R2: Start next scheduled run after 5 minutes
  Note over R1,R2: Both runs touch the same data at once
  R1-->>S: First run finishes
  R2-->>S: Second run finishes

A short checklist you can use on your next build.

Best practices

Common mistakes

A simple troubleshooting order

When a job does not do what you expect, check in this order. First, is the job enabled and is its schedule and time zone what you intended? Second, does the log show that attempts were made, and what answer code came back? Third, if the answer is “unauthorized” or “forbidden,” check the token type, audience and roles. Fourth, if the answer is “not found,” check the address and region. Fifth, if the answer is a server error, look at the target’s own logs. Sixth, use “force run” to repeat the call on demand while you watch. Following the same path each time turns panic into routine.

These typical situations show how companies of many kinds use scheduled work on Google Cloud. They are illustrative patterns, not accounts of any one company’s private setup.

Google Cloud has several services that start work. Knowing the differences prevents using the wrong one.

flowchart TD
  Q["What starts your work?"] --> A{"A clock or calendar?"}
  A -->|"Yes"| B["Cloud Scheduler"]
  A -->|"No"| C{"Something happened?"}
  C -->|"Yes"| D["Eventarc or Pub/Sub"]
  C -->|"No"| E{"One delayed task from your own code?"}
  E -->|"Yes"| F["Cloud Tasks with a schedule time"]
  E -->|"No"| G["Workflows or Cloud Composer for multi-step flows"]

Scheduler and Workflows together

These two are friends, not rivals. Cloud Scheduler decides when, and Workflows decides what happens next. A job starts a workflow execution on schedule, and the workflow carries out the steps, waits, retries and error handling. This pairing keeps the scheduler simple and the process visible.

Scheduler and Cloud Tasks

Cloud Scheduler is for recurring jobs you configure ahead of time. Cloud Tasks is for work your application creates on the fly, such as “send this user a reminder in 20 minutes.” If the schedule is data that changes per customer, use Cloud Tasks or a database, not a job per customer.

If you know other clouds

Readers who know other clouds may find a loose comparison helpful: Cloud Scheduler plays a role similar to the scheduled-rule and scheduler services found on other major clouds. The match is not exact, so rely on Google Cloud’s documentation for details.

Let us put everything together by designing, on paper, a nightly sales-report flow for a small online shop.

Step 1: Write the story in one sentence

“Every night at about 2 a.m. India time, build yesterday’s sales report, store it, and email the finance team, and never email the same report twice.” This sentence names the time, the action, the result and an important rule.

Step 2: Pick the schedule and time zone

The business thinks in Indian time, which has no daylight saving, so the job uses Asia/Kolkata. To avoid the midnight stampede, the job is set for a few minutes past two, not exactly on the hour. The expression means “minute 7, hour 2, every day.”

Step 3: Choose the target

The report takes a few minutes to build, which is longer than a comfortable web answer. So the job calls a Google API to start a Cloud Run job, which can run for a long time, rather than a web service that would have to answer quickly. Because this is a Google API, the job uses an OAuth token.

Step 4: Set identities

A dedicated service account, named for this job only, receives just the permission to start that one Cloud Run job. The Cloud Run job itself has a different service account that can read the orders database and write to one storage bucket.

flowchart LR
  S["Cloud Scheduler Job at 02:07 India time"] --> R["Cloud Run Job builds report"]
  R --> D["Orders Database read only"]
  R --> B["Report File in Cloud Storage"]
  R --> M["Email to Finance Team"]
  R --> L["Cloud Logging and Alert on Missing Success"]

Step 5: Protect against the known traps

Step 6: Plan the watching

An alert fires if the job logs failed attempts, and a dead-man’s switch fires if no successful report is recorded for twenty-six hours. A small business check confirms that yesterday’s order total in the report matches a quick count from the database.

The design checklist

Quick answers to the questions that come up most often.

It uses the same schedule notation, but it is a managed service. There is no machine for you to run, and it adds retries, authentication, logging and monitoring that plain cron does not have.

No. It only sends a request or publishes a message at the scheduled time. Your code runs in the target, such as Cloud Run or a Cloud Run function.

Yes, in rare cases, and also through retries after a slow or failed answer. Design the work to be idempotent.

One minute. For anything faster, use an event-driven or streaming design instead.

Cloud Scheduler retries according to your retry settings. If all retries fail, the run is recorded as failed and the job waits for its next scheduled time. It does not make up the missed run later.

No. Runs are scheduled by the clock, so they can overlap if work takes longer than the gap. Use a lock to prevent trouble.

Use OIDC when calling your own services such as Cloud Run or Cloud Run functions. Use OAuth when calling Google Cloud APIs.

Use the force-run option to fire the job immediately, then check the target’s logs and the job’s attempt log.

HTTP targets generally need to be reachable from the internet. A common approach is to publish to Pub/Sub and let a subscriber inside your network do the work. Check the current documentation for newer private-connectivity options.

Jobs follow their time zone’s rules, so an hour may be skipped or repeated on change days in zones that use daylight saving. Use UTC, or avoid the changing hour, for important jobs.

Pricing is mainly per job per month with a small free allowance, which is usually far cheaper than a machine running cron. Pricing can change, so read the current pricing page. Also count the cost of whatever the job starts.

Usually not. Jobs suit a modest number of recurring tasks. For large numbers of per-user timers, use Cloud Tasks or a database-driven approach.

Add an alert on the absence of a successful run for longer than expected, sometimes called a dead-man’s switch, in addition to alerts on failures.

The whole guide in one place.