Cache quickstart

Create a cache setting in Azion Console, the Azion CLI, or the API, apply it to one path with a Rules Engine rule, and read the cache status of a response.

Last updated

View as Markdown Agent setup

This guide instructs you through caching a path of your application for the first time. By the end you will have:

  • A cache setting that keeps a copy of each response for 300 seconds.
  • A Rules Engine rule that applies the setting to one path prefix.
  • The cache status of a response, read from its x-cache header.

The result rests on four objects, in this order. The application carries the Cache module, which is on for every application. The cache setting belongs to the application and holds the TTL, the time Azion keeps a copy. The rule, also on the application, matches requests by path and applies the setting through the Set Cache Policy behavior. A matching request is answered from the stored copy when one exists, and its response carries x-cache with HIT. Until a rule names it, a cache setting does nothing.

Select the interface you will use. The prerequisites and every stage below follow that choice.

Prerequisites

  • An application that already serves content on a domain. To create one, refer to Applications quickstart.
  • The URL of a static object the application serves, such as an image, to check at the end.
  • curl on your machine, for the cache status check at the end.

Create a cache setting

A cache setting holds how long Azion keeps a copy of a response. This one keeps each copy for 300 seconds.

To create the cache setting in Azion Console:

Open the application

Access Azion Console > Applications, then select the application that serves your content.

Go to the Cache Settings tab
Select + Cache
Name the cache setting

In Name, enter static-assets.

Keep Override cache behavior selected

Under Cache, keep Override cache behavior selected. With this option, Max Age replaces the TTL the origin sends.

Set Max Age

In Max Age, replace 60 with 300.

Select Save

The new setting appears in the Cache Settings list, which shows its Name, ID, Browser Cache, and Cache.

To create the cache setting with the Azion CLI, replace <application_id> with the ID of your application:

Save the request body

The command reads the setting from a JSON file. Save this body as cache-setting.json:

JSON
01{
02 "name": "static-assets",
03 "browser_cache": { "behavior": "honor" },
04 "modules": {
05 "cache": {
06 "behavior": "override",
07 "max_age": 300
08 }
09 }
10}
Run the create command
azion create cache-setting --application-id <application_id> --file cache-setting.json

The command confirms the setting and returns its ID:

Created Cache Settings configuration with ID 123460
Read the setting back

Replace 123460 with the ID the create command returned:

azion describe cache-setting --application-id <application_id> --cache-setting-id 123460 --format json

The output reports modules.cache.max_age as 300.

The cache setting exists on the application. Record its ID: the rule in the next stage names it.

The command flags do not set Max Age, the cache behavior, stale cache, Large File Optimization, or Tiered Cache. Pass the request body with --file for those fields. For every flag the command accepts, refer to Azion CLI create.

To create the cache setting with the Azion API, replace [TOKEN VALUE] with your personal token and <application_id> with the ID of your application:

Send the create request
Shell
01curl --request POST \
02 --url https://api.azion.com/v4/workspace/applications/<application_id>/cache_settings \
03 --header 'Accept: application/json' \
04 --header 'Authorization: Token [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data {
07 "name": "static-assets",
08 "browser_cache": { "behavior": "honor" },
09 "modules": {
10 "cache": {
11 "behavior": "override",
12 "max_age": 300
13 }
14 }
15}
Read the response

A 201 carries the setting, with every field the request left out filled by its default:

JSON
01{
02 "state": "executed",
03 "data": {
04 "id": 123459,
05 "name": "static-assets",
06 "browser_cache": { "behavior": "honor", "max_age": 0 },
07 "modules": {
08 "cache": {
09 "behavior": "override",
10 "max_age": 300,
11 "stale_cache": { "enabled": false },
12 "large_file_cache": { "enabled": false, "offset": 1024 },
13 "tiered_cache": { "enabled": false }
14 }
15 }
16 }
17}

The cache setting exists on the application. Record the id: the rule in the next stage names it.

A Max Age below 60 seconds requires the Application Accelerator module on the application.

Apply the setting with a rule

A cache setting does nothing until a rule names it. This rule applies static-assets to every request whose path matches a prefix you choose.

To create the rule in Azion Console:

Go to the Rules Engine tab
Select + Rule
Name the rule

