CDN APIs for Phased Headless Rollouts

A phased headless rollout is a technique for delivering a single shopping experience using multiple storefront technologies like Storefront Reference Architecture (SFRA) and Composable Storefront.

An embedded CDN (eCDN) zone can route traffic to both SFRA and Managed Runtime at the same time, allowing you to gradually roll out a Composable Storefront.

This guide describes how to use Commerce API CDN Zones to route traffic to Managed Runtime.

Only existing customers can access some of the links on this page. Visit Salesforce Commerce Cloud GitHub Repositories and Access for information about how to get access to the Commerce Cloud repositories.

  1. Familiarize yourself with Authorization for Admin APIs
  2. You must have an Account Manager API Client with the scope
  3. You must know the zone ID of the eCDN zone to be used with Managed Runtime. To get this info, use the getZonesInfo endpoint of the CDN Zones API.
  4. Use updateSecuritySettings to enable alwaysUseHttps on the zone. Managed Runtime only supports traffic over HTTPS.
  5. Set your SLAS API Client’s redirect_uri to include the zone.
  6. If you have restricted the set of IPs allowed to access your Managed Runtime environment, add the CloudFlare IPs used by eCDN to the set of allowed IPs.

With the createMrtRules endpoint, you can create rules that route traffic to a Managed Runtime environment:

Let’s examine the data provided in the request body.

The value of mrtHostname is the domain of the Managed Runtime environment for traffic routing. It must refer to a Managed Runtime environment hosted on the domain. If the provided value is used by an existing rule, the request fails.

Managed Runtime is the only supported routing destination.

The value of expressions is an array of Cloudflare rule expressions that controls which requests are routed to Managed Runtime. For most implementations, a single routing expression is sufficient.

In addition to the provided expressions, the following default routing rules are used:

Routing changes are applied immediately, and navigating to a URL that matches an expression returns content retrieved from Managed Runtime.

Expressions are validated against the following criteria:

  • must occur exactly one time and must be followed by the eq operator. The value must match the zone.
  • The following fields are supported:
    • http.request.uri.path
    • http.request.uri
    • http.cookie
  • The maximum length of an expression is 3072 characters.
  • A maximum of 100 expressions can be associated with a zone.

As you continue your phased rollout, you can route more requests to Managed Runtime.

To modify a routing expression, use getMrtRule to get the IDs of the ruleset and rule associated with the expression you want to update:

Next, use updateMrtRule to update the expression:

To disable routing use getMrtRule to get ruleset ID:

Then, use deleteMrtRuleset to remove Managed Runtime routing for that ruleset:

When you complete your phased rollout or if you are launching a new site, you can choose to route all traffic for a zone to Managed Runtime using a single expression:

On environments where eCDN is not available, use the composable-hybrid-dev-server to simulate eCDN routing.

Though createMrtRules allows the creation of rules that route traffic from a single hostname to multiple Managed Runtime environments, this use case is not currently supported.