Amazon Route 53Networking Stable

AWS::Route53::RecordSet

Creates a DNS record in a Route 53 hosted zone, including the alias records and routing policies that make Route 53 more than a name server.

Required properties 2 of 15, plus 6 conditional

Ref returns Record nameapi.acme.example

Fn::GetAtt 0 attributes

Replacement risk 3 3 properties force replacement

Minimal template

Every required property, nothing else

Resources:
  ApiRecord:
    Type: AWS::Route53::RecordSet
    Properties:
      HostedZoneId: Z0123456789ABCDEFGHIJ
      Name: api.acme.example
      Type: A
      TTL: "300"
      ResourceRecords:
        - 203.0.113.42

{
  "Resources": {
    "ApiRecord": {
      "Type": "AWS::Route53::RecordSet",
      "Properties": {
        "HostedZoneId": "Z0123456789ABCDEFGHIJ",
        "Name": "api.acme.example",
        "Type": "A",
        "TTL": "300",
        "ResourceRecords": ["203.0.113.42"]
      }
    }
  }
}

TTL and ResourceRecords go together and are mutually exclusive with AliasTarget. A record is either a literal value with a cache lifetime, or an alias to an AWS resource whose lifetime Route 53 manages.

Overview #

A record set is one DNS record — or, under a routing policy, one candidate record among several sharing a name and type. The resource is small, and almost all of its difficulty comes from two places: the alias mechanism, and the fact that DNS is a distributed cache you do not control.

The property structure encodes a single either/or that is easy to miss:

A literal record has TTL and ResourceRecords. You supply the values and the cache lifetime.
An alias record has AliasTarget and neither of the above. Route 53 resolves the target for you and manages the lifetime.

Setting both fails. Setting neither fails. The explorer marks all three properties as conditionally required for exactly this reason.

Alias or CNAME #

The decision people get wrong most often.

An alias is resolved inside Route 53 and answered with addresses. A CNAME is answered with a name, which the client must then resolve again.

Use an alias whenever the target is an AWS resource. It works at the zone apex where a CNAME is forbidden, it saves the client a round trip, and Route 53 does not bill queries against it.

Use a CNAME when the target is not an AWS resource Route 53 can resolve — a SaaS vendor’s hostname, a partner’s endpoint.

Weighted routing across regions #

The routing policies all share one requirement: every record in the group needs a distinct SetIdentifier, and every record must specify the same policy.

Resources:
  ApiPrimary:
    Type: AWS::Route53::RecordSet
    Properties:
      HostedZoneId: !Ref HostedZone
      Name: api.acme.example
      Type: A
      SetIdentifier: us-west-2      # required by the routing policy
      Weight: 90
      AliasTarget:
        DNSName: !GetAtt UsWestLoadBalancer.DNSName
        HostedZoneId: !GetAtt UsWestLoadBalancer.CanonicalHostedZoneID
        EvaluateTargetHealth: true  # without this, failover never happens

  ApiCanary:
    Type: AWS::Route53::RecordSet
    Properties:
      HostedZoneId: !Ref HostedZone
      Name: api.acme.example
      Type: A
      SetIdentifier: eu-west-1
      Weight: 10
      AliasTarget:
        DNSName: !GetAtt EuWestLoadBalancer.DNSName
        HostedZoneId: !GetAtt EuWestLoadBalancer.CanonicalHostedZoneID
        EvaluateTargetHealth: true

