Menu
Amazon Route 53
API Reference

Traffic Policy Document Format

When you create a traffic policy programmatically by using the Amazon Route 53 API, one of the AWS SDKs, the AWS CLI, or AWS Tools for Windows PowerShell, you specify the definition of the traffic policy in a Document element in JSON format.

For more information about traffic policies, see Using Traffic Flow to Route DNS Traffic in the Amazon Route 53 Developer Guide.

Basic Syntax

Here is the basic syntax for a traffic policy document:

Copy
{ "AWSPolicyFormatVersion": "2015-10-01", "RecordType": "DNS type for all resource record sets created by this traffic policy", "StartEndpoint | StartRule": "ID that you assign to an endpoint or rule", "Endpoints": { "Endpoint ID that you assign": { Endpoint definition }, ... }, "Rules": { "Rule ID that you assign": { Rule definition }, ... } }

The basic syntax for a traffic policy document contains the following objects:

AWSPolicyFormatVersion

The version of the traffic policy format, currently 2015-10-01.

RecordType

The DNS type of all of the resource record sets that Amazon Route 53 will create based on this traffic policy. If you want to route traffic to the following AWS resources, choose the applicable value:

  • CloudFront distribution – Choose A: IP address in IPv4 format.

  • ELB load balancer – Choose either A: IP address in IPv4 format or AAAA: IP address in IPv6 format.

  • Amazon S3 bucket configured as a website endpoint: Choose A: IP address in IPv4 format.

If you want to route traffic to other resources, choose the applicable type for the resource. For example, if you want to route traffic to mail servers, specify MX. For the list of DNS types that Amazon Route 53 supports, see Supported DNS Resource Record Types in the Amazon Route 53 Developer Guide.

StartEndpoint | StartRule

Whether you want the starting point for the traffic policy to be an endpoint or a rule, and the ID that you assigned to the endpoint or rule elsewhere in the traffic policy document.

Endpoints

The definitions of the endpoints that you want to use in this traffic policy. For more information, see Syntax for Endpoint Definitions.

Rules

The definitions of the rules that you want to use in this traffic policy. For more information, see Syntax for Rule Definitions.

Syntax for Endpoint Definitions

Here is the syntax for the endpoint definitions that you specify in a traffic policy document:

Copy
{ "Type": value | cloudfront | elastic-load-balancer | s3-website, "Region": "AWS region that you created your Amazon S3 bucket in" "Value": "value applicable to the type of endpoint" }

The syntax for an endpoint definition contains the following objects:

Type

Specify the applicable value:

value

To route traffic to a resource other than a CloudFront distribution, an ELB load balancer, or an Amazon S3 bucket that is configured as a website endpoint, specify value for Type.

cloudfront

To route traffic to a CloudFront distribution, specify cloudfront for Type.

elastic-load-balancer

To route traffic to an ELB load balancer, specify elastic-load-balancer for Type.

s3-website

To route traffic to an Amazon S3 bucket that is configured as a website endpoint, specify s3-website for Type.

Region

To route traffic to an Amazon S3 bucket that is configured as a website endpoint, specify the region in which you created the bucket for Region. For any other resource, omit Region.

Value

Specify the applicable value:

value

To route traffic to a resource other than a CloudFront distribution, an ELB load balancer, or an Amazon S3 bucket that is configured as a website endpoint, specify the value that corresponds with the value that you specified for RecordType. For example, if you specified A for RecordType, specify an IP address in IPv4 format for Value.

cloudfront

If you specified cloudfront for Type, specify the domain name that CloudFront assigned to your CloudFront distribution when you created it, for example, d111111abcdef8.cloudfront.net.

elastic-load-balancer

If you specified elastic-load-balancer for Type, specify the DNS name for your load balancer. Use the value that begins with dualstack, for example, dualstack.my-load-balancer-1234567890.us-west-2.elb.amazonaws.com.

s3-website

If you specified s3-website for Type, specify the name of your Amazon S3 bucket, for example, example.com.s3-website-us-east-1.amazonaws.com.

Important

When you create a traffic policy instance based on this traffic policy, the bucket that you specify here must match the domain name (such as www.example.com) that you specify for Name in the CreateTrafficPolicyInstance request. If Value and Name don't match, Amazon S3 won't respond to DNS queries for the domain name.

Syntax for Rule Definitions

