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

> **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

```yaml
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:

```yaml
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:

```bash
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`).