{
  "Resources": {
    "ApiPrimary": {
      "Type": "AWS::Route53::RecordSet",
      "Properties": {
        "HostedZoneId": { "Ref": "HostedZone" },
        "Name": "api.acme.example",
        "Type": "A",
        "SetIdentifier": "us-west-2",
        "Weight": 90,
        "AliasTarget": {
          "DNSName": { "Fn::GetAtt": ["UsWestLoadBalancer", "DNSName"] },
          "HostedZoneId": { "Fn::GetAtt": ["UsWestLoadBalancer", "CanonicalHostedZoneID"] },
          "EvaluateTargetHealth": true
        }
      }
    },
    "ApiCanary": {
      "Type": "AWS::Route53::RecordSet",
      "Properties": {
        "HostedZoneId": { "Ref": "HostedZone" },
        "Name": "api.acme.example",
        "Type": "A",
        "SetIdentifier": "eu-west-1",
        "Weight": 10,
        "AliasTarget": {
          "DNSName": { "Fn::GetAtt": ["EuWestLoadBalancer", "DNSName"] },
          "HostedZoneId": { "Fn::GetAtt": ["EuWestLoadBalancer", "CanonicalHostedZoneID"] },
          "EvaluateTargetHealth": true
        }
      }
    }
  }
}

Properties

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

Name StringThe fully qualified domain name of the record. Required Replacement — CloudFormation creates a new resource and deletes the old one Create-only
A trailing dot is optional and normalised away. The name must be within the hosted zone — Route 53 rejects a record for other.example in a zone for acme.example.
Type
String
Required
Yes
Update behaviour
Replacement
Length
0 – 1024
Example values
- api.acme.example
Non-ASCII names must be punycode, and the API will not tell you
Route 53 stores names in a canonical form where non-ASCII characters are punycode-encoded and uppercase letters are lowercased. Submitting café.acme.example creates xn--caf-dma.acme.example, and a subsequent template that submits the same Unicode string produces no diff — until some tooling in the middle normalises differently and you get two records.
Write punycode in templates.
Type StringThe DNS record type. Required No interruption — updates in place
The DNS record type.
Type
String
Required
Yes
Update behaviour
No interruption
Allowed values
- A
- AAAA
- CAA
- CNAME
- DS
- MX
- NAPTR
- NS
- PTR
- SOA
- SPF
- SRV
- TXT
Example values
- A
Note
SPF as a record type was deprecated by RFC 7208 in 2014. Publish SPF policy as a TXT record; resolvers stopped looking at the SPF type long ago.
HostedZoneId StringID of the hosted zone the record belongs to. Conditional Replacement — CloudFormation creates a new resource and deletes the old one Create-only
Prefer this over HostedZoneName. It is unambiguous, and it is what Fn::GetAtt on an AWS::Route53::HostedZone returns.
Type
String
Required
ConditionalExactly one of HostedZoneId or HostedZoneName is required.
Update behaviour
Replacement
Length
0 – 32
Example values
- Z0123456789ABCDEFGHIJ
AliasTarget AliasTargetPoints the record at an AWS resource instead of a literal value. Conditional No interruption — updates in place
Aliases are Route 53’s answer to the DNS rule that a CNAME cannot exist at a zone apex. They also cost nothing to resolve and track the target’s addresses automatically.
Type
AliasTarget
Required
ConditionalRequired unless ResourceRecords is set.
Update behaviour
No interruption
Remarks
An alias is not a CNAME. Route 53 resolves it internally and returns the target’s A or AAAA records directly, so clients never see the indirection, the apex restriction does not apply, and queries against alias records are not billed.
The cost is that the target must be an AWS resource Route 53 knows how to resolve — a load balancer, CloudFront distribution, S3 website endpoint, API Gateway domain, or another record in the same zone. An arbitrary hostname needs a real CNAME.
AliasTarget properties
- DNSName StringDNS name of the target resource. Required No interruption — updates in place
  DNS name of the target resource.
  Type
  String
  Required
  Yes
  Update behaviour
  No interruption
  Example values
  d111111abcdef8.cloudfront.net
