style

content

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 or a developer pushes code changes to the main branch (changes on other branches do not trigger push invalidation).

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