There are different syntaxes for the rule definitions that you specify in a traffic policy document, depending on the type of routing policy that you want to use: failover, geolocation, latency, multivalue answer, or weighted.

Failover Rules

For more information, see Configuring DNS Failover in the Amazon Route 53 Developer Guide.

Copy
{ "RuleType": "failover", "Primary": { "EndpointReference | RuleReference": "ID that you assigned to the rule or endpoint that this rule routes traffic to", "EvaluateTargetHealth": "true" | "false", "HealthCheck": "optional health check ID" }, "Secondary": { "EndpointReference | RuleReference": "ID that you assigned to the rule or endpoint that this rule routes traffic to", "EvaluateTargetHealth": "true" | "false", "HealthCheck": "optional health check ID" } }

When you define a failover rule, you specify the following objects:

RuleType

Specify failover.

Primary | Secondary

For the Primary object, specify settings for the rule or endpoint that you want to route traffic to whenever the corresponding resources are available.

For the Secondary object, specify settings for the rule or endpoint that you want to route traffic to whenever the primary resources are not available.

EndpointReference | RuleReference

Whether you want to route traffic to an endpoint or to another rule, and the ID that you assigned to the endpoint or rule elsewhere in the traffic policy document.

EvaluateTargetHealth

A Boolean that indicates whether you want Amazon Route 53 to evaluate the health of the endpoint and route traffic only to healthy endpoints. For more information, see EvaluateTargetHealth, in the documentation about ChangeResourceRecordSets.

HealthCheck

If you want to associate a health check with the endpoint or rule, specify the ID of the health check. For more information, see HealthCheckId in the documentation about ChangeResourceRecordSets.

Geolocation Rules

When you add a geolocation rule, you configure your traffic policy to route your traffic based on the geographic location of your users. For more information, see Geolocation Routing in the Amazon Route 53 Developer Guide.