Enter a name such as cache-static-assets.

Select Request Phase
Set the criteria

Under Criteria, select ${uri} and an operator. As the argument, enter the path prefix to cache, such as /static/.

Add the Set Cache Policy behavior

Under Behaviors, select Set Cache Policy, then select static-assets.

Select Save

The rule appears in the list and applies static-assets to every request whose path matches its criteria.

To create the rule with the Azion CLI, replace <application_id> with the ID of your application:

Save the request body

The criteria carry ${uri}, which a shell expands, so the rule goes in a file. Save this body as rule.json, and replace 123460 with the ID of the cache setting from the previous stage:

JSON
01{
02 "name": "cache-static-assets",
03 "active": true,
04 "criteria": [
05 [
06 {
07 "conditional": "if",
08 "variable": "${uri}",
09 "operator": "starts_with",
10 "argument": "/static/"
11 }
12 ]
13 ],
14 "behaviors": [
15 {
16 "type": "set_cache_policy",
17 "attributes": { "value": 123460 }
18 }
19 ]
20}
Run the create command
azion create rules-engine --application-id <application_id> --phase request --file rule.json

The command confirms the rule and returns its ID:

Created Rules Engine with ID 234570

The rule exists on the application and applies static-assets to every request whose path starts with /static/.

To create the rule with the Azion API, replace [TOKEN VALUE] with your personal token and <application_id> with the ID of your application:

Save the request body

The criteria carry ${uri}, which a shell expands, so the body goes in a file instead of on the command line. Save this body as rule.json, and replace 123459 with the ID of the cache setting from the previous stage:

JSON
01{
02 "name": "cache-static-assets",
03 "active": true,
04 "criteria": [
05 [
06 {
07 "conditional": "if",
08 "variable": "${uri}",
09 "operator": "starts_with",
10 "argument": "/static/"
11 }
12 ]
13 ],
14 "behaviors": [
15 {
16 "type": "set_cache_policy",
17 "attributes": { "value": 123459 }
18 }
19 ]
20}
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 [TOKEN VALUE]' \
05 --header 'Content-Type: application/json' \
06 --data @rule.json
Read the response

A 202 carries the rule, and the state pending means the platform is still applying it:

JSON
01{
02 "state": "pending",
03 "data": {
04 "id": 234569,
05 "name": "cache-static-assets",
06 "active": true,
07 "behaviors": [
08 {
09 "type": "set_cache_policy",
10 "attributes": { "value": 123459 }
11 }
12 ],
13 "order": 2
14 }
15}

The rule exists on the application and applies static-assets to every request whose path starts with /static/.

A new rule can take a few minutes to propagate. Wait before you check the cache status.

Check the cache status

The request header Pragma: azion-debug-cache makes the response carry two debug headers. x-cache holds the cache status, the IP of the server that answered, and the protocol. x-cache-key holds the key that indexes the copy.

Request the object with the debug header

Request an object under the path the rule matches, with your own host and path:

curl -sI -H "Pragma: azion-debug-cache" https://www.example.com/static/site.js
Read the cache status

The response carries the two debug headers. Under HTTP/2, the header names arrive in lowercase:

HTTP
01x-cache: MISS from 192.0.2.10 with HTTP/2.0
02x-cache-key: httpswww.example.com/static/site.js

MISS means the object was not in the cache: Azion fetched it from the origin and may store the response.

Run the same command again
Read the cache status again

A response answered from the stored copy carries HIT. x-cache also names the server that answered.

Your application now keeps a copy of each matching response for 300 seconds. x-cache tells you when a response came from that copy. A response can also carry another status, such as REVALIDATED. For every status value, refer to Cache keys.

Next steps

Expiration and freshnessHow a request finds a stored copy, how the TTL expires it, and what stale cache does when the origin fails.Cache settingsEvery field a cache setting carries, including the browser TTL and stale cache.Create a cache settingThe same cache setting and rule through the Azion API and the Azion CLI.Purge cached contentRemove a stored copy before its TTL expires, by URL, cache key, or wildcard.Applications limitsThe bounds on TTL values, cache setting names, object size, and purge requests.Troubleshoot ApplicationsWhat to check when a response is not served from the cache.