Updraft ScheduleScheduling PreviewSince v1.2

Updraft::Schedule::MaintenanceWindow

Resolves a maintenance window from a duration, a set of acceptable days, and an optional per-region offset — emitting the start time, the end time, and the cron expression in one resource instead of three hand-aligned ones.

Required properties 4 of 8

Ref returns Window expressionsun:11:00-sun:13:00

Fn::GetAtt 8 attributes

Replacement risk None no property forces replacement

Minimal template

Every required property, nothing else

Resources:
  Window:
    Type: Updraft::Schedule::MaintenanceWindow
    Properties:
      DurationHours: 2
      PreferredDays: [SUN]
      EarliestStart: "02:00"
      TimeZone: UTC

{
  "Resources": {
    "Window": {
      "Type": "Updraft::Schedule::MaintenanceWindow",
      "Properties": {
        "DurationHours": 2,
        "PreferredDays": ["SUN"],
        "EarliestStart": "02:00",
        "TimeZone": "UTC"
      }
    }
  }
}

Without a Stagger, the window opens at EarliestStart exactly. The resource is still worth using for the derived attributes — EndTime, Ddd:hh:mm format for RDS and ElastiCache, and the cron expression — which otherwise have to be kept consistent by hand.

Overview #

A maintenance window is a start time, a duration, and — depending on which service consumes it — one of four incompatible string formats. RDS wants sun:11:00-sun:13:00 in UTC. Systems Manager wants a cron expression plus a separate duration. EventBridge wants cron(...). ElastiCache wants the RDS format but validates it differently.

Keeping those in sync by hand is the kind of task that works until somebody changes the window in one place.

This resource takes the window once and emits every dialect, plus the derived facts worth asserting on: when it ends, which day it landed on, and whether it overlaps a working day.

Composing with a stagger #

The intended shape: the stagger decides which region goes when, this resource turns that into a window, and the managed service consumes it.

Resources:
  RegionOffset:
    Type: Updraft::Region::Stagger
    Properties:
      Interval: 60
      Unit: Minutes
      Order: Geographic
      Regions: [us-west-2, us-east-1, eu-west-1, ap-southeast-2]

  Window:
    Type: Updraft::Schedule::MaintenanceWindow
    Properties:
      DurationHours: 2
      PreferredDays: [SAT, SUN]
      EarliestStart: "02:00"
      LatestStart: "06:00"       # refuse to push into the working day
      TimeZone: UTC
      OffsetMinutes: !GetAtt RegionOffset.OffsetMinutes
      Format: RdsWindow

  Database:
    Type: AWS::RDS::DBInstance
    Properties:
      Engine: postgres
      DBInstanceClass: db.t4g.medium
      AllocatedStorage: "100"
      PreferredMaintenanceWindow: !GetAtt Window.RdsWindow
      PreferredBackupWindow: "00:30-01:30"

Outputs:
  MaintenanceWindow:
    Value: !GetAtt Window.LocalDescription

!GetAtt RegionOffset.OffsetMinutes → 120eu-west-1, third in geographic order

!GetAtt Window.StartTime → 04:00

!GetAtt Window.RdsWindow → sat:04:00-sat:06:00

!GetAtt Window.LocalDescription → Saturdays 04:00–06:00 UTC

Properties

Expand a row for the full reference; nested types open in place

DurationHours IntegerHow long the window stays open. Required No interruption — updates in place
How long the window stays open.
Type
Integer
Required
Yes
Update behaviour
No interruption
Range
1 – 24
Example values
- 2
PreferredDays Array of StringDays the window may open on. Required No interruption — updates in place
With more than one day, the resource picks deterministically from the set by hashing the stack ID — so a fleet of stacks spreads across the weekend rather than all landing on Sunday.
Type
Array of String
Required
Yes
Update behaviour
No interruption
Items
1 – 7 must be unique
Allowed values
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
Example values
- ["SAT","SUN"]
EarliestStart StringEarliest local time the window may open, as HH:MM. Required No interruption — updates in place
Earliest local time the window may open, as HH:MM.
Type
String
Required
Yes
Update behaviour
No interruption
Pattern
^([01]\d|2[0-3]):([0-5]\d)$
Example values
- 02:00
TimeZone StringIANA time zone the times are expressed in. Required No interruption — updates in place
IANA time zone the times are expressed in.
Type
String
Required
Yes
Update behaviour
No interruption
Pattern
^([A-Za-z_]+/[A-Za-z_+\-0-9/]+|UTC)$
Example values
- UTC
- America/Toronto
See also: How daylight saving is handled
LatestStart StringLatest local time the window may open. Bounds the stagger offset. No interruption — updates in place
An offset that would push the start past this time fails the stack rather than silently wrapping into the working day. Set it whenever the window must not overlap business hours.
Type
String
Required
No
Update behaviour
No interruption
Pattern
^([01]\d|2[0-3]):([0-5]\d)$
Example values
- 06:00
Important
Without LatestStart, a stagger with enough regions pushes the last region’s window into the middle of its own business day. The resource has no way to know that is wrong unless you tell it.
Cutoff IntegerHours before the window closes after which no new task may start. No interruption — updates in place
Matches the Systems Manager maintenance window concept: work already running continues, but nothing new begins. A cutoff of zero means tasks may start right up to the closing minute and overrun it.
Type
Integer
Required
No
Update behaviour
No interruption
Default
1
Range
−∞ – 23
Format StringWhich dialect the primary Expression attribute is rendered in. No interruption — updates in place
RDS and ElastiCache take ddd:hh:mm-ddd:hh:mm in UTC. Systems Manager takes a cron expression with a separate duration. EventBridge takes cron(...). Every dialect is available as its own attribute regardless of this setting; Format only chooses which one Expression and Ref return.
Type
String
Required
No
Update behaviour
No interruption
Default
Cron
Allowed values
- Cron
- RdsWindow
- ElastiCacheWindow
- SsmWindow
RDS windows are always UTC, whatever TimeZone says
The ddd:hh:mm format RDS accepts has no time zone and is interpreted as UTC. This resource converts for you, which means the string it emits will not match the local time you wrote — that is correct, and LocalDescription is the attribute to check against your intent.
OffsetMinutes IntegerMinutes to add to EarliestStart. Usually wired from Updraft::Region::Stagger. No interruption — updates in place
Minutes to add to EarliestStart. Usually wired from Updraft::Region::Stagger.
Type
Integer
Required
No
Update behaviour
No interruption
Default
0
Range
−∞ – 1439
Example values
- 240