- HostedZoneId StringThe **target's** hosted zone ID, not the zone the record lives in. Required No interruption — updates in place
  The **target's** hosted zone ID, not the zone the record lives in.
  Type
  String
  Required
  Yes
  Update behaviour
  No interruption
  Example values
  Z2FDTNDATAQYW2
  This is the most-confused field in Route 53
  It is the canonical hosted zone of the target service, and for several services it is a fixed magic value that has nothing to do with your account. CloudFront is always Z2FDTNDATAQYW2 everywhere. Load balancers have one per region. S3 website endpoints have one per region.
  Putting your own zone ID here produces InvalidChangeBatch: Tried to create an alias that targets ..., which does not mention that the wrong zone was supplied.
  Get it from the target resource with Fn::GetAtt (!GetAtt LoadBalancer.CanonicalHostedZoneID) rather than hard-coding it.
- EvaluateTargetHealth BooleanWhether the target's own health influences this record. No interruption — updates in place
  Turning this on is what makes an alias to a load balancer fail over when the load balancer has no healthy targets. Leaving it off means the record keeps answering while the target is down.
  Type
  Boolean
  Required
  No
  Update behaviour
  No interruption
  Default
  false
HostedZoneName StringName of the hosted zone, with a trailing dot. Conditional Replacement — CloudFormation creates a new resource and deletes the old one Create-only
Name of the hosted zone, with a trailing dot.
Type
String
Required
ConditionalExactly one of HostedZoneId or HostedZoneName is required.
Update behaviour
Replacement
Example values
- acme.example.
Ambiguous when public and private zones share a name
A split-horizon setup has two zones called acme.example., and this property cannot distinguish them — the stack fails with a “found more than one hosted zone” error that names neither zone.
Whenever a private hosted zone exists, use HostedZoneId.
ResourceRecords Array of StringThe record values. Conditional No interruption — updates in place
For TXT, each value must be individually quoted inside the string, and any value over 255 characters must be split into several quoted strings that resolvers concatenate — a DKIM key is the usual reason to care.
Type
Array of String
Required
ConditionalRequired unless AliasTarget is set.
Update behaviour
No interruption
Example values
- ["203.0.113.42"]
SetIdentifier StringDistinguishes records that share a name and type under a routing policy. Conditional No interruption — updates in place
Distinguishes records that share a name and type under a routing policy.
Type
String
Required
ConditionalRequired whenever a routing policy is used — Weight, Failover, Region, GeoLocation, or MultiValueAnswer.
Update behaviour
No interruption
Length
1 – 128
Example values
- us-west-2
TTL StringSeconds resolvers may cache the record. Written as a string, not a number. Conditional No interruption — updates in place
The string type is a quirk of the underlying API, faithfully reproduced. TTL: 300 in YAML is a number and fails validation; TTL: "300" is correct.
Type
String
Required
ConditionalRequired with ResourceRecords. Must be omitted with AliasTarget.
Update behaviour
No interruption
Example values
- 300
Tip
Lower the TTL well before a planned change, not during it. Resolvers hold the old value for up to the old TTL, so dropping from 3600 to 60 at cutover time still means an hour of stale answers. Drop it an hour ahead, cut over, then raise it again.
Comment StringComment attached to the change batch, not to the record. No interruption — updates in place
Visible in the Route 53 change history and nowhere else. It does not appear when listing records.
Type
String
Required
No
Update behaviour
No interruption
Length
0 – 256
Failover StringRole of this record in a failover pair. No interruption — updates in place
The primary record must have an associated health check, or failover never triggers — Route 53 has no other way to know the primary is unhealthy.
Type
String
Required
No
Update behaviour
No interruption
Allowed values
- PRIMARY
- SECONDARY
GeoLocation GeoLocationGeographic scope for geolocation routing. No interruption — updates in place
Geographic scope for geolocation routing.
Type
GeoLocation
Required
No
Update behaviour
No interruption
Important
Always create a default record with CountryCode: "*". Queries from a location matching no rule receive NOERROR with no answer, which clients experience as the domain not existing rather than as a routing gap.
GeoLocation properties
- ContinentCode StringTwo-letter continent code. Mutually exclusive with CountryCode. No interruption — updates in place
  Two-letter continent code. Mutually exclusive with CountryCode.
  Type
  String
  Required
  No
  Update behaviour
  No interruption
  Allowed values
  AF
  AN
  AS
  EU
  OC
  NA
  SA
