Org Skills

Adobe CDN — `cdn.yaml`, purge, traffic filters, BYO CDN

Supporting material for aem-dispatcher. Agents load it on demand; it ships inside the skill folder.

RawSource

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 status accepts 301, 302, 303, 307, 308.
  • Traffic filter actions include block and log. Start every new rule with log, watch the CDN logs for false positives, then switch to block. 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 / purgeKey2 is required; two slots exist so you can rotate without downtime. Generate with openssl 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; soft marks the object stale so the CDN revalidates against the origin and keeps serving while it does. Prefer soft for 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).