Updraft RegionMulti-region StableSince v1.1

Updraft::Region::Metadata

Exposes facts about an AWS region — partition, DNS suffix, availability-zone count, opt-in status, geography — so a template can adapt to where it is deploying instead of carrying a mapping table that goes stale.

Required properties 0 of 4

Ref returns Region codeap-southeast-2

Fn::GetAtt 10 attributes

Replacement risk None no property forces replacement

Minimal template

Every required property, nothing else

Resources:
  Here:
    Type: Updraft::Region::Metadata
    Properties: {}

{
  "Resources": {
    "Here": {
      "Type": "Updraft::Region::Metadata",
      "Properties": {}
    }
  }
}

With no properties at all, the resource describes the region the stack is deploying into. That is the common case; Region exists for hub stacks that need to reason about somewhere else.

Overview #

Templates that deploy to more than one region tend to accumulate a Mappings block: a hand-maintained table of region codes to availability zone counts, DNS suffixes, and AMI IDs. It is correct on the day it is written. It is wrong the next time AWS launches a region, and nothing fails until somebody deploys there.

Updraft::Region::Metadata resolves those facts at deploy time instead.

Guarding against a region that is too small #

The most useful thing this resource does is fail early.

Resources:
  Here:
    Type: Updraft::Region::Metadata
    Properties:
      RequireAvailabilityZones: 3
      Fields: [AvailabilityZones, Partition]

  SubnetA:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref Vpc
      CidrBlock: 10.0.0.0/24
      AvailabilityZone: !Select [0, !GetAtt Here.AvailabilityZoneNames]

  SubnetB:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref Vpc
      CidrBlock: 10.0.1.0/24
      AvailabilityZone: !Select [1, !GetAtt Here.AvailabilityZoneNames]

Deploying this into a two-zone region fails immediately, before the VPC is created, with a message naming the region and the requirement. Without the guard, it fails at SubnetC with Value (us-xxxx-1c) for parameter availabilityZone is invalid — which is true but unhelpful.

!GetAtt Here.AvailabilityZoneCount → 3

!GetAtt Here.Partition → aws

!GetAtt Here.DnsSuffix → amazonaws.comamazonaws.com.cn in the China partition

Properties

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

Region StringThe region to describe. Defaults to the deploying region. No interruption — updates in place
The region to describe. Defaults to the deploying region.
Type
String
Required
No
Update behaviour
No interruption
Pattern
^[a-z]{2}(-gov)?(-iso[a-z]?)?-[a-z]+-\d$ Region code, including GovCloud and isolated-partition forms.
Example values
- ap-southeast-2
ExcludeConstrainedZones BooleanWhether to omit availability zones with known capacity constraints. No interruption — updates in place
Some zones exist but cannot launch current-generation instance types. When true, those zones are excluded from AvailabilityZoneNames and from the count, so a subnet layout built from this resource will not land in a zone that cannot host anything.
Type
Boolean
Required
No
Update behaviour
No interruption
Default
true
Fields Array of StringRestrict which facts are resolved, reducing the API calls made. No interruption — updates in place
Every requested field costs at least one describe call at stack-operation time. Restricting the set matters in a stack that creates this resource per region.
Type
Array of String
Required
No
Update behaviour
No interruption
Allowed values
- Partition
- Geography
- AvailabilityZones
- OptIn
- Endpoints
- LaunchYear
Example values
- ["Partition","AvailabilityZones"]
RequireAvailabilityZones IntegerFail the stack operation if the region has fewer usable AZs than this. No interruption — updates in place
A three-AZ template deployed into a two-AZ region fails somewhere in the middle, having already created half a network. This turns that into an immediate, legible failure at the start of the operation.
Type
Integer
Required
No
Update behaviour
No interruption
Range
1 – 6
Example values
- 3
Tip
Pair this with AvailabilityZoneNames and index into it, rather than calling Fn::GetAZs and assuming three entries. Fn::GetAZs returns what the account can see, which is not the same as what the region has — AZ availability is per-account.

Property	Type	Required	Update	Description
Region	`String`	No	None	The region to describe. Defaults to the deploying region.
ExcludeConstrainedZones	`Boolean`	No	None	Whether to omit availability zones with known capacity constraints.
Fields	`Array of String`	No	None	Restrict which facts are resolved, reducing the API calls made.
RequireAvailabilityZones	`Integer`	No	None	Fail the stack operation if the region has fewer usable AZs than this.

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::Metadata
Properties:
  {}

{
  "Type": "Updraft::Region::Metadata",
  "Properties": {}
}

Every property, three levels deep:

Type: Updraft::Region::Metadata
Properties:
  ExcludeConstrainedZones: true
  Fields:
  - String
  Region: ap-southeast-2
  RequireAvailabilityZones: '3'

{
  "Type": "Updraft::Region::Metadata",
  "Properties": {
    "ExcludeConstrainedZones": true,
    "Fields": [
      "String"
    ],
    "Region": "ap-southeast-2",
    "RequireAvailabilityZones": "3"
  }
}

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

Return values

What other resources can read from this one

Ref

Returns the region code that was described.

!Ref MyResource → ap-southeast-2

`Fn::GetAtt` attributes

Attribute	Type	Description	Example value
AvailabilityZoneCount	`Integer`	Number of usable availability zones, after ExcludeConstrainedZones is applied.	`3`
AvailabilityZoneNames	`Array`	The usable zone names, sorted. Index into this rather than into Fn::GetAZs.	`["ap-southeast-2a","ap-southeast-2b","ap-southeast-2c"]`
City	`String`	The region’s primary metropolitan location.	`Sydney`
Country	`String`	ISO 3166-1 alpha-2 country code of the region’s primary location.	`AU`
DnsSuffix	`String`	The partition’s service DNS suffix. Never hard-code amazonaws.com in a template that might deploy to China.	`amazonaws.com`
Geography	`String`	Broad geography of the region.	`Asia Pacific`
IsOptIn	`Boolean`	Whether the region must be explicitly enabled in an account before use.	`false`
LaunchYear	`Integer`	Year the region became generally available. A rough proxy for which services and instance families are present.	`2012`
LongitudeDegrees	`Number`	Approximate longitude, used by Updraft::Region::Stagger for geographic ordering.	`151.2`
Partition	`String`	The ARN partition — aws, aws-cn, aws-us-gov, or an isolated partition.	`aws`

Required permissions

For the principal running the stack operation

create

ec2:DescribeAvailabilityZones
account:ListRegions
account:GetRegionOptStatus

read

ec2:DescribeAvailabilityZones
account:ListRegions

update

ec2:DescribeAvailabilityZones
account:ListRegions
account:GetRegionOptStatus

delete

No actions required

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

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