Oracle Cloud Infrastructure Documentation

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 a FILTER rule first, then the following rules in succession: HEALTH, PRIORITY, and LIMIT. This gives the domain dynamic failover capability. Policies that define the template field with any policy other than CUSTOM, must follow the rule sequence outlined for that policy type, otherwise, a 400 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 a caseCondition 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
  • No cases are allowed.

  • Answer data must be defined in defaultAnswerData using the following JSON:

    
{
  "answerCondition": "answer.isDisabled != true",
  "shouldKeep": true
}
 
2 HEALTH
  • No cases are allowed.
Only included if healthCheckMonitorId is defined for the policy.
3 PRIORITY
  • No cases are allowed.
  • Answer data must be defined in the defaultAnswerData property for the rule.

  • Every answer must have a pool property.

  • defaultAnswerData restrictions:
    • Answers cannot be referenced by their name property in answerCondition expressions, they must be referenced by their pool property.
    • Every answer pool must be referenced once and only once.
    • Every answer pool must have a unique value property.
    • Each answer pool reference must match the pool property on one or more answers defined in the answer list for the policy.
  
4 LIMIT
  • No cases are allowed.
 

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
  • No cases are allowed.

  • Answer data must be defined in defaultAnswerData using the following JSON:

    
{
  "answerCondition": "answer.isDisabled != true",
  "shouldKeep": true
}
 
2 HEALTH
  • No cases are allowed.
Only included if healthCheckMonitorId is defined for the policy.
3 WEIGHTED
  • No cases are allowed.
  • Answer data must be defined in the defaultAnswerData property for the rule.
  • Answers cannot be referenced by their pool property in answerCondition expressions, they must be referenced by their name property.
 
4 LIMIT
  • No cases are allowed.
 

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
  • No cases are allowed.

  • Answer data must be defined in defaultAnswerData using the following JSON:

    
{
  "answerCondition": "answer.isDisabled != true",
  "shouldKeep": true
}
 
2 HEALTH
  • No cases are allowed.
Only included if healthCheckMonitorId is defined for the policy.
3 PRIORITY
  • The defaultAnswerData property cannot be used on this rule.
  • At least one case must be defined. If there are multiple cases, the final case can provide a "catch-all" case.
  • The caseCondition property on cases can only use query.client.geoKey in the conditional expression.
  • Answers cannot be referenced by their name property in answerCondition expressions, they must be referenced by their pool property.
  • Every answer must have a pool property.

  • For each case's answerData:

    • Every answer pool must be referenced once and only once.
    • Every answer pool must have a unique value property (within the case).
    • Each answer pool reference must match the pool property on one or more answers defined in the answer list for the policy.
 
4 LIMIT
  • No cases are allowed.
 

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
  • No cases are allowed.

  • Answer data must be defined in defaultAnswerData using the following JSON:

    
{
  "answerCondition": "answer.isDisabled != true",
  "shouldKeep": true
}
 
2 HEALTH
  • No cases are allowed.
Only included if healthCheckMonitorId is defined for the policy.
3 PRIORITY
  • The defaultAnswerData property cannot be used on this rule.
  • At least one case must be defined. If there are multiple cases, the final case can provide a "catch-all" case.
  • The caseCondition property on cases can only use query.client.asn in the conditional expression.
  • Answers cannot be referenced by their name property in answerCondition expressions, they must be referenced by their pool property.
  • Every answer must have a pool property.

  • For each case's answerData:

    • Every answer pool must be referenced once and only once.
    • Every answer pool must have a unique value property (within the case).
    • Each answer pool reference must match the pool property on one or more answers defined in the answer list for the policy.
  
4 LIMIT
  • No cases are allowed.
 

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
  • No cases are allowed.

  • Answer data must be defined in defaultAnswerData using the following JSON:

    
{
  "answerCondition": "answer.isDisabled != true",
  "shouldKeep": true
}
 
2 HEALTH
  • No cases are allowed.
Only included if healthCheckMonitorId is defined for the policy.
3 PRIORITY
  • The defaultAnswerData property cannot be used on this rule.
  • At least one case must be defined. If there are multiple cases, the final case can provide a "catch-all" case.
  • The caseCondition property on cases can only use query.client.address in the conditional expression.
  • Answers cannot be referenced by their name property in answerCondition expressions, they must be referenced by their pool property.
  • Every answer must have a pool property.

  • For each case's answerData:

    • Every answer pool must be referenced once and only once.
    • Every answer pool must have a unique value property (within the case).
    • Each answer pool reference must match the pool property on one or more answers defined in the answer list for the policy.
 
4 LIMIT
  • No cases are allowed.
 

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 is true.
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.