Skip to main content

Choose between cron and fixed-rate schedules

When you automate task executions in flyte-sdk, you need to decide whether a task should run at a specific calendar clock time (such as every day at midnight in New York) or on a regular recurring interval (such as every 45 minutes regardless of wall-clock time).

flyte-sdk provides two schedule models in flyte._trigger:

  • Cron: A clock-based schedule evaluated against standard five-field cron expressions and optional IANA timezones.
  • FixedRate: An interval-based schedule evaluated strictly in elapsed minutes, optionally anchored to an initial start time.

Both schedule types are passed into the automation parameter of Trigger and registered on task definitions via @env.task(triggers=...).

Comparison: Cron vs. FixedRate​

FeatureCronFixedRate
Cadence TypeCalendar and wall-clock timeElapsed interval duration
Precision UnitMinutes, hours, days, months, days of weekMinutes (interval_minutes: int)
Timezone SupportYes (default: "UTC", accepts IANA timezones)No (purely relative duration)
Daylight Saving (DST)Subject to 1-hour shifts/skips depending on timezoneUnaffected by clock changes
Anchor PointWall-clock matchOptional start_time: datetime
Best Used ForDaily reports, business-hour pipelines, end-of-month jobsPolling routines, metric refreshes, periodic batch syncs

Clock-Based Scheduling with Cron​

Use Cron when your execution needs to align with specific calendar dates, hours of the day, or regional business schedules.

The Cron dataclass accepts:

  • expression (str): Standard five-field cron expression string (e.g., "0 * * * *").
  • timezone (Timezone, default "UTC"): An IANA timezone identifier (e.g., "America/New_York", "Europe/London").

Expression Format​

Cron expressions use the standard five-field format:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of the week (0 - 6, Sunday to Saturday)
│ │ │ │ │
* * * * *

Note: flyte-sdk uses the 5-field cron standard. Do not provide 6-field expressions that include a seconds column.

Common patterns supported in expressions include:

  • "0 * * * *" — hourly (at minute 0)
  • "0 0 * * *" — daily at midnight
  • "0 0 * * 1" — weekly on Mondays at midnight
  • "0 0 1 * *" — monthly on the 1st at midnight
  • "*/5 * * * *" — every 5 minutes
  • "0 9-17 * * 1-5" — hourly between 9:00 AM and 5:00 PM on weekdays

Timezones and Daylight Saving Time​

The timezone parameter defaults to "UTC". You can pass any standard IANA timezone string (such as "America/New_York", "Europe/London", or "Asia/Tokyo").

Internally, Cron formats the schedule as a CRON_TZ expression via the timezone_expression property: CRON_TZ={self.timezone} {self.expression}. For instance, Cron("0 12 * * *", timezone="Europe/London") evaluates to CRON_TZ=Europe/London 0 12 * * *.

When using regional timezones that observe Daylight Saving Time (DST), note that clock shifts can affect execution times:

  • Spring forward (1-hour loss): Times in the skipped hour (for example, 2:30 AM during a 2:00 AM to 3:00 AM transition) may be skipped.
  • Fall back (1-hour gain): Times in the repeated hour may run twice or follow your cluster scheduler's deduplication policy.

If your workloads require invariant durations between runs across DST boundaries, use FixedRate instead.

Interval-Based Scheduling with FixedRate​

Use FixedRate when you want a task to run consistently every $N$ minutes, decoupled from wall-clock timestamps or calendar days.

Start Time Behavior​

The FixedRate constructor takes two arguments:

  • interval_minutes (int): The recurring interval between trigger activations in minutes (e.g., 60 for hourly, 1440 for daily).
  • start_time (datetime | None, default None): The optional anchor timestamp for the initial execution.

Execution starts according to whether start_time is configured:

  • Without start_time: The first trigger run occurs interval_minutes after the trigger is deployed and activated on the platform.
  • With start_time: The schedule is anchored to start_time. Subsequent runs occur at regular multiples of interval_minutes from that point.

Because FixedRate measures absolute elapsed time rather than clock face positions, it is unaffected by DST transitions or timezone adjustments.

Configuring Triggers​

A Trigger binds an automation schedule (Cron or FixedRate) to execution settings, resource overrides, and task inputs.

Trigger Attributes​

When defining a Trigger, you can configure the following attributes:

  • name (str): Unique identifier for the trigger (required).
  • automation (Union[Cron, FixedRate]): The schedule definition (required).
  • description (str): A description string up to 255 characters. Descriptions exceeding 255 characters are automatically truncated with ...(tr.) in __post_init__.
  • auto_activate (bool, default True): Whether the trigger activates immediately upon deployment.
  • inputs (Dict[str, Any] | None): Default input parameters passed to triggered task executions.
  • env_vars (Dict[str, str] | None): Environment variables overriding the task's base environment.
  • interruptible (bool | None): Overrides whether triggered executions run on spot/preemptible instances.
  • overwrite_cache (bool, default False): Forces cache invalidation and re-execution for triggered runs.
  • queue (str | None): Overrides the execution queue for the task.
  • labels / annotations (Mapping[str, str] | None): Kubernetes labels and annotations attached to triggered runs.
  • custom_context (Mapping[str, str] | None): Metadata propagated across the task hierarchy, readable at runtime via flyte.ctx().custom_context.

Binding Execution Timestamps with TriggerTime​

To access the exact timestamp that triggered a scheduled run inside your task, pass the TriggerTime sentinel in the inputs dictionary.

During serialization in flyte._internal.runtime.trigger_serde._to_schedule, matching the TriggerTime sentinel maps the argument name to the Protobuf schedule field kickoff_time_input_arg. The platform then supplies the scheduled kickoff time to that parameter at runtime.

Built-In Convenience Constructors​

Trigger provides factory classmethods for common cron schedules. These constructors configure standard cron expressions and accept a trigger_time_input_key parameter to automatically bind TriggerTime:

  • Trigger.minutely(trigger_time_input_key=...) -> Cron("* * * * *")
  • Trigger.hourly(trigger_time_input_key=...) -> Cron("0 * * * *")
  • Trigger.daily(trigger_time_input_key=...) -> Cron("0 0 * * *")
  • Trigger.weekly(trigger_time_input_key=...) -> Cron("0 0 * * 0") (Sundays at midnight)
  • Trigger.monthly(trigger_time_input_key=...) -> Cron("0 0 1 * *") (1st of the month at midnight)

Each convenience method also accepts standard trigger configuration overrides, including name, description, auto_activate, inputs, env_vars, interruptible, overwrite_cache, queue, labels, annotations, and custom_context.

Attaching Multiple Triggers to a Task​

You can attach multiple triggers to a single task by passing a list or tuple of Trigger objects to @env.task(triggers=...). This allows you to run the same task under different cadence configurations, timezones, or input parameters.

When deploying the task, flyte-sdk validates each trigger's inputs dictionary against the task's parameter signature and registers each trigger independently on the platform.