Configure cache policies for an application

From Azion Console or the API, you set how long an object stays cached, bypass the cache for a path, and forward the origin’s Set-Cookie header. A cache setting carries the cache policy, and a Rules Engine rule applies it to the requests you choose.

To vary a cached object by a query string argument or by a cookie, refer to Configure Advanced Cache Key.

Prerequisites

Console

An application. To create one, refer to Applications quickstart.
Access to Azion Console. Refer to Access Azion Console.
Application Accelerator can generate usage-related costs. For the rates, refer to Pricing.

Turn on Application Accelerator

A cache setting needs no module, and any application can carry one. Application Accelerator is required for a Max Age below 60 seconds, for cache variation, and for the Bypass Cache and Forward Cookies behaviors. The module is off by default. To turn it on:

Open the application

Access Azion Console > Applications > your application.

Turn on the module

On the Main Settings tab, in the Modules section, turn on Application Accelerator.

Select Save

The application runs with Application Accelerator. Its cache settings accept a Max Age below 60 seconds, and Bypass Cache and Forward Cookies become available in Rules Engine.

Set the cache TTL for a path

A cache setting holds the time-to-live (TTL) the browser applies and the TTL Azion applies. To create one:

Open the Cache Settings tab

Access Azion Console > Applications > your application, then go to the Cache Settings tab.

Select + Cache

Name the cache setting

In Name, enter a name that identifies the setting. For example: /target-uri - Cache TTL.

Set the browser cache

Under Browser Cache, select Override cache settings and set the maximum age in seconds.

Set Max Age

Under Cache, select Override cache behavior and set Max Age to the number of seconds Azion keeps the object.

Select Save

The cache setting appears in the Cache Settings tab. The same setting can also vary the cached object by query string or by cookie, which is the Advanced Cache Key feature.

A cache setting takes effect only when a rule applies it. To apply this one to the /target-uri path:

Go to the Rules Engine tab

Select + Rule

Name the rule

Enter a name for the rule. For example: /target-uri - Cache TTL.

Select Request Phase

Select the variable in the Criteria section

In the Criteria section, select the ${uri} variable.

Select starts with as the comparison operator

Enter the argument

Enter /target-uri as the argument.

In the Behaviors section, select Set Cache Policy

Select the cache setting you created

Select Save

Requests whose URI starts with /target-uri carry the cache setting, at both the browser TTL and the Azion TTL you set. A new rule takes a few minutes to propagate.

Bypass the cache for a path

Bypass Cache stops Azion from caching the origin response for the requests a rule matches. To create the rule:

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 for the rule. For example: /target-uri - Bypass Cache.

Select Request Phase

Select the variable in the Criteria section

In the Criteria section, select the ${uri} variable.

Select starts with as the comparison operator

Enter the argument

Enter /target-uri as the argument.

In the Behaviors section, select Bypass Cache

Select Save

Requests whose URI starts with /target-uri reach the origin, and Azion stores no response for them. A new rule takes a few minutes to propagate.

Bypass Cache affects only the cache on Azion, not the browser cache. The browser cache comes from the cache setting that Set Cache Policy applies.

For more information, refer to Bypass Cache. For the difference between Bypass Cache and a Max Age of 0 seconds, refer to Cache variation.

Bypass the cache for a path with the API

Bypass Cache can also be set with the API, by sending a rule with a bypass_cache behavior. The example bypasses the cache on /api/, with a rule named cdn - api pass-through. Replace each value with your own. To create the bypass rule:

Shell

01curl --request POST \

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

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

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

05 --data {

06 "name": "cdn - api pass-through",

07 "active": true,

08 "criteria": [[{ "variable": "${uri}", "conditional": "if", "operator": "starts_with", "argument": "/api/" }]],

09 "behaviors": [{ "type": "bypass_cache" }]

10}

The API answers 202 with a state of pending and the rule as it was stored.

Requests whose URI starts with /api/ reach the origin, and Azion stores no response for them. A new rule takes a few minutes to propagate.

To confirm the rule, request a path it matches with the Pragma: azion-debug-cache header:

curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/api/status

The response carries x-cache: BYPASS. For how to read the header, refer to Check the cache status of a response.

The Accelerate websites and APIs with a CDN use case uses the values of this example.

These checks confirm the Accelerate websites and APIs with a CDN use case.

Forward cookies from the origin to the user

Forward Cookies sends the origin’s Set-Cookie header to users, including on a cache hit. To create the rule:

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 for the rule. For example: /target-uri - Forward Cookies.

Select Request Phase

Select the variable in the Criteria section

In the Criteria section, select the ${uri} variable.

Select starts with as the comparison operator

Enter the argument

Enter /target-uri as the argument.

In the Behaviors section, select Forward Cookies