- CountryCode StringISO 3166-1 alpha-2 country code, or `*` for the default record. No interruption — updates in place
  ISO 3166-1 alpha-2 country code, or `*` for the default record.
  Type
  String
  Required
  No
  Update behaviour
  No interruption
  Example values
  CA
- SubdivisionCode StringState or province code. Only valid when the country code is US. No interruption — updates in place
  State or province code. Only valid when the country code is US.
  Type
  String
  Required
  No
  Update behaviour
  No interruption
  Example values
  WA
HealthCheckId StringHealth check that gates whether this record is returned. No interruption — updates in place
Health check that gates whether this record is returned.
Type
String
Required
No
Update behaviour
No interruption
Example values
- abcdef01-2345-6789-abcd-ef0123456789
MultiValueAnswer BooleanReturn up to eight healthy records in a random order. No interruption — updates in place
A cheap approximation of load balancing that is not a load balancer: it has no connection awareness, no draining, and depends entirely on client resolver behaviour to spread load.
Type
Boolean
Required
No
Update behaviour
No interruption
Region StringAWS region for latency-based routing. No interruption — updates in place
Route 53 answers with the record whose region has the lowest measured latency from the resolver — not from the client, and not by geographic distance.
Type
String
Required
No
Update behaviour
No interruption
Example values
- us-west-2
Weight IntegerRelative share of traffic for weighted routing. No interruption — updates in place
Each record receives its weight divided by the sum of weights across the group. Weight 0 removes a record from rotation without deleting it, which is the standard way to drain a target.
Type
Integer
Required
No
Update behaviour
No interruption
Range
−∞ – 255
Example values
- 100
All-zero weights do not mean no traffic
If every record in a weighted group has weight 0, Route 53 treats them as equally weighted and returns them in rotation. Setting everything to zero to “turn off” a service does the opposite of what it looks like.

Property	Type	Required	Update	Description
Name	`String`	Yes	Replacement	The fully qualified domain name of the record.
Type	`String`	Yes	None	The DNS record type.
HostedZoneId	`String`	Conditional	Replacement	ID of the hosted zone the record belongs to.
AliasTarget	`AliasTarget`	Conditional	None	Points the record at an AWS resource instead of a literal value.
AliasTarget.DNSName	`String`	Yes	None	DNS name of the target resource.
AliasTarget.HostedZoneId	`String`	Yes	None	The target's hosted zone ID, not the zone the record lives in.
AliasTarget.EvaluateTargetHealth	`Boolean`	No	None	Whether the target's own health influences this record.
HostedZoneName	`String`	Conditional	Replacement	Name of the hosted zone, with a trailing dot.
ResourceRecords	`Array of String`	Conditional	None	The record values.
SetIdentifier	`String`	Conditional	None	Distinguishes records that share a name and type under a routing policy.
TTL	`String`	Conditional	None	Seconds resolvers may cache the record. Written as a string, not a number.
Comment	`String`	No	None	Comment attached to the change batch, not to the record.
Failover	`String`	No	None	Role of this record in a failover pair.
GeoLocation	`GeoLocation`	No	None	Geographic scope for geolocation routing.
GeoLocation.ContinentCode	`String`	No	None	Two-letter continent code. Mutually exclusive with CountryCode.
GeoLocation.CountryCode	`String`	No	None	ISO 3166-1 alpha-2 country code, or `*` for the default record.
GeoLocation.SubdivisionCode	`String`	No	None	State or province code. Only valid when the country code is US.
HealthCheckId	`String`	No	None	Health check that gates whether this record is returned.
MultiValueAnswer	`Boolean`	No	None	Return up to eight healthy records in a random order.
Region	`String`	No	None	AWS region for latency-based routing.
Weight	`Integer`	No	None	Relative share of traffic for weighted routing.

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: AWS::Route53::RecordSet
Properties:
  AliasTarget:
    DNSName: d111111abcdef8.cloudfront.net
    HostedZoneId: Z2FDTNDATAQYW2
  HostedZoneId: Z0123456789ABCDEFGHIJ
  HostedZoneName: acme.example.
  Name: api.acme.example
  ResourceRecords:
  - String
  SetIdentifier: us-west-2
  TTL: '300'
  Type: A