Property	Type	Required	Update	Description
DurationHours	`Integer`	Yes	None	How long the window stays open.
PreferredDays	`Array of String`	Yes	None	Days the window may open on.
EarliestStart	`String`	Yes	None	Earliest local time the window may open, as HH:MM.
TimeZone	`String`	Yes	None	IANA time zone the times are expressed in.
LatestStart	`String`	No	None	Latest local time the window may open. Bounds the stagger offset.
Cutoff	`Integer`	No	None	Hours before the window closes after which no new task may start.
Format	`String`	No	None	Which dialect the primary Expression attribute is rendered in.
OffsetMinutes	`Integer`	No	None	Minutes to add to EarliestStart. Usually wired from Updraft::Region::Stagger.

Generated from the schema. The first pair shows only required and conditionally-required properties — a template you can paste and deploy. Property keys are ordered alphabetically here rather than required-first, because that is the order a template file conventionally uses.

Type: Updraft::Schedule::MaintenanceWindow
Properties:
  DurationHours: '2'
  EarliestStart: '02:00'
  PreferredDays:
  - String
  TimeZone: UTC

{
  "Type": "Updraft::Schedule::MaintenanceWindow",
  "Properties": {
    "DurationHours": "2",
    "EarliestStart": "02:00",
    "PreferredDays": [
      "String"
    ],
    "TimeZone": "UTC"
  }
}

Every property, three levels deep:

Type: Updraft::Schedule::MaintenanceWindow
Properties:
  Cutoff: 1
  DurationHours: '2'
  EarliestStart: '02:00'
  Format: Cron
  LatestStart: '06:00'
  OffsetMinutes: '240'
  PreferredDays:
  - String
  TimeZone: UTC

{
  "Type": "Updraft::Schedule::MaintenanceWindow",
  "Properties": {
    "Cutoff": 1,
    "DurationHours": "2",
    "EarliestStart": "02:00",
    "Format": "Cron",
    "LatestStart": "06:00",
    "OffsetMinutes": "240",
    "PreferredDays": [
      "String"
    ],
    "TimeZone": "UTC"
  }
}

updates in place some interruption replacement create-only read-only write-only

Return values

What other resources can read from this one

Ref

Returns Expression, in the dialect chosen by Format.

!Ref MyResource → sun:11:00-sun:13:00

`Fn::GetAtt` attributes

Attribute	Type	Description	Example value
CronExpression	`String`	EventBridge cron for the window’s opening moment.	`cron(0 11 ? * SUN *)`
Day	`String`	The day selected from PreferredDays.	`SUN`
EndTime	`String`	Local window end.	`08:00`
Expression	`String`	The window in the dialect chosen by Format.	`sun:11:00-sun:13:00`
LocalDescription	`String`	Plain-English rendering. Put it in a stack output; it is the fastest review check there is.	`Sundays 06:00–08:00 America/Toronto (11:00–13:00 UTC)`
OverlapsBusinessHours	`Boolean`	Whether the resolved window intersects 09:00–17:00 local on a weekday.	`false`
RdsWindow	`String`	The ddd:hh:mm-ddd:hh:mm form RDS and ElastiCache accept, in UTC.	`sun:11:00-sun:13:00`
StartTime	`String`	Local window start, after the offset is applied.	`06:00`

Required permissions

For the principal running the stack operation

This type makes no AWS API calls. It is computed entirely from its own properties during the stack operation, so it needs no permissions beyond those CloudFormation already holds to manage the stack.