Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/content-delivery/cdn-configuring-traffic, .../cdn-cache-purge and .../cdn-credentials-authentication
Open this when writing or debugging cdn.yaml, setting up purging, adding WAF or rate-limit rules, or putting your own CDN in front of AEM.
The config pipeline
CDN rules do not ship with the code. They live in a config folder in the Git branch a config pipeline (Adobe calls these Targeted Deployment Pipelines) builds, and they deploy in minutes without a code build. The available kind values are:
kind |
Purpose |
|---|---|
CDN |
Traffic filters and WAF, request/response transformations, redirects, origin selectors, authentication (purge keys) |
MaintenanceTasks |
Maintenance task scheduling |
LogForwarding |
Forwarding AEM, dispatcher and CDN logs to a destination |
API |
Registering client IDs for the Content Fragment Delivery OpenAPI |
All config-pipeline files together must stay under 100 KB.
cdn.yaml shape
kind: "CDN"
version: "1"
data:
requestTransformations:
rules: []
responseTransformations:
rules: []
redirects:
rules:
- name: redirect-legacy-page
when: { reqProperty: originalPath, equals: "/page.html" }
action:
type: redirect
status: 301
location: https://www.example.com/page
originSelectors:
rules: []
trafficFilters:
rules:
- name: block-admin-paths
when:
reqProperty: path
matches: "^/admin.*"
action:
type: block
- Redirect
statusaccepts301,302,303,307,308. - Traffic filter actions include
blockandlog. Start every new rule withlog, watch the CDN logs for false positives, then switch toblock. WAF rule families need the WAF licence; traffic filter rules (rate limiting, path, geo, IP) do not. - Rate limiting is a traffic-filter rule with a rate condition; scope it to the paths that need it (form handlers, search, GraphQL) rather than the whole site, or you will throttle crawlers into a ranking problem.
Purging
Declare a purge key as an authenticator, referencing a Cloud Manager secret environment variable:
kind: "CDN"
version: "1"
data:
authentication:
authenticators:
- name: purge-auth
type: purge
purgeKey1: ${{CDN_PURGEKEY_031224}}
purgeKey2: ${{CDN_PURGEKEY_021225}}
rules:
- name: purge-auth-rule
when: { reqProperty: tier, equals: "publish" }
action:
type: authenticate
authenticator: purge-auth
- At least one of
purgeKey1/purgeKey2is required; two slots exist so you can rotate without downtime. Generate withopenssl rand -hex 32(32 bytes minimum recommended). - Purge a single URL:
curl -X PURGE "https://publish-p1234-e5678.adobeaemcloud.com/content/acme/en/hotfix.html" \
-H 'X-AEM-Purge-Key: <purge_key>' \
-H 'X-AEM-Purge: soft'
X-AEM-Purge: hard(the default) evicts immediately;softmarks the object stale so the CDN revalidates against the origin and keeps serving while it does. Prefersoftfor anything on a hot path.- Purge a group by surrogate key: have the response carry
Surrogate-Key: <keys separated by spaces>, then send the same header on the PURGE request. Emit surrogate keys from the vhost (Header set Surrogate-Key "site-acme brand-acme") or from AEM per response, and design them the way you design the content tree: one key per site, per template, per fragment. - Purging is not a substitute for a cache plan. Keep HTML TTLs sane, and purge on the events that are genuinely unpredictable (hotfixes, emergency copy changes, campaign go-live).
BYO CDN
- Point your CDN at the Adobe CDN, not around it — the Adobe CDN is also where traffic filters and WAF run.
- The forwarded host and the edge key must be sent as required by the current BYO CDN setup (
X-Forwarded-Host,X-AEM-Edge-Key); AEM uses them to resolve the site and to trust the request. Without the edge key the request is treated as direct traffic. - Avoid double caching with conflicting TTLs: pick which layer owns HTML TTL and make the other one obey
Cache-Control. Purging must fire on both layers, or the stale object simply moves one hop out.
Useful response headers when debugging
| Header | Meaning |
|---|---|
x-cache |
HIT/MISS at the CDN (and how many layers hit) |
age |
Seconds the object has been in cache |
x-aem-* |
Platform diagnostics on some responses |
Server-Timing |
Included on CDN responses; useful for separating edge from origin time |
CDN logs are available through Cloud Manager and can be forwarded with a LogForwarding config. The cache field is what you aggregate for a hit-ratio-per-path report (aem-performance).