There are frequent use cases where you want to cache a ressource depending on the geography or any other client level information, for example:
- you might want to cache a page that depend on a country
- and you might want to change the origin server accordingly
In both cases, you will need to add the geographic info into the cache-key and this article will show you how to do it. If your ressource is not cacheable then you can use this template and omit the cache-key modification part, keeping only the origin change behavior based on the variable.
The geographic data you can use are the one you may get from the Edgescape service option like the continent or the country of the user user sending a request. In this article we will use the country information as this is by far the case we see the most.
Typical Request flow
The typical request flow makes this use case not so easy to implement. In your configuration, you might be using Tiered Distribution or SiteShield, the request flow for a cacheable content will be:
The above figure shows this typical request flow, an end user (User 1) is sending request to an Edge server, this Edge server will get the content from his local cache but if the content is not found or is stale, the edge server will send the request to his parent server. At the parent level, the content will be fetched from his local cache or if the content is not found or is stale, the server will send the request to the origin server.
This request flow is the most typical but there is one that should not be forgotten: this is when the end user is connecting to a server which happen to be also a parent as shown for 'User 2'. When this happens, the server react as an Edge server but if it needs to proxy the request, it will do it to the Origin directly. The later case is also the one to consider when Tiered Distribution and SiteShield are not active.
When setting up a configuration with Property Manager, it is important to keep this request flow in your mind.
Anyway what's special about caching geography dependent ressource ?
What's makes this use case not so easy to implement is that the geographic data can be fetched at the Edge server level only, the parent level does not automatically 'inherit' this information from the edge level. So if you try to setup a rule that match on a country and change the origin server accordingly, it won't work for 'User 1'. For 'User 2' it will work if you are doing it the right way in order not to break the purge mechanism.
The main concerns are the following:
The geographic data is known at the edge only so the origin change will not work at the parent level unless the configuration exports the geographic data to the parent level.
The cache-key has to be modified to include the geographic data both at the edge and at the parent levels.
If both rules are enforced in the configuration then both User 1 and User 2 will get the right content and you will be able to purge it when necessary.
Here is the set of behavior to include in your configuration in order to implement these use cases.
You might be adding this template inside a match on path and/or extension if you need it, or at the global level (but most user needs it for cacheable content that is not static, because static content usually does not depend on geography) so let's start with an example rule where we want to limit the feature to url that are not static (this is the goal of the negative match on extension) and are only present into the specific directory '/possible_path_restriction/*' in this example I wanted to cache geographic ressources with a 1 day TTL:
Now let's really implement the setting, first we will include a behavior that will be triggered both at the edge level and the parent level, it will initialize the new variable (do not forget to declare it, see the yellow block):
Next step is to override the variable when we are at the edge level with the country code value. The trick here is that we are not changing the cache-key or the origin server inside a geo match but only setting a variable. The list of country code should be the complete list of all the country you have specific content for. later we will use specif match to change the origin for each contry individually.
Optional step : if you need to group together several country code into a unique one use the behavior below or else you may just skip this behavior.
Here we want to group all french related country code into one 'FR' code.
This step is required in all cases, we want to send a header with the country code value to the next level.
Bonus: the origin server will get it too. It is very important to keep it inside the edge level match so that it does not gets rewritten or removed by the parent.
Next, we want to add the variable into the cache-key, this is also required in all cases.
You might choose a variant of this code adapted to your specific needs if you are already using the Cache ID Modification behavior or any other feature that modify the cache key elsewhere in your configuration.
Be careful to make this rule a sibling of the 'Edge Only' rule, child of the main rule and located after the 'Edge Only' rules (see the red arrow for the right alignement)
One way to check that the rules do have the right relationship is to collapse them using the '-' button, you should see the following:
Now we are good to change the origin server if you need that, some customers do not have different origin servers so you may skip this part if that is the case for you. In this example, I wanted to change origin only when the request comes from France or Deutschland, keeping the globally defined origin for all others countries.
I like to group together rules when they are closely related so I did it that way:
Do not change the 'Cache Key Hostname' to anything else than 'Incoming Host Header' it won't work the way you might be expecting. We already managed to have the country code into the cache-key so this is not required and it will defeat the behavior usage that we need which is to change only the next level IP to be the geographic specific origin. Modifying it will break the cache-key: you will get cache mismatch (page for one country sent for another country) and the purge system will not work well.
Ready for Staging !
You are now ready to propagate and test on the staging network.
We are expecting the following warning from the 'Edge Only' rule, we are purposely playing with the fact that 'User Location Match' are only active at the edge level ! so you can safely continue with this setting.