Basic Syntax Syntax for Endpoint Definitions Syntax for Rule Definitions Examples

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.

Topics

Basic Syntax
Syntax for Endpoint Definitions
Syntax for Rule Definitions
Examples

Basic Syntax

Here is the basic syntax for a traffic policy document:


{
   "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 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:


{
   "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, geoproximity, latency, multivalue answer, or weighted.

Topics

Failover Rules
Geolocation Rules
Geoproximity Rules
Latency Rules
Multivalue Answer Rules
Weighted Rules

Failover Rules

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


{
   "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.


{
   "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

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.

Geoproximity Rules

When you add a geoproximity rule, you configure Amazon Route 53 to route traffic to your resources based on the geographic location of your resources. You can also optionally choose to route more traffic or less to a given endpoint or rule by specifying a bias. You use a bias to expand or shrink the size of the geographic region from which traffic is routed to an endpoint or rule. For more information, see Geoproximity Routing in the Amazon Route 53 Developer Guide.


{
   "RuleType": "geoproximity",
   "GeoproximityLocations": [
      {
         "EndpointReference | RuleReference": "ID that you assigned to the endpoint or rule that this rule routes traffic to",
         "Region": "AWS Region",
         "Bias": "optional value to expand or shrink the geographic region for this rule, -99 to 99",
         "EvaluateTargetHealth": "true | false",
         "HealthCheck": "optional health check ID"
      },
      {
         "EndpointReference | RuleReference": "ID that you assigned to the endpoint or rule that this rule routes traffic to",
         "Latitude": "location south (negative) or north (positive) of the equator, -90 to 90 degrees",
         "Longitude": "location west (negative) or east (positive) of the prime meridian, -180 to 180 degrees",
         "Bias": "optional value to expand or shrink the geographic region for this rule, -99 to 99",
         "EvaluateTargetHealth": "true | false",
         "HealthCheck": "optional health check ID"
      }
   ]
}

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

RuleType

Specify geoproximity.

GeoproximityLocations

Specify one set of values for each resource that you want to route traffic to. You can specify either an AWS Region or the latitude and longitude of a geographic location.

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

If your endpoint is an AWS resource, specify the AWS Region that you created the resource in. Use the following format:

aws:route53:region-code

For a list of valid region codes, see Region in the documentation about ChangeResourceRecordSets.

Latitude and Longitude

If your endpoint is not an AWS resource, enter the latitude and longitude of the location of the resource. Note the following:

Latitude represents the location south (negative) or north (positive) of the equator. Valid values are -90 degrees to 90 degrees.
Longitude represents the location west (negative) or east (positive) of the prime meridian. Valid values are -180 degrees to 180 degrees.
You can get latitude and longitude from some online mapping applications. For example, in Google Maps, the URL for a location specifies the latitude and longitude:

https://www.google.com/maps/@47.6086111,-122.3409953,20z
You can enter up to two decimals of precision, for example, 47.61. If you specify a value with greater precision, Route 53 returns an error. For latitude and for longitude at the equator, 0.01 degree is approximately 0.69 miles.

Bias

Specify a value for Bias if you want to route more traffic to an endpoint from nearby endpoints (positive values) or route less traffic to an endpoint (negative values). The range of valid values is -99 to 99; the default value is 0.

Important

The value of Bias is relative, based on the location of other resources, rather than absolute, based on distance. As a result, the effect of a change is difficult to predict. For example, depending on where your resources are, changing the bias from 10 to 15 can mean the difference between adding or subtracting a significant amount of traffic from the New York City metropolitan area. We recommend that you change the bias in small increments and evaluate the results, and then make additional changes if appropriate.

EvaluateTargetHealth

A Boolean that indicates whether you want 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.


{
   "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: The region code for the AWS Region that you created the resource in. For a list of valid region codes, see 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, Route 53 responds to all DNS queries with all the healthy records. For more information, see MultiValueAnswer.


{
   "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.


{
   "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, geolocation, geoproximity, latency, and weighted rules, and how to use multiple types of rules in the same traffic policy.

Topics

Failover Example
Geolocation Example
Geoproximity Example
Latency Example
Weighted Example
Example with Failover, Latency, and Geolocation Rules

Failover Example


{
   "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"
         }
      }
   }
}

Geolocation Example


{
  "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"
        }
      ]
    }
  }
}

Geoproximity Example


{
  "AWSPolicyFormatVersion":"2015-10-01",
  "RecordType":"A",
  "StartRule":"geoprox-rule",
  "Endpoints":{
    "aws-us-west-1-region":{
      "Type":"elastic-load-balancer",
      "Value":"elb-123456.us-east-1.elb.amazonaws.com"
    },
    "london-data-center":{
      "Type":"value",
      "Value":"192.0.2.1"
    }
  },
  "Rules":{
    "geoprox-rule":{
      "RuleType": "geoproximity",
      "GeoproximityLocations": [
        {
          "EndpointReference": "aws-us-west-1-region",
          "Region": "us-west-1",
          "Bias": "10",
          "HealthCheck": "11111111-1111-1111-1111-111111111111"
        },
        {
          "EndpointReference": "london-data-center",
          "Latitude": "51.50",
          "Longitude": "-0.16",
          "Bias": "0",
          "HealthCheck": "22222222-2222-2222-2222-222222222222"
        }
      ]
    }
  }
}

Latency Example


{
  "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"
        }
      ]
    }
  }
}

Weighted Example


{
  "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"
        }
      ]
    }
  }
}

Example with Failover, Latency, and Geolocation Rules


{
  "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"
      }
    }
  }
}

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Signing Amazon Route 53 API Requests

Data Types