{
  "Type": "AWS::Route53::RecordSet",
  "Properties": {
    "AliasTarget": {
      "DNSName": "d111111abcdef8.cloudfront.net",
      "HostedZoneId": "Z2FDTNDATAQYW2"
    },
    "HostedZoneId": "Z0123456789ABCDEFGHIJ",
    "HostedZoneName": "acme.example.",
    "Name": "api.acme.example",
    "ResourceRecords": [
      "String"
    ],
    "SetIdentifier": "us-west-2",
    "TTL": "300",
    "Type": "A"
  }
}

Every property, three levels deep:

Type: AWS::Route53::RecordSet
Properties:
  AliasTarget:
    DNSName: d111111abcdef8.cloudfront.net
    EvaluateTargetHealth: false
    HostedZoneId: Z2FDTNDATAQYW2
  Comment: String
  Failover: PRIMARY
  GeoLocation:
    ContinentCode: AF
    CountryCode: CA
    SubdivisionCode: WA
  HealthCheckId: abcdef01-2345-6789-abcd-ef0123456789
  HostedZoneId: Z0123456789ABCDEFGHIJ
  HostedZoneName: acme.example.
  MultiValueAnswer: false
  Name: api.acme.example
  Region: us-west-2
  ResourceRecords:
  - String
  SetIdentifier: us-west-2
  TTL: '300'
  Type: A
  Weight: '100'

{
  "Type": "AWS::Route53::RecordSet",
  "Properties": {
    "AliasTarget": {
      "DNSName": "d111111abcdef8.cloudfront.net",
      "EvaluateTargetHealth": false,
      "HostedZoneId": "Z2FDTNDATAQYW2"
    },
    "Comment": "String",
    "Failover": "PRIMARY",
    "GeoLocation": {
      "ContinentCode": "AF",
      "CountryCode": "CA",
      "SubdivisionCode": "WA"
    },
    "HealthCheckId": "abcdef01-2345-6789-abcd-ef0123456789",
    "HostedZoneId": "Z0123456789ABCDEFGHIJ",
    "HostedZoneName": "acme.example.",
    "MultiValueAnswer": false,
    "Name": "api.acme.example",
    "Region": "us-west-2",
    "ResourceRecords": [
      "String"
    ],
    "SetIdentifier": "us-west-2",
    "TTL": "300",
    "Type": "A",
    "Weight": "100"
  }
}

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 record’s fully qualified domain name, in Route 53’s canonical form — lowercased and punycode-encoded, which may not be the string you supplied.

!Ref MyResource → api.acme.example

`Fn::GetAtt` attributes

This resource exposes no Fn::GetAtt attributes.

Required permissions

For the principal running the stack operation

create

route53:ChangeResourceRecordSets
route53:GetChange
route53:ListHostedZonesByName

read

route53:ListResourceRecordSets

update

route53:ChangeResourceRecordSets
route53:GetChange

delete

route53:ChangeResourceRecordSets
route53:GetChange

list

route53:ListResourceRecordSets

{
  "Statement": [
    {
      "Action": [
        "route53:ChangeResourceRecordSets",
        "route53:GetChange",
        "route53:ListHostedZonesByName",
        "route53:ListResourceRecordSets"
      ],
      "Effect": "Allow",
      "Resource": "*",
      "Sid": "ManageResource"
    }
  ],
  "Version": "2012-10-17"
}

Statement:
- Action:
  - route53:ChangeResourceRecordSets
  - route53:GetChange
  - route53:ListHostedZonesByName
  - route53:ListResourceRecordSets
  Effect: Allow
  Resource: '*'
  Sid: ManageResource
Version: '2012-10-17'