Updraft RegionMulti-region StableSince v1.1

Updraft::Region::Stagger

Computes a deterministic per-region offset, so the same template deployed to twelve regions produces twelve different start times instead of twelve simultaneous ones.

Required properties 1 of 8

Ref returns Offset in minutes90

Fn::GetAtt 6 attributes

Replacement risk None no property forces replacement

Minimal template

Every required property, nothing else

Resources:
  RolloutOffset:
    Type: Updraft::Region::Stagger
    Properties:
      Interval: 30

{
  "Resources": {
    "RolloutOffset": {
      "Type": "Updraft::Region::Stagger",
      "Properties": { "Interval": 30 }
    }
  }
}

With no Regions list, the region set defaults to every region enabled in the account. OffsetMinutes is then this region’s position in that ordering, multiplied by Interval.

Overview #

Deploy the same template to twelve regions and you get twelve identical schedules. Every backup starts at 03:00 UTC, every maintenance window opens simultaneously, and every one of them hits the same regional service endpoints at the same moment.

Updraft::Region::Stagger gives each region a deterministic position in an ordering and turns that into an offset. Nothing about it is random, and the same region always gets the same answer.

Ordering #

Template

Resources:
  RolloutOffset:
    Type: Updraft::Region::Stagger
    Properties:
      Interval: 2
      Unit: Hours
      Anchor: "01:00"
      Order: Explicit
      Regions:
        - us-west-2      # we watch this one
        - us-east-1
        - eu-west-1
        - ap-southeast-2

Result in eu-west-1

Index:          2
Total:          4
Offset:         4      # 2 intervals x 2 hours
OffsetMinutes:  240
StartTime:      "05:00"
OrderedRegions:
  - us-west-2
  - us-east-1
  - eu-west-1
  - ap-southeast-2

!Ref RolloutOffset → 240OffsetMinutes, for direct substitution

!GetAtt RolloutOffset.StartTime → 05:00

Combining with a schedule #

The two resources compose: the stagger produces a start time, the cron resource turns it into an expression.

Resources:
  MaintenanceOffset:
    Type: Updraft::Region::Stagger
    Properties:
      Interval: 90
      Unit: Minutes
      Anchor: "02:00"
      Order: Geographic          # follow the sun, west to east
      Regions: !Ref TargetRegions

  MaintenanceSchedule:
    Type: Updraft::Schedule::CronExpression
    Properties:
      Behavior: Weekly
      DaysOfWeek: [SUN]
      Time: !GetAtt MaintenanceOffset.StartTime
      TimeZone: UTC

Outputs:
  Window:
    Value: !GetAtt MaintenanceSchedule.LocalDescription
  RegionOrder:
    Description: The ordering this deployment computed — worth recording.
    Value: !Join [",", !GetAtt MaintenanceOffset.OrderedRegions]

Properties

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

Interval IntegerSpacing between consecutive regions, in the unit given by Unit. Required No interruption — updates in place
Spacing between consecutive regions, in the unit given by Unit.
Type
Integer
Required
Yes
Update behaviour
No interruption
Range
1 – 1440
Example values
- 30
Unit StringUnit for Interval and for the computed offset. No interruption — updates in place
Unit for Interval and for the computed offset.
Type
String
Required
No
Update behaviour
No interruption
Default
Minutes
Allowed values
- Minutes
- Hours
- Days
Anchor StringBase time the offset is added to, as HH:MM. Required to compute StartTime. No interruption — updates in place
Without an anchor the resource yields an offset only. With one, it also yields the resolved local start time, which is usually what the consuming resource actually wants.
Type
String
Required
No
Update behaviour
No interruption
Pattern
^([01]\d|2[0-3]):([0-5]\d)$
Example values
- 02:00
Order StringHow the region set is ordered before offsets are assigned. No interruption — updates in place
- Alphabetical — by region code. Predictable, and groups by continent prefix as a side effect.
- Explicit — the order given in Regions, unchanged. Use when the rollout order is a deliberate blast-radius decision.
- Hash — stable pseudo-random order seeded by Seed. Spreads without implying that ap- regions are always last.
- Geographic — ordered west to east by the region’s primary longitude, so a “follow the sun” rollout falls out naturally.
Type
String
Required
No
Update behaviour
No interruption
Default
Alphabetical
Allowed values
- Alphabetical
- Explicit
- Hash
- Geographic
Region StringThe region to compute the offset for. Defaults to the deploying region. No interruption — updates in place
Overriding this is mainly useful in a hub stack that needs to know what offset a different region will get — for example, to build a rollout timetable as a stack output.
Type
String
Required
No
Update behaviour
No interruption
Example values
- eu-west-1
Regions Array of StringThe region set to position this region within. Defaults to the account's enabled regions. No interruption — updates in place
Listing regions explicitly is strongly preferred for anything whose ordering matters. The enabled-region default changes whenever somebody enables a region in the account, which silently renumbers every region after it in the ordering.
Type
Array of String
Required
No
Update behaviour
No interruption
Items
1 – 50 must be unique
Example values
- ["us-east-1","us-west-2","eu-west-1","ap-southeast-2"]
Enabling a new region reshuffles existing offsets
With the default region set, enabling ca-central-1 in the account inserts it into the alphabetical ordering and shifts every region after it by one interval. The next stack update in each of those regions moves its schedule.
Nothing fails, no alarm fires, and the change surfaces weeks later as “why did the Sydney maintenance window move”. Pin Regions explicitly for any stagger that other teams depend on.
Seed StringSeed for Hash ordering. Defaults to the stack name. No interruption — updates in place
Two stacks sharing a seed produce the same ordering, which is how you keep several related schedules in the same relative sequence.
Type
String
Required
No
Update behaviour
No interruption
Example values
- platform-rollout-2026
Wrap BooleanWhether the offset wraps at 24 hours rather than running past midnight. No interruption — updates in place
With twelve regions at two-hour intervals, the twelfth region’s offset is 22 hours. Wrapping keeps every region inside a single day; disabling it lets a long stagger deliberately run into the following day.
Type
Boolean
Required
No
Update behaviour
No interruption
Default
true

