Route requests by country or continent

You send the requests of one continent, or of a list of countries, to a regional connector with a geolocation rule, from Azion Console, the API, or the Azion CLI. To give a connector a backup origin that takes requests when its primary origin fails, refer to Add a backup origin to a connector.

A geolocation rule reads the location of the client’s IP address in the Request Phase and names a connector with Set Connector. Set Connector does not add up across rules: when several matching rules carry it, only the one from the last matching rule runs. A default rule that sends every path to one connector therefore comes first, and each geolocation rule comes after it and overrides the default for the requests it matches.

mermaid

%%{init: {"layout": "dagre", "themeVariables": {"fontSize": "13px"}, "flowchart": {"nodeSpacing": 12, "rankSpacing": 12, "padding": 6, "wrappingWidth": 70, "minNodeWidth": 40, "useMaxWidth": true}}}%%

02flowchart TD

03 Req["A request reaches the application"] --> R1["Rule 1: every path, Set Connector origin-default"]

04 R1 --> R2{"Rule 2: does the continent or the country match?"}

05 R2 -->|"yes: the last match wins"| Reg["origin-regional"]

06 R2 -->|"no"| Def["origin-default stays"]

Every request matches the first rule, which sets origin-default.
A request from the continent or the countries of the second rule also matches it, which sets origin-regional, and the later rule wins.
Any other request keeps origin-default.

Prerequisites

An application served by a workload, with a first rule whose Set Connector behavior sends every request, ${uri} starts with /, to the default connector. To create them, refer to Applications quickstart.
A second connector, for the region. To create one, refer to Connectors quickstart.
A personal token, for the API procedures.
The Azion CLI installed and authorized, for the CLI procedures.

The examples use origin-default for the default connector, origin-regional with the ID <connector-id> for the regional one, and the application <application-id>. Replace them with your values.

Create the geolocation rule

The criterion names the location to match. Rules Engine reads it from the client’s IP address, and the variables and operators below need no Product on the application:

To match	Variable	Operator	Argument
One continent	`${geoip_continent_code}`, the two-letter continent code	is equal, `is_equal`	A code such as `NA`, for North America
One country	`${geoip_country_code}`, the two-letter country code	is equal, `is_equal`	A code such as `RU`, for Russia
A list of countries	`${geoip_country_code}`	matches, `matches`	A regular expression of country codes, such as `^(BR\|AR)$`

A continent code is geography, not a jurisdiction. When a rule must follow the countries a law or a contract names, match the country list. The ${geoip_city_*} variables read a different geolocation base, geoip_city. For every geolocation variable, refer to Variables.

The procedures match the continent NA. For a country list, change the criterion to the one in the table.

To create the rule in Azion Console:

Go to the Rules Engine tab

Access Azion Console > Applications > your application, then go to the Rules Engine tab.

Select + Rule

Name the rule

Enter a name that identifies the region. For example: geo - north america.

Select Request Phase

Match the continent

In the Criteria section, set the criterion to ${geoip_continent_code} is equal NA.

Set the connector

In the Behaviors section, select Set Connector, then select origin-regional.

Select Save

The rule appears in the Request list of the Rules Engine tab.

The criteria carry ${geoip_continent_code}, which a shell expands, so the body is sent from a file. To create the rule:

Write the rule to a file

Save the following as rule.json, with the ID of origin-regional in attributes.value:

JSON

01{

02 "name": "geo - north america",

03 "active": true,

  "criteria": [[{ "variable": "${geoip_continent_code}", "conditional": "if", "operator": "is_equal", "argument": "NA" }]],

05 "behaviors": [{ "type": "set_connector", "attributes": { "value": <connector-id> } }]

06}

Send the create request

Shell

01curl --request POST \

02 --url https://api.azion.com/v4/workspace/applications/<application-id>/request_rules \

03 --header 'Accept: application/json' \

04 --header 'Authorization: Token <personal-token>' \

05 --header 'Content-Type: application/json' \

06 --data @rule.json

The API answers 202 with "state": "pending" and the rule as it was stored, with its id and its order in the phase.

The CLI reads the rule from a JSON file. To create the rule:

Write the rule to a file

Save the following as rule.json, with the ID of origin-regional in attributes.value:

JSON

01{

02 "name": "geo - north america",

03 "active": true,

  "criteria": [[{ "variable": "${geoip_continent_code}", "conditional": "if", "operator": "is_equal", "argument": "NA" }]],

05 "behaviors": [{ "type": "set_connector", "attributes": { "value": <connector-id> } }]

06}

Create the rule

azion create rules-engine --application-id <application-id> --phase request --file rule.json

The command prints the ID of the rule:

Created Rules Engine with ID <rule-id>

Requests from North America go to origin-regional once the rule propagates, and every other request keeps origin-default. A new rule takes a few minutes to reach every data center.

Keep the geolocation rule after the default rule

The platform creates a new rule at the end of its phase, which is the position a geolocation rule needs. A reordered list can put the default rule last, and it then sends every request to origin-default again, with no change to any rule. Check the order after every change to the list.

To check the order in Azion Console:

Go to the Rules Engine tab

Access Azion Console > Applications > your application, then go to the Rules Engine tab.

Find the geolocation rule in the Request list

geo - north america sits after the default rule. If it does not, move it below the default rule.

To set the order, send the rule IDs of the phase in their new order, the default rule first, in the order array:

Shell

01curl --request PUT \

02 --url https://api.azion.com/v4/workspace/applications/<application-id>/request_rules/order \

03 --header 'Accept: application/json' \

04 --header 'Authorization: Token <personal-token>' \

05 --header 'Content-Type: application/json' \

06 --data '{ "order": [<default-rule-id>, <geo-rule-id>] }'

The list must name every rule of the phase. Each rule’s order field then holds its new position, starting at 0.

To read the order, list the rules of the phase with their position:

azion list rules-engine --application-id <application-id> --phase request --details

The output adds the ORDER, PHASE, and ACTIVE columns to the ID and NAME columns. ORDER starts at 0, and the geolocation rule must carry a higher number than the default rule.

To set the order, pass every rule ID of the phase, the default rule first:

azion update rules-engine-order --application-id <application-id> --phase request --rule-ids "<default-rule-id>,<geo-rule-id>"

The command confirms the new order:

Ordered Rules Engine of Application with ID <application-id>

The geolocation rule runs after the default rule, so its connector wins for the requests it matches.

The default cache key holds the scheme, the host, and the path, and no location. When the regional origins answer the same path with different content, a cache setting applied to that path can serve one region’s copy to another. For the key format, refer to Cache keys.

To test the rule, send a request from a machine in the region it matches, because the rule reads the location of the client’s IP address. To see which rules ran on a request, turn on Debug Rules.

Next steps

Rules Engine for ApplicationsEvery geolocation variable a rule can read, from the continent to the region.How Applications worksWhy the last matching Set Connector wins, and how rule order sets a default.Balancing methodsGive a regional connector a backup origin with the Primary and Backup roles.Route users to regional originsSend European users to a European origin, with a backup region only where residency allows it.