Copy
{ "RuleType": "geo", "Locations": [ { "EndpointReference | RuleReference": "ID that you assigned to the rule or endpoint that this rule routes traffic to", "IsDefault": "true" | "false", "Continent": "continent name, "Country": "country name, "Subdivision": "subdivision name, "EvaluateTargetHealth": "true" | "false", "HealthCheck": "optional health check ID" }, ... ] }

When you define a geolocation rule, you specify the following objects:

RuleType

Specify geo.

Locations

Specify one set of values (EndpointReference | RuleReference, IsDefault, Continent, Country, Subdivision, EvaluateTargetHealth, and HealthCheck) for each of the geographic locations that you want to route traffic to.

EndpointReference | RuleReference

Whether you want to route traffic to an endpoint or to another rule, and the ID that you assigned to the endpoint or rule elsewhere in the traffic policy document.

IsDefault

A Boolean that indicates whether this set of values represents the default location. For more information about IsDefault, see the explanation about specifying * as the value for the CountryCode element when you create or update a resource record set in the description for GeoLocation.

Continent, Country, Subdivision

Values that indicate the geographic location of users whose traffic you want to route to a rule or endpoint. For more information, see the following element descriptions in the documentation about ChangeResourceRecordSets:

  • GeoLocation

  • ContinentCode

  • CountryCode

  • SubdivisionCode

EvaluateTargetHealth

A Boolean that indicates whether you want Amazon Route 53 to evaluate the health of the endpoint and route traffic only to healthy endpoints. For more information, see EvaluateTargetHealth in the documentation about ChangeResourceRecordSets.

HealthCheck

If you want to associate a health check with the endpoint or rule, specify the ID of the health check. For more information, see HealthCheckId in the documentation about ChangeResourceRecordSets.

Latency Rules

When you add a latency rule, you configure your traffic policy to route your traffic based on the latency (the time delay) between your users and the AWS regions where you've created AWS resources such as ELB load balancers and Amazon S3 buckets. For more information, see Latency Routing in the Amazon Route 53 Developer Guide.

Copy
{ "RuleType": "latency", "Regions": [ { "EndpointReference | RuleReference": "ID that you assigned to the rule or endpoint that this rule routes traffic to", "Region": "AWS region that you want to route traffic to", "EvaluateTargetHealth": "true" | "false", "HealthCheck": "optional health check ID" }, ... ] }

When you define a latency rule, you specify the following objects:

RuleType

Specify latency.

Regions

Specify one set of values (EndpointReference | RuleReference, Region, EvaluateTargetHealth, and HealthCheck) for each of the regions that you want to route traffic to.

EndpointReference | RuleReference

Whether you want to route traffic to an endpoint or to another rule, and the ID that you assigned to the endpoint or rule elsewhere in the traffic policy document.

Region

A value between 0 and 255 that determines the proportion of traffic that is routed to the corresponding endpoint or rule. For more information, Region in the documentation about ChangeResourceRecordSets.

EvaluateTargetHealth

A Boolean that indicates whether you want Amazon Route 53 to evaluate the health of the endpoint and route traffic only to healthy endpoints. For more information, see EvaluateTargetHealth in the documentation about ChangeResourceRecordSets.

HealthCheck

If you want to associate a health check with the endpoint or rule, specify the ID of the health check. For more information, see HealthCheckId in the documentation about ChangeResourceRecordSets.

Multivalue Answer Rules

When you add a multivalue answer rule, you configure your traffic policy to route traffic approximately randomly to your healthy resources. Amazon Route 53 responds to DNS queries with up to eight healthy records; if you have eight or fewer healthy records, Amazon Route 53 responds to all DNS queries with all the healthy records. For more information, see MultiValueAnswer.

Copy
{ "RuleType": "multivalue", "Items": [ { "EndpointReference": "ID that you assigned to the endpoint that this rule routes traffic to", "HealthCheck": "optional health check ID" }, ... ] }

When you define a multivalue answer rule, you specify the following objects:

RuleType

Specify multivalue.

Items

Specify one set of values (EndpointReference and HealthCheck) for each of the multivalue answer rules or endpoints that you want to route traffic to.

EndpointReference

The ID that you assigned to the endpoint elsewhere in the traffic policy document.

HealthCheck

If you want to associate a health check with the endpoint, specify the ID of the health check. For more information, see HealthCheckId.

Weighted Rules

When you add a weighted rule, you configure your traffic policy to route traffic based on proportions that you specify. For example, you might specify weights of 4, 5, 5, and 6 (sum=20). The result is that 4/20ths of your traffic, on average, is routed to the first endpoint or rule, 5/20ths is routed both to the second and third endpoints or rules, and 6/20ths is routed to the last endpoint or rule. For more information, see Weighted Routing in the Amazon Route 53 Developer Guide.

Copy
{ "RuleType": "weighted", "Items": [ { "EndpointReference | RuleReference": "ID that you assigned to the rule or endpoint that this rule routes traffic to", "Weight": "value between 0 and 255", "EvaluateTargetHealth": "true" | "false", "HealthCheck": "optional health check ID" }, ... ] }

When you define a weighted rule, you specify the following objects:

RuleType

Specify weighted.

Items

Specify one set of values (EndpointReference | RuleReference, Weight, EvaluateTargetHealth, and HealthCheck) for each of the weighted rules or endpoints that you want to route traffic to.

EndpointReference | RuleReference

Whether you want to route traffic to an endpoint or to another rule, and the ID that you assigned to the endpoint or rule elsewhere in the traffic policy document.

Weight

A value between 0 and 255 that determines the proportion of traffic that is routed to the corresponding endpoint or rule. For more information, see Weight in the documentation about ChangeResourceRecordSets.

EvaluateTargetHealth

A Boolean that indicates whether you want Amazon Route 53 to evaluate the health of the endpoint and route traffic only to healthy endpoints. For more information, see EvaluateTargetHealth in the documentation about ChangeResourceRecordSets.

HealthCheck

If you want to associate a health check with the endpoint or rule, specify the ID of the health check. For more information, see HealthCheckId in the documentation about ChangeResourceRecordSets.

Examples

The following examples show how to use failover, weighted, latency, and geolocation rules, and how to use multiple types of rules in the same traffic policy.

Failover Example

Copy
{ "AWSPolicyFormatVersion":"2015-10-01", "RecordType":"A", "StartRule":"site_switch", "Endpoints":{ "my_elb":{ "Type":"elastic-load-balancer", "Value":"elb-111111.us-east-1.elb.amazonaws.com" }, "site_down_banner":{ "Type":"s3-website", "Region":"us-east-1", "Value":"www.example.com" } }, "Rules":{ "site_switch":{ "RuleType":"failover", "Primary":{ "EndpointReference":"my_elb" }, "Secondary":{ "EndpointReference":"site_down_banner" } } } }

Weighted Example

Copy
{ "AWSPolicyFormatVersion":"2015-10-01", "RecordType":"A", "StartRule":"round_robin", "Endpoints":{ "srv1":{ "Type":"value", "Value":"192.0.2.1" }, "srv2":{ "Type":"value", "Value":"192.0.2.2" }, "srv3":{ "Type":"value", "Value":"192.0.2.3" } }, "Rules":{ "round_robin":{ "RuleType":"weighted", "Items":[ { "EndpointReference":"srv1", "Weight":"3", "HealthCheck":"11111111-1111-1111-1111-111111111111" }, { "EndpointReference":"srv2", "Weight":"1", "HealthCheck":"22222222-2222-2222-2222-222222222222" }, { "EndpointReference":"srv3", "Weight":"1", "HealthCheck":"33333333-3333-3333-3333-333333333333" } ] } } }

Latency Example

Copy
{ "AWSPolicyFormatVersion":"2015-10-01", "RecordType":"A", "StartRule":"region_selector", "Endpoints":{ "us_lb":{ "Type":"elastic-load-balancer", "Value":"elb-123456.us-east-1.elb.amazonaws.com" }, "europe_lb":{ "Type":"elastic-load-balancer", "Value":"elb-654321.eu-west-1.elb.amazonaws.com" } }, "Rules":{ "region_selector":{ "RuleType":"latency", "Regions":[ { "Region":"us-east-1", "EndpointReference":"us_lb" }, { "Region":"eu-west-1", "EndpointReference":"europe_lb" } ] } } }

Geolocation Example

Copy
{ "AWSPolicyFormatVersion":"2015-10-01", "RecordType":"A", "StartRule":"geo_dest", "Endpoints":{ "english":{ "Type":"value", "Value":"192.0.2.1" }, "french":{ "Type":"value", "Value":"192.0.2.2" }, "german":{ "Type":"value", "Value":"192.0.2.3" } }, "Rules":{ "geo_dest":{ "RuleType":"geo", "Locations":[ { "EndpointReference":"english", "IsDefault":true, "HealthCheck":"11111111-1111-1111-1111-111111111111" }, { "EndpointReference":"french", "Country":"FR", "HealthCheck":"22222222-2222-2222-2222-222222222222" }, { "EndpointReference":"french", "Country":"BE", "HealthCheck":"22222222-2222-2222-2222-222222222222" }, { "EndpointReference":"german", "Country":"DE", "HealthCheck":"33333333-3333-3333-3333-333333333333" } ] } } }

Example with Failover, Latency, and Geolocation Rules

Copy
{ "AWSPolicyFormatVersion":"2015-10-01", "RecordType":"A", "StartRule":"geo_restriction", "Endpoints":{ "east_coast_lb1":{ "Type":"elastic-load-balancer", "Value":"elb-111111.us-east-1.elb.amazonaws.com" }, "east_coast_lb2":{ "Type":"elastic-load-balancer", "Value":"elb-222222.us-east-1.elb.amazonaws.com" }, "west_coast_lb1":{ "Type":"elastic-load-balancer", "Value":"elb-111111.us-west-1.elb.amazonaws.com" }, "west_coast_lb2":{ "Type":"elastic-load-balancer", "Value":"elb-222222.us-west-1.elb.amazonaws.com" }, "denied_message":{ "Type":"s3-website", "Region":"us-east-1", "Value":"video.example.com" } }, "Rules":{ "geo_restriction":{ "RuleType":"geo", "Locations":[ { "EndpointReference":"denied_message", "IsDefault":true }, { "RuleReference":"region_selector", "Country":"US" } ] }, "region_selector":{ "RuleType":"latency", "Regions":[ { "Region":"us-east-1", "RuleReference":"east_coast_region" }, { "Region":"us-west-1", "RuleReference":"west_coast_region" } ] }, "east_coast_region":{ "RuleType":"failover", "Primary":{ "EndpointReference":"east_coast_lb1" }, "Secondary":{ "EndpointReference":"east_coast_lb2" } }, "west_coast_region":{ "RuleType":"failover", "Primary":{ "EndpointReference":"west_coast_lb1" }, "Secondary":{ "EndpointReference":"west_coast_lb2" } } } }