Configuring push invalidation for BYO production CDN

Push invalidation automatically purges content on the customer's production CDN (e.g. www.yourdomain.com), whenever an author publishes content changes.

Content is purged by url and by cache tag/key.

Setting up push invalidation requires 2 steps:

• Configuration
• Opt-In Request Header

Configuration

Push invalidation is currently supported for CDNs of the following vendors:

• Fastly
• Akamai
• Cloudflare
• CloudFront

Push invalidation is enabled by adding specific properties to the project's configuration (an Excel workbook named .helix/config.xlsx in Sharepoint or a Google Sheet named .helix/config in Google Drive).

The following sections describe the vendor specific properties required to set up push invalidation.

Fastly

Configuration properties:

key	value	comment
cdn.prod.host	<Production Host>	Host name of production site, e.g. www.yourdomain.com
cdn.prod.type	fastly
cdn.prod.serviceId	<Fastly Service ID>	Service ID of production service
cdn.prod.authToken	<Fastly API Token>

Create a Fastly API Token

• go to Personal API Tokens,
• click on "Create Token",
• enter a name (e.g. "Production Site Purge Token"),
• select "A specific service" and your production service from the drop-down list,
• check the "Purge select content (purge_select) — Purge by URL or surrogate key" check box,
• select "Never expire",
• click on "Create Token",
• copy the generated token value shown in the pop-up window.

You can validate the credentials with this tool.

Akamai

Configuration properties

key	value	comment
cdn.prod.host	<Production Host>	Host name of production site, e.g. www.yourdomain.com
cdn.prod.type	akamai
cdn.prod.endpoint	<host>	Fast Purge API credentials
cdn.prod.clientSecret	<client_secret>	Fast Purge API credentials
cdn.prod.clientToken	<client_token>	Fast Purge API credentials
cdn.prod.accessToken	<access_token>	Fast Purge API credentials

Push invalidation uses the Akamai Fast Purge API, specifically Delete by URL and Delete by cache tag.

The Fast Purge API credentials consist of

host = akaa-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.luna.akamaiapis.net
client_token = akab-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX
client_secret = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
access_token = akab-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX

They can be generated by following the instructions at Create an API client with custom permissions.

Identity & Access Management

Create API client

Required group/role permissions:

You can validate the credentials with this tool.

Cloudflare

Configuration properties

key	value	comment
cdn.prod.host	<Production Host>	Host name of production site, e.g. www.yourdomain.com
cdn.prod.type	cloudflare
cdn.prod.plan	e.g. free	values: free, pro, business, enterprise default: free only enterprise plan supports purge-by-tag
cdn.prod.zoneId	<Cloudflare Zone ID>	ID of production zone
cdn.prod.apiToken	<Cloudflare API Token>

Create an API Token

• go to API Tokens
• click on "Create Token",
• go to "Create Custom Token" at the bottom and click on "Get started"
• enter a token name (e.g. "Production Site Purge Token"),
• Permissions: "Zone", "Cache Purge", "Purge"
• Zone Resources: "Include", "Specific zone", "<your production zone>"
• click on "Continue to summary"
• click on "Create Token",
• copy the generated token value.

Note that only sites on the enterprise plan will be surgically purged by url and cache key. A Purge All will be performed instead on non-enterprise sites every time an author publishes a content change.

You can validate the credentials with this tool.

CloudFront

NB: CloudFront does NOT support purging by cache tag/key. Purge by cache tag/key always triggers a purge all.

Configuration properties

key	value	comment
cdn.prod.host	<Production Host>	Host name of production site, e.g. www.yourdomain.com
cdn.prod.type	cloudfront
cdn.prod.distributionId	<Cloudfront Distribution ID>
cdn.prod.accessKeyId	<AWS Access key ID>	AWS credentials
cdn.prod.secretAccessKey	<AWS Secret access key>	AWS credentials

Create the AWS credentials

In the AWS Console, open the IAM dashboard:

Select Users -> Add users:

Enter a user name and check “Access key - Programmatic access”:

On the “Set permissions” pane, click on “Create group”:

Enter a group name and select the CloudFrontFullAccess policy:

Create the user:

Finally, copy the Access key ID and Secret access key values:

You can validate the credentials with this tool.

Opt-In Request Header

The production CDN needs to send the following opt-in header to the origin in order to enable long cache TTLs:

X-Push-Invalidation: enabled