Traffic Management Steering Policies API Guide
Traffic Management Steering Policies allows you to build and configure traffic management policies using the Oracle Cloud Infrastructure DNS REST API. Use the following guide to learn how policies are constructed using the REST API.
Authentication and Authorization
Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and authorization, for all interfaces (the Console, SDK or CLI, and REST API).
An administrator in your organization needs to set up groups , compartments , and policies that control which users can access which services, which resources, and the type of access. For example, the policies control who can create new users, create and manage the cloud network, launch instances, create buckets, download objects, etc. For more information, see Getting Started with Policies. For specific details about writing policies for each of the different services, see Policy Reference.
If you’re a regular user (not an administrator) who needs to use the Oracle Cloud Infrastructure resources that your company owns, contact your administrator to set up a user ID for you. The administrator can confirm which compartment or compartments you should be using.
Traffic Management Steering Policy Components
The following list describes the components used to build a Traffic Management Steering Policy.
- STEERING POLICIES
- An overall framework to define the traffic management behavior for your zones. Steering policies contain rules that help to intelligently serve DNS answers.
- ATTACHMENTS
- Allows you to link a steering policy to your zones. An attachment of a steering policy to a zone occludes all records at its domain that are of a covered record type, constructing DNS responses from its steering policy rather than from those domain's records. A domain can have at most one attachment covering any given record type.
- RULES
- The guidelines steering policies use to filter answers based on the properties of a DNS request, such as the requests geo-location or the health of your endpoints.
- ANSWERS
- Answers contain the DNS record data and metadata to be processed in a steering policy.
- TEMPLATES
- Templates are predefined rule sequences that create a policy type and its intended behavior. Example: The
FAILOVER
template determines answers by checking DNS query against aFILTER
rule first, then the following rules in succession:HEALTH
,PRIORITY
, andLIMIT
. This gives the domain dynamic failover capability. Policies that define thetemplate
field with any policy other thanCUSTOM
, must follow the rule sequence outlined for that policy type, otherwise, a400
status code error will be returned upon policy creation. - CASES
- A rule may optionally include a sequence of cases defining alternate configurations for how it should behave during processing for any given DNS query. When a rule has no sequence of cases, it is always evaluated with the same configuration during processing. When a rule has an empty sequence of cases, it is always ignored during processing. When a rule has a non-empty sequence of cases, its behavior during processing is configured by the first matching case in the sequence. A rule case with no
caseCondition
always matches. A rule case with acaseCondition
matches only when that expression evaluates to true for the given query.
Create Steering Policies Using Templates
The following section explains the rule configuration for each type of steering policy template followed by an example POST request (CreateSteeringPolicy) displaying how to configure each template.
FAILOVER
Failover policies allow you to prioritize the order in which you want answers served in a
policy (for example, Primary and Secondary). Oracle Cloud Infrastructure
Health Checks are leveraged to determine the health of answers in the policy. If the Primary
Answer is determined to be unhealthy, DNS traffic will automatically be steered to the
Secondary Answer. Each of the following rules must be defined in the order specified below
in the rules
field of your request body when using a
FAILOVER
template:
Order | Rule | Restrictions | Comments |
---|---|---|---|
1
|
FILTER
|
|
|
2
|
HEALTH
|
|
Only included if healthCheckMonitorId is defined for the
policy. |
3
|
PRIORITY
|
|
|
4
|
LIMIT
|
|
Example of a POST /steeringPolicies
policy using the
FAILOVER
template:
{
"compartmentId": "ocid1...",
"displayName": "failover between endpoints",
"ttl": 30,
"healthCheckMonitorId": "ocid1...",
"template": "FAILOVER",
"answers": [
{
"name": "server-primary",
"rtype": "A",
"rdata": "192.168.0.2",
"pool": "primary"
},
{
"name": "server-secondary",
"rtype": "A",
"rdata": "192.168.0.3",
"pool": "secondary"
}
],
"rules": [
{
"ruleType": "FILTER",
"defaultAnswerData": [
{
"answerCondition": "answer.isDisabled != true",
"shouldKeep": true
}
]
},
{
"ruleType": "HEALTH"
},
{
"ruleType": "PRIORITY",
"defaultAnswerData": [
{
"answerCondition": "answer.pool == 'primary'",
"value": 1
},
{
"answerCondition": "answer.pool == 'secondary'",
"value": 99
}
]
},
{
"ruleType": "LIMIT",
"defaultCount": 1
}
]
}
LOAD_BALANCE
Load Balancer policies allow distribution of traffic across multiple endpoints. Endpoints
can be assigned equal weights to distribute traffic evenly across the endpoints or custom
weights may be assigned for ratio load balancing. Oracle Cloud Infrastructure Health Checks are leveraged to determine the health of the endpoint. DNS traffic will be
automatically distributed to the other endpoints, if an endpoint is determined to be
unhealthy. Each of the following rules must be defined in the order specified below in the
rules
field of your request body when using a
LOAD_BALANCE
template:
Order | Rule | Restrictions | Comments |
---|---|---|---|
1
|
FILTER
|
|
|
2
|
HEALTH
|
|
Only included if healthCheckMonitorId is defined for the
policy. |
3
|
WEIGHTED
|
|
|
4
|
LIMIT
|
|
Example of a POST /steeringPolicies
policy using the
LOAD_BALANCE
template:
{
"compartmentId": "ocid1...",
"displayName": "Weighted load balance for a set of answers with health checks",
"ttl": 30,
"healthCheckMonitorId": "ocid1...",
"template": "LOAD_BALANCE",
"answers": [
{
"name": "server1",
"rtype": "A",
"rdata": "192.168.0.2"
},
{
"name": "server2",
"rtype": "A",
"rdata": "192.168.0.3"
}
],
"rules": [
{
"ruleType": "FILTER",
"defaultAnswerData": [
{
"answerCondition": "answer.isDisabled != true",
"shouldKeep": true
}
]
},
{
"ruleType": "HEALTH"
},
{
"ruleType": "WEIGHTED",
"defaultAnswerData": [
{
"answerCondition": "answer.name == 'server1'",
"value": 99
},
{
"answerCondition": "answer.name == 'server2'",
"value": 1
}
]
},
{
"ruleType": "LIMIT",
"defaultCount": 1
}
]
}
ROUTE_BY_GEO
Geolocation-based steering policies distribute DNS traffic to different endpoints based on
the location of the end user. Customers can define geographic regions composed of
originating continent, countries or states/provinces (North America) and define a separate
endpoint or set of endpoints for each region. Each of the following rules must be defined in
the order specified below in the rules
field of your request body when
using a ROUTE_BY_GEO
template:
Order | Rule | Restrictions | Comments |
---|---|---|---|
1
|
FILTER
|
|
|
2
|
HEALTH
|
|
Only included if healthCheckMonitorId is defined for the
policy. |
3
|
PRIORITY
|
|
|
4
|
LIMIT
|
|
Example of a POST /steeringPolicies
request body using the
ROUTE_BY_GEO
template:
{
"compartmentId": "ocid1...",
"displayName": "Geolocations mapped to answer pools",
"ttl": 30,
"healthCheckMonitorId": "ocid1...",
"template": "ROUTE_BY_GEO",
"answers": [
{
"name": "US Server 1",
"rtype": "A",
"rdata": "192.168.0.2",
"pool": "US"
},
{
"name": "US Server 2",
"rtype": "A",
"rdata": "192.168.0.3",
"pool": "US"
},
{
"name": "EU Server 1",
"rtype": "A",
"rdata": "192.168.0.4",
"pool": "EU"
},
{
"name": "EU Server 2",
"rtype": "A",
"rdata": "192.168.0.5",
"pool": "EU"
},
{
"name": "rest of world 1",
"rtype": "A",
"rdata": "203.0.113.2",
"pool": "Global"
},
{
"name": "rest of world 2",
"rtype": "A",
"rdata": "203.0.113.3",
"pool": "Global"
}
],
"rules": [
{
"ruleType": "FILTER",
"defaultAnswerData": [
{
"answerCondition": "answer.isDisabled != true",
"shouldKeep": true
}
]
},
{
"ruleType": "HEALTH"
},
{
"ruleType": "PRIORITY",
"cases": [
{
"caseCondition": "query.client.geoKey in (geoKey '6255149')",
"answerData": [
{
"answerCondition": "answer.pool == 'US'",
"value": 1
},
{
"answerCondition": "answer.pool == 'EU'",
"value": 2
},
{
"answerCondition": "answer.pool == 'Global'",
"value": 3
}
]
},
{
"caseCondition": "query.client.geokey in (geokey '6255148')",
"answerData": [
{
"answerCondition": "answer.pool == 'EU'",
"value": 1
},
{
"answerCondition": "answer.pool == 'US'",
"value": 2
},
{
"answerCondition": "answer.pool == 'Global'",
"value": 3
}
]
},
{
"answerData": [
{
"answerCondition": "answer.pool == 'Global'",
"value": 1
},
{
"answerCondition": "answer.pool == 'US'",
"value": 2
},
{
"answerCondition": "answer.pool == 'EU'",
"value": 3
}
]
}
]
},
{
"ruleType": "LIMIT",
"defaultCount": 1
}
]
}
ROUTE_BY_ASN
ASN-based steering policies enable you to steer DNS traffic based on Autonomous System
Numbers (ASN). DNS queries originating from a specific ASN or set of ASNs can be steered to
a specified endpoint. Each of the following rules must be defined in the order specified
below in the rules
field of your request body when using a
ROUTE_BY_ASN
template:
Order | Rule | Restrictions | Comments |
---|---|---|---|
1
|
FILTER
|
|
|
2
|
HEALTH
|
|
Only included if healthCheckMonitorId is defined for the
policy. |
3
|
PRIORITY
|
|
|
4
|
LIMIT
|
|
Example of a POST /steeringPolicies
request body using the
ROUTE_BY_ASN
template:
{
"compartmentId": "ocid1...",
"displayName": "ASNs mapped to pools",
"ttl": 30,
"template": "ROUTE_BY_ASN",
"answers": [
{
"name": "ABC Server",
"rtype": "A",
"rdata": "192.168.0.2",
"pool": "ABC"
},
{
"name": "DEF Server",
"rtype": "A",
"rdata": "192.168.0.3",
"pool": "DEF"
},
{
"name": "Other",
"rtype": "A",
"rdata": "203.0.113.2",
"pool": "Other"
}
],
"rules": [
{
"ruleType": "FILTER",
"defaultAnswerData": [
{
"answerCondition": "answer.isDisabled != true",
"shouldKeep": true
}
]
},
{
"ruleType": "PRIORITY",
"cases": [
{
"caseCondition": "query.client.asn == 3",
"answerData": [
{
"answerCondition": "answer.pool == 'ABC'",
"value": 1
},
{
"answerCondition": "answer.pool == 'DEF'",
"value": 2
},
{
"answerCondition": "answer.pool == 'Other'",
"value": 3
}
]
},
{
"caseCondition": "query.client.asn == 16591",
"answerData": [
{
"answerCondition": "answer.pool == 'DEF'",
"value": 1
},
{
"answerCondition": "answer.pool == 'ABC'",
"value": 2
},
{
"answerCondition": "answer.pool == 'Other'",
"value": 3
}
]
},
{
"answerData": [
{
"answerCondition": "answer.pool == 'Other'",
"value": 1
},
{
"answerCondition": "answer.pool == 'ABC'",
"value": 2
},
{
"answerCondition": "answer.pool == 'DEF'",
"value": 3
}
]
}
]
},
{
"ruleType": "LIMIT",
"defaultCount": 1
}
]
}
ROUTE_BY_IP
IP Prefix-based steering policies enable customers to steer DNS traffic based on the IP
Prefix of the originating query. Each of the following rules must be defined in the order
specified below in the rules
field of your request body when using a
ROUTE_BY_IP
template:
Order | Rule | Restrictions | Comments |
---|---|---|---|
1
|
FILTER
|
|
|
2
|
HEALTH
|
|
Only included if healthCheckMonitorId is defined for the
policy. |
3
|
PRIORITY
|
|
|
4
|
LIMIT
|
|
Example of a POST /steeringPolicies
request body using the
ROUTE_BY_IP
template:
{
"compartmentId": "ocid1...",
"displayName": "IP subnets mapped to answer pools",
"ttl": 30,
"template": "ROUTE_BY_IP",
"answers": [
{
"name": "ABC Server",
"rtype": "A",
"rdata": "192.168.0.2",
"pool": "ABC"
},
{
"name": "DEF Server",
"rtype": "A",
"rdata": "192.168.0.3",
"pool": "DEF"
},
{
"name": "Other",
"rtype": "A",
"rdata": "203.0.113.2",
"pool": "Other"
}
],
"rules": [
{
"ruleType": "FILTER",
"defaultAnswerData": [
{
"answerCondition": "answer.isDisabled != true",
"shouldKeep": true
}
]
},
{
"ruleType": "PRIORITY",
"cases": [
{
"caseCondition": "query.client.address in (subnet '10.0.3.0/24')",
"answerData": [
{
"answerCondition": "answer.pool == 'ABC'",
"value": 1
},
{
"answerCondition": "answer.pool == 'DEF'",
"value": 2
},
{
"answerCondition": "answer.pool == 'Other'",
"value": 3
}
]
},
{
"caseCondition": "query.client.address in (subnet '192.0.2.2/24')",
"answerData": [
{
"answerCondition": "answer.pool == 'DEF'",
"value": 1
},
{
"answerCondition": "answer.pool == 'ABC'",
"value": 2
},
{
"answerCondition": "answer.pool == 'Other'",
"value": 3
}
]
},
{
"answerData": [
{
"answerCondition": "answer.pool == 'Other'",
"value": 1
},
{
"answerCondition": "answer.pool == 'ABC'",
"value": 2
},
{
"answerCondition": "answer.pool == 'DEF'",
"value": 3
}
]
}
]
},
{
"ruleType": "LIMIT",
"defaultCount": 1
}
]
}
CUSTOM
Custom policies allow you to create complex policies combining the capabilities of failover, load balancing, geolocation, ASN and IP prefix steering. Custom templates to not require a regimented sequence of rules and it is recommended to contact Oracle Cloud Infrastructure support before creating a custom policy.
Rule Types
- FILTER
- Uses boolean data associated with answers, keeping answers only if the rule's
shouldKeep
value istrue
. - HEALTH
- Utilizes Oracle Cloud Health Check monitors to determine the health of your endpoints and add and remove answers from your policy as needed. A health check monitor must be referenced in a health rule to have an effect on the policy. For more information about Health Checks, see Health Checks.
- WEIGHTED
- Uses a number between 0 and 255 used to determine how often an answer will be served in relation to other answers. Answers with higher values are more likely to be returned.
- PRIORITY
- Uses an integer associated with each answer to sort answers from lowest to highest value. Example: An answer with a priority value of 1 would be returned before an answer with a priority value of 10 in the list of answers. Answers that do not have a priority value assigned to them will be moved to the end of the list of answers.
- LIMIT
- Uses a count property to filter away all but the first answers in the list.