Traffic Management Steering Policies API Guide
Use the Oracle Cloud Infrastructure DNS REST API to build and configure Traffic Management policies.
Use the following guide to learn how policies are constructed using the DNS 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, and so on. 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 zones. Steering policies contain rules that help to intelligently serve DNS answers.
- ATTACHMENTS
- Allows you to link a steering policy to 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 particular record type.
- RULES
- The guidelines steering policies use to filter answers based on the properties of a DNS request, such as the requests geolocation or the health of 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 serves 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 is returned upon policy creation. - CASES
- A rule can optionally include a sequence of cases defining alternate configurations for how it behaves during processing for any particular DNS query. When a rule has no sequence of cases, it's always evaluated with the same configuration during processing. When a rule has an empty sequence of cases, it's 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 specific 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
User failover policies to prioritize the order in which answers are served in a policy (for example, Primary and Secondary). Oracle Cloud Infrastructure
Health Checks monitors and on-demand probes are leveraged to evaluate the health of answers in the policy. If the Primary Answer is found to be unhealthy, DNS traffic is automatically steered to the Secondary Answer. Each of the following rules must be defined in the order specified in the rules
field of the 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 distribute traffic across many endpoints. You can assign equal weights to endpoints to distribute traffic evenly across the endpoints or you can assign custom weights for ratio load balancing. Oracle Cloud Infrastructure
Health Checks monitors and on-demand probes are leveraged to evaluate the health of the endpoint. DNS traffic is be automatically distributed to the other endpoints, if an endpoint is found to be unhealthy. Each of the following rules must be defined in the order specified in the rules
field of the 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 in the rules
field of the 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 in the rules
field of the 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 in the rules
field of the 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
Use custom policies 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 we recommend that you 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
- Uses OCI Health Checks monitors and on-demand probes to evaluate the health of endpoints and add and remove answers from the policy as needed. A health check monitor must be referenced in a health rule to affect the policy. For more information about Health Checks, see Health Checks.
- WEIGHTED
- Uses a number between 0 and 255 used to evaluate how often an answer is 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 don't have a priority value assigned to them are 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.