Configuring Traffic at the CDN cdn-configuring-cloud
AEM as a Cloud Service offers a collection of features configurable at the Adobe-managed CDN layer that modify the nature of either incoming requests or outgoing responses. The following rules, described in detail in this page, can be declared to achieve the following behavior:
- Request transformations - modify aspects of incoming requests, including headers, paths and parameters.
- Response transformations - modify headers that are on the way back to the client (for example, a web browser).
- Client-side redirects - trigger a browser redirect.
- Origin selectors - proxy to a different origin backend.
Also configurable at the CDN are Traffic Filter Rules (including WAF), which control what traffic is allowed or denied by the CDN. This feature is already released and you can learn more about it in the Traffic Filter Rules including WAF rules page.
Additionally, if the CDN cannot contact its origin, you can write a rule that references a self-hosted custom error page (which is then rendered). Learn more about this by reading the Configuring CDN error pages article.
All these rules, declared in a configuration file in source control, are deployed by using the Cloud Manager config pipeline. Be aware that the cumulative size of the configuration file, including traffic filter rules, cannot exceed 100KB.
Order of Evaluation order-of-evaluation
Functionally, the various features mentioned previously are evaluated in the following sequence:
Setup initial-setup
Before you can configure traffic at the CDN you need to do the following:
-
Create a file named
cdn.yamlor similar, referencing the various configuration snippets in the sections below.All snippets have these common properties, which are described under Config Pipeline. The
kindproperty value should be CDN and theversionproperty should be set to 1.code language-none kind: "CDN" version: "1" metadata: envTypes: ["dev"] -
Place the file somewhere under a top level folder named config or similar, as described under Config Pipeline.
-
Create a Config Pipeline in Cloud Manager, as described under Config Pipeline.
-
Deploy the configuration.
Rules Syntax configuration-syntax
The rule types in the sections below share a common syntax.
A rule is referenced by a name, a conditional “when clause”, and actions.
The when clause determines whether a rule will be evaluated, based on properties including domain, path, query strings, headers, and cookies. The syntax is the same across rule types; for details, see the Condition Structure section in the Traffic Filter Rules article.
The details of the actions node differ per rule type, and are outlined in the individual sections below.
Request Transformations request-transformations
Request transformation rules allow you to modify incoming requests. The rules support setting, unsetting, and altering paths, query parameters, and headers (including cookies) based on various matching conditions, including regular expressions. You can also set variables, which can then be referenced later in the evaluation sequence.
Use cases are varied and include URL rewrites for application simplification or mapping legacy URLs.
As mentioned earlier, there is a size limit to the configuration file so organizations with larger requirements should define rules in the apache/dispatcher layer.
Configuration example:
kind: "CDN"
version: "1"
metadata:
envTypes: ["dev", "stage", "prod"]
data:
requestTransformations:
removeMarketingParams: true
rules:
- name: set-header-rule
when:
reqProperty: path
like: /set-header
actions:
- type: set
reqHeader: x-some-header
value: some value
- name: set-header-with-reqproperty-rule
when:
reqProperty: path
like: /set-header
actions:
- type: set
reqHeader: x-some-header
value: {reqProperty: path}
- name: unset-header-rule
when:
reqProperty: path
like: /unset-header
actions:
- type: unset
reqHeader: x-some-header
- name: unset-matching-query-params-rule
when:
reqProperty: path
equals: /unset-matching-query-params
actions:
- type: unset
queryParamMatch: ^removeMe_.*$
- name: unset-all-query-params-except-exact-two-rule
when:
reqProperty: path
equals: /unset-all-query-params-except-exact-two
actions:
- type: unset
queryParamMatch: ^(?!leaveMe$|leaveMeToo$).*$
- name: multi-action
when:
reqProperty: path
like: /multi-action
actions:
- type: set
reqHeader: x-header1
value: body set by transformation rule
- type: set
reqHeader: x-header2
value: '201'
- name: replace-html
when:
reqProperty: path
like: /mypath
actions:
- type: transform
reqProperty: path
op: replace
match: \.html$
replacement: ""
Actions
Explained in the table below are the available actions.
Replace actions support capture groups, as illustrated below:
- name: extract-country-code-from-path
when:
reqProperty: path
matches: ^/([a-zA-Z]{2})(/.*|$)
actions:
- type: set
var: country-code
value:
reqProperty: path
- type: transform
var: country-code
op: replace
match: ^/([a-zA-Z]{2})(/.*|$)
replacement: \1
- name: replace-jpg-with-jpeg
when:
reqProperty: path
like: /mypath
actions:
- type: transform
reqProperty: path
op: replace
match: (.*)(\.jpg)$
replacement: "\1\.jpeg"
Actions can be chained together. For example:
actions:
- type: transform
reqProperty: path
op: replace
match: \.html$
replacement: ""
- type: transform
reqProperty: path
op: tolower
Variables variables
You can set variables during the request transformation and then reference them later on in the evaluation sequence. See the order of evaluation diagram for further details.
Configuration example:
kind: "CDN"
version: "1"
metadata:
envTypes: ["prod", "dev"]
data:
requestTransformations:
rules:
- name: set-variable-rule
when:
reqProperty: path
equals: /set-variable
actions:
- type: set
var: some_var_name
value: some_value
responseTransformations:
rules:
- name: set-response-header-while-variable
when:
var: some_var_name
equals: some_value
actions:
- type: set
respHeader: x-some-header
value: some header value
Response Transformations response-transformations
Response transformation rules allow you to set and unset headers of the CDN’s outgoing responses. Also, see the example above for referencing a variable previously set in a request transformation rule.
Configuration example:
kind: "CDN"
version: "1"
metadata:
envTypes: ["prod", "dev"]
data:
responseTransformations:
rules:
- name: set-response-header-rule
when:
reqProperty: path
like: /set-response-header
actions:
- type: set
value: value-set-by-resp-rule
respHeader: x-resp-header
- name: unset-response-header-rule
when:
reqProperty: path
like: /unset-response-header
actions:
- type: unset
respHeader: x-header1
# Example: Multi-action on response header
- name: multi-action-response-header-rule
when:
reqProperty: path
like: /multi-action-response-header
actions:
- type: set
respHeader: x-resp-header-1
value: value-set-by-resp-rule-1
- type: set
respHeader: x-resp-header-2
value: value-set-by-resp-rule-2
Actions
Explained in the table below are the available actions.
Origin Selectors origin-selectors
You can leverage the AEM CDN to route traffic to different backends, including non-Adobe applications (perhaps on a per-path or subdomain basis).
Configuration example:
kind: "CDN"
version: "1"
metadata:
envTypes: ["dev"]
data:
originSelectors:
rules:
- name: example-com
when: { reqProperty: path, like: /proxy* }
action:
type: selectOrigin
originName: example-com
# skipCache: true
origins:
- name: example-com
domain: www.example.com
# ip: '1.1.1.1'
# forwardHost: true
# forwardCookie: true
# forwardAuthorization: true
# timeout: 20
Actions
Explained in the table below is the available action.
Origins
Connections to origins are SSL only and use port 443.
Proxying to Edge Delivery Services proxying-to-edge-delivery
There are scenarios where origin selectors should be used to route traffic through AEM Publish to AEM Edge Delivery Services:
- Some content is delivered by a domain managed by AEM Publish, while other content from the same domain is delivered by Edge Delivery Services
- Content delivered by Edge Delivery Services would benefit from rules deployed via config pipeline, including traffic filter rules or request/response transformations
Here is an example of an origin selector rule that can accomplish this:
kind: CDN
version: '1'
data:
originSelectors:
rules:
- name: select-edge-delivery-services-origin
when:
allOf:
- reqProperty: tier
equals: publish
- reqProperty: domain
equals: <Production Host>
- reqProperty: path
matches: "^(/scripts/.*|/styles/.*|/fonts/.*|/blocks/.*|/icons/.*|.*/media_.*|/favicon.ico)"
action:
type: selectOrigin
originName: aem-live
origins:
- name: aem-live
domain: main--repo--owner.aem.live
Client-side Redirects client-side-redirectors
You can use client side redirect rules for 301, 302 and similar client side redirects. If a rule matches, the CDN responds with a status line that includes the status code and message (for example, HTTP/1.1 301 Moved Permanently), as well as the location header set.
Both absolute and relative locations with fixed values are allowed.
Be aware that the cumulative size of the configuration file, including traffic filter rules, cannot exceed 100KB.
Configuration example:
kind: "CDN"
version: "1"
metadata:
envTypes: ["dev"]
data:
redirects:
rules:
- name: redirect-absolute
when: { reqProperty: path, equals: "/page.html" }
action:
type: redirect
status: 301
location: https://example.com/page
- name: redirect-relative
when: { reqProperty: path, equals: "/anotherpage.html" }
action:
type: redirect
location: /anotherpage
The locations of a redirect can be either string literals (e.g., https://www.example.com/page) or the result of a property (e.g., path) that is optionally transformed, with the following syntax:
experimental_redirects:
rules:
- name: country-code-redirect
when: { reqProperty: path, like: "/" }
action:
type: redirect
location:
reqProperty: clientCountry
transform:
- op: replace
match: '^(.*)$'
replacement: 'https://www.example.com/\1/home'
- op: tolower
- name: www-redirect
when: { reqProperty: domain, equals: "example.com" }
action:
type: redirect
location:
reqProperty: path
transform:
- op: replace
match: '^/(.*)$'
replacement: 'https://www.example.com/\1'