Property	Type	Required	Update	Description
Interval	`Integer`	Yes	None	Spacing between consecutive regions, in the unit given by Unit.
Unit	`String`	No	None	Unit for Interval and for the computed offset.
Anchor	`String`	No	None	Base time the offset is added to, as HH:MM. Required to compute StartTime.
Order	`String`	No	None	How the region set is ordered before offsets are assigned.
Region	`String`	No	None	The region to compute the offset for. Defaults to the deploying region.
Regions	`Array of String`	No	None	The region set to position this region within. Defaults to the account's enabled regions.
Seed	`String`	No	None	Seed for Hash ordering. Defaults to the stack name.
Wrap	`Boolean`	No	None	Whether the offset wraps at 24 hours rather than running past midnight.

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::Region::Stagger
Properties:
  Interval: '30'

{
  "Type": "Updraft::Region::Stagger",
  "Properties": {
    "Interval": "30"
  }
}

Every property, three levels deep:

Type: Updraft::Region::Stagger
Properties:
  Anchor: '02:00'
  Interval: '30'
  Order: Alphabetical
  Region: eu-west-1
  Regions:
  - String
  Seed: platform-rollout-2026
  Unit: Minutes
  Wrap: true

{
  "Type": "Updraft::Region::Stagger",
  "Properties": {
    "Anchor": "02:00",
    "Interval": "30",
    "Order": "Alphabetical",
    "Region": "eu-west-1",
    "Regions": [
      "String"
    ],
    "Seed": "platform-rollout-2026",
    "Unit": "Minutes",
    "Wrap": true
  }
}

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

Return values

What other resources can read from this one

Ref

Returns OffsetMinutes as a string, for direct substitution into another property.

!Ref MyResource → 90

`Fn::GetAtt` attributes

Attribute	Type	Description	Example value
Index	`Integer`	Zero-based position of this region in the ordering.	`3`
Offset	`Integer`	This region’s offset expressed in Unit.	`3`
OffsetMinutes	`Integer`	This region’s offset from the anchor, always normalised to minutes regardless of Unit.	`90`
OrderedRegions	`Array`	The full ordering that was used. Worth putting in a stack output — it is the only way to see the ordering a deployment actually computed.	`["us-east-1","us-west-2","eu-west-1"]`
StartTime	`String`	Anchor plus offset, as HH:MM. Empty when Anchor is not set.	`03:30`
Total	`Integer`	Number of regions in the set.	`12`

Required permissions

For the principal running the stack operation

create

account:ListRegions

read

account:ListRegions

update

account:ListRegions

delete

No actions required

{
  "Statement": [
    {
      "Action": [
        "account:ListRegions"
      ],
      "Effect": "Allow",
      "Resource": "*",
      "Sid": "ManageResource"
    }
  ],
  "Version": "2012-10-17"
}

Statement:
- Action:
  - account:ListRegions
  Effect: Allow
  Resource: '*'
  Sid: ManageResource
Version: '2012-10-17'