CDN Routing Rules for Hybrid Implementations

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) is available for Primary Instance Group (PIG) environments, such as production or staging, and for on-demand sandbox (ODS) instances. eCDN can route traffic to both SFRA and Managed Runtime (MRT) at the same time, allowing you to gradually roll out a Composable Storefront. Local development servers don’t have an eCDN; in that case, use the hybrid proxy to route traffic to SFRA.

For local development servers, which don’t have an eCDN, develop and test hybrid shopper apps that use PWA Kit and SFRA or SiteGenesis by enabling the hybrid proxy feature in the pwa-kit-runtime package in PWA Kit v3.14.0 and later. On ODS instances, use eCDN instead of the hybrid proxy.

For more information, see Configure a Hybrid Storefront with Hybrid Auth (PWA Kit).

For PIG instances, an eCDN zone can route traffic to both SFRA and MRT at the same time, allowing you to gradually roll out a Composable Storefront.

This diagram shows the sequence of requests and responses when an eCDN routes an incoming page request for a hybrid app for a PIG instance. If the request matches MRT rules, it is forwarded to MRT. Otherwise, if the request doesn’t match MRT rules, it is sent to the B2C Commerce instance, and then a response is returned.

You can configure hybrid routing rules in two ways. We recommend using the Business Manager eCDN UI for most implementations. Use the CDN Zones API when you need to automate or script rule management.

The embedded CDN (eCDN) UI in Business Manager is the recommended way to add and manage hybrid routing rules. It lets you configure rules without writing API payloads.

1. In Business Manager, go to Administration > Sites > Embedded CDN Settings.

2. Locate the zone that contains your storefront hostname (typically the default zone).

3. Click the caret on the right side of the zone title, then select Configure Routing Rules.

   

4. Locate the routing rule for your hostname and click Edit.

5. Confirm that the Hostnames and MRT Origin fields are prefilled and match your setup. Find your MRT Origin (the Managed Runtime environment domain) in Environment Settings in Runtime Admin.

6. In Rule expression, enter the Cloudflare expression that matches the routes you want to serve from Managed Runtime.

7. Click Save.

For architecture-specific, copy-ready rule expressions, see:

• Storefront Next: Set Up Hybrid Storefront with On-Demand Sandbox (ODS) Instances Using eCDN and Hybrid Storefront Routing Matrix.
• PWA Kit / Composable Storefront: Configure a Hybrid Storefront with Hybrid Auth (PWA Kit).

If you need to automate or script routing-rule management, use the Commerce API CDN Zones API to route traffic to Managed Runtime.

Before running the commands in this section, replace any placeholders with actual values. Placeholders are formatted like this: $PLACEHOLDER. Throughout this section, we use an example storefront with the production URL https://www.example.com.

1. Familiarize yourself with Authorization for Admin APIs
2. You must have an Account Manager API Client with the scope sfcc.cdn-zones.rw.
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, 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 mobify-storefront.com or exp-delivery.com domain. If the provided value is used by an existing rule, the request fails.

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.

• The following routing scenarios are supported:

  • A single hostname mapped to a single MRT environment:

    • For example, http.host eq \"www.example.com\" → example-production.mobify-storefront.com

  • Multiple hostnames mapped to a single MRT environment:

    • For example, http.host in {\"www.example.com\" \"prod.example.com\" \"us.example.com\"}→ example-production.mobify-storefront.com

• The following routing scenario is currently not supported:

  • A single hostname mapped to multiple MRT environments based on different paths

Expressions are validated against the following criteria:

• http.host must occur exactly once and must be followed by either the eq or in operator. See above for usage examples.
• The hostname(s) must match the zone. Or in other words, the eCDN zone must have a valid certificate that covers the provided hostname(s).
• The following fields are supported:
  • http.host
  • http.request.uri.path
  • http.request.uri
  • http.cookie
• The maximum length of an expression is 3072 characters.
• A maximum of 300 expressions can be associated with a zone.

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

To modify a routing expression, use getMrtRules 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 add more routing rules to an existing Managed Runtime environment, use updateMrtRuleset and provide the mrtHostname and additional routing expressions:

To add routing rules for a new Managed Runtime environment, use the createMrtRules endpoint and provide a new mrtHostname value:

To update existing rules to route to a different Managed Runtime environment, use updateMrtRuleset and provide the oldMrtHostname and the (new) mrtHostname that you want to route to:

If you’re switching to a third-party CDN or you no longer want to route a particular path from eCDN to MRT, disable routing.

To disable routing, use getMrtRules to get the IDs of the configuration that you want to delete:

Then, to remove the Managed Runtime routing rule, use deleteMrtRule and pass in the applicable IDs returned by getMrtRules:

If you want to remove all Managed Runtime routing rules, use deleteMrtRuleset:

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

• Hybrid Implementation Guidance
• Hybrid Authentication