Select Save

Requests whose URI starts with /target-uri return the origin’s Set-Cookie header to the user.

The forwarded header can carry session cookies. To stop a user from receiving the session cookies of another user:

Go to the Cache Settings tab

Select + Cache

Name the cache setting

In Name, enter a name that identifies the setting. For example: /target-uri - Private cookies.

Denylist the session cookies

Under Application Accelerator, open Cache vary by Cookies and set Behavior to Denylist.

Enter the cookie names

Add each session cookie to the list of cookie names.

Select Save

The cache setting appears in the Cache Settings tab, and it keeps the listed cookies out of the cache key.

To apply that cache setting to the rule that forwards the cookies:

Go to the Rules Engine tab

Select the rule

Select the /target-uri - Forward Cookies rule.

In the Behaviors section, select + Behavior

Select Set Cache Policy

Select the cache setting

Select the /target-uri - Private cookies cache setting.

Select Save

The rule forwards the origin’s Set-Cookie header and applies the cache setting. A rule change takes a few minutes to propagate. The same rule can also carry the Bypass Cache behavior.

Cache a set of paths only for visitors without a session

A rule can hold several criteria. In a group, each criterion after the first joins the one before it with And or Or, and groups join with And, so a request matches only when it meets every group. The rule in this section joins its two paths with Or in one group and checks the cookie in a second group. It caches two catalog paths only for requests that carry no session cookie, so a signed-in visitor never receives a shared copy. The example uses /products/ and /category/ for the paths and session_id for the cookie the origin sets when a session starts. Replace each one with your own.

The cache setting keeps a page for 600 seconds on Azion and overrides the browser cache to 0 seconds, because a copy in the browser cannot be purged.

Console

Create a cache setting named storefront-catalog, as Set the cache TTL for a path shows, with a browser maximum age of 0 and a Max Age of 600. To create the rule that applies it:

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 storefront - catalog cache.

Select Request Phase

Match the catalog paths

In the Criteria section, set the first criterion to ${uri} starts with /products/. Add a second criterion joined by Or: ${uri} starts with /category/.

Exclude visitors with a session

Add a second criteria group with one criterion: ${cookie_session_id} does not exist.

In the Behaviors section, select Set Cache Policy

Select the storefront-catalog cache setting

Select Save

Catalog and product pages requested without a session cookie are cached for 600 seconds, and browsers revalidate them on every visit. A new rule takes a few minutes to propagate.

The Build e-commerce storefronts use case uses the values of this example.

One rule can send every per-visitor request to the origin. The rule in this section matches the cart, checkout, and account paths, and any request that carries the session cookie, so a visitor with a session bypasses the cache on every path. It carries Forward Cookies as well, so the session cookie the origin sets reaches the visitor. Nothing this rule matches is cached, so the denylist cache setting of Forward cookies from the origin to the user is not needed here. The example uses /cart, /checkout, /account, and session_id. Replace each one with your own.

Console

To create the bypass rule:

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 storefront - bypass per-visitor pages.

Select Request Phase

Match the per-visitor paths

In the Criteria section, set the first criterion to ${uri} starts with /cart. Add two criteria joined by Or: ${uri} starts with /checkout, and ${uri} starts with /account.

Match the session cookie

Add a fourth criterion joined by Or: ${cookie_session_id} exists.

In the Behaviors section, select Bypass Cache

Add the Forward Cookies behavior

Select Save

Cart, checkout, and account requests, and every request with a session, reach the origin, and Azion stores none of their responses. A new rule takes a few minutes to propagate.

To confirm both rules, request a catalog page twice without a cookie, then the cart, then a catalog page with the session cookie, each with the Pragma: azion-debug-cache header:

Shell

01curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/products/blue-shirt

02curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/cart

03curl -sI -H "Pragma: azion-debug-cache" -H "Cookie: session_id=test" https://www.example.com/products/blue-shirt

The second catalog request carries x-cache: HIT. The cart and the request with the cookie carry x-cache: BYPASS. For how to read the header, refer to Check the cache status of a response.

The Build e-commerce storefronts use case uses the values of this example.

These checks confirm the Build e-commerce storefronts use case.

Next steps

Cache variationWhat Bypass Cache does that a Max Age of 0 seconds does not.Cache SettingsEvery field a cache setting carries, with its values and defaults.Verify cache indicators with ModHeaderRead the cache headers a request returns and confirm the policy you applied.Real-Time PurgeExpire a cached object before its Max Age runs out.Build e-commerce storefrontsA storefront that caches catalog pages for visitors without a session and bypasses the cache for cart, checkout, and account.Accelerate websites and APIs with a CDNTwo cache settings, one with Tiered Cache, and a rule that passes API calls through to the origin.