The conditional origin feature uses the rules engine to filter user requests by criteria, such as the request header, query string parameter, path, or client IP. Matching requests are routed to a specific origin. You can add multiple configurations to direct requests to different origins under different conditions.
Prerequisites
Before you configure a conditional origin, you must create a rule condition in the rules engine.
Usage notes
Feature conflict: The conditional origin and advanced origin features are mutually exclusive. You can enable only one.
Wildcard support: In the rules engine, the match value for a URI can include the wildcards
*(matches zero or more characters) and?(matches any single character). The advanced origin feature, however, supports only exact path matching and does not support wildcards.Configuration precedence: Requests are matched based on the priority of the associated rule condition, not the order in which the conditional origins are configured. After a request matches a rule, rule evaluation stops.
Rule limit: The number of rule conditions you can reference for conditional origins is limited by the rules engine. For a single domain, the total number of references to rule conditions across all features (including conditional origins, advanced origins, and Referer-based hotlink protection) cannot exceed five. If you exceed this limit in complex multi-origin scenarios, the configuration fails. Plan your rules carefully, or use separate domain names for acceleration if you have many origins.
Considerations for OSS origins
If your origin is an OSS bucket, you must add its address to the Domain Names > Basics > Origin Information section and set the origin type to OSS Domain. This allows CDN to authenticate correctly with OSS.
Multi-OSS origin scenarios: When you configure multiple OSS origins, you must specify an origin Host for each. The value of the origin Host must exactly match the corresponding OSS bucket domain, such as
dev-3mir.oss-cn-guangzhou.aliyuncs.com.If you do not correctly configure the origin Host or rely on the default setting, requests may be routed to the wrong bucket. This can result in a 403 SignatureDoesNotMatch (signature verification failed) or 404 Not Found error. Each conditional origin rule, including both match rules and fallback rules, must be explicitly linked to its corresponding origin and origin Host. When configuring multiple origins, set equal weights for the basic origins and create separate rule conditions for each conditional origin to ensure predictable routing.
Origin type comparison
Both conditional origins and advanced origins can reference rule conditions from the rules engine to create flexible origin pull policies. CDN automatically selects an origin if a request matches a rule condition.
Origin type | Trigger condition |
Conditional origin | The request matches the rule condition referenced by the conditional origin. |
Advanced origin | The request matches the rule condition referenced by the advanced origin. |
Basic origin | The request does not match any conditional or advanced origin rule (fallback rule). |
Procedure
-
Log on to the CDN console.
-
In the left navigation pane, click Domain Names.
-
On the Domain Names page, find the target domain name and click Manage in the Actions column.
In the Origin Information section, click Expand to expand the Conditional Origin settings.
Click Add Conditional Origin.
-
Configure the Rule Condition.
-
To add a new Rule Condition or modify an existing one, click Rules Engine in the Conditional Origin dialog box to open the rules engine. For more information, see rules engine.
If you have an existing rule condition, select it from the Rule Condition drop-down list.
-
In the Origin Address field, enter the address of the origin. Supported origin types include IP address, domain name, OSS, and Function Compute.
Click OK to save the configuration.
Example: Path-based routing to FC and OSS
Advanced origin supports only exact value matching and does not support wildcards or regular expressions. To implement path-based origin routing, you can use conditional origin and the rules engine. By combining conditional origin with the rules engine and URL rewrite, you can route requests for the /api/* path to a Function Compute (FC) origin, while all other requests are routed by default to an OSS origin.
Create a rules engine rule
Navigate to Domain Names, find the target domain, and go to the Rules Engine page.
Click Add Rule and configure the rule condition as described in the following table:
Parameter
Value
Rule Name
A custom name, such as
api-to-fc, for easy identification later.Match type
URI
Match operator
Include Any
Match value
*/api/*Case sensitive
Case-insensitive (default)
ImportantDo not add a hostname condition. The hostname condition matches the request domain, not the origin. Adding a hostname condition may prevent the rule from matching the path after a URL rewrite.
Click Submit to save the rule.
Configure the conditional origin
From the navigation pane on the left, go to Domain Names > Basics. In the Origin Information section, expand the Conditional Origin settings.
Click Add Conditional Origin and configure the parameters in the dialog box as described in the following table:
Parameter
Value
Rule Condition
In the drop-down list, select the rule created in Step 1 (such as
api-to-fc).Origin Address
Enter the address of your Function Compute (FC) origin.
Click OK to save the configuration.
Configure the origin Host
In the origin configuration, set the origin Host for this rule to the FC domain name to ensure that requests to the origin use the correct Host header.
Configure URL rewrite (optional)
If you need to rewrite the /api/ path to the /print/api/ path on Function Compute (FC), you must use the URL rewrite feature of CDN to configure this:
Configure a URL rewrite rule in the rules engine to rewrite
/api/to/print/api/.Ensure that the URI matching condition for the rules engine from Step 1 covers the rewritten path (for example,
*/api/*or a specific match such as/print/api/*).
After the preceding configuration is complete, frontend requests to /api/* are routed to the FC service, while other requests perform an origin pull to OSS by default.
Example: Referer-based routing
The following example shows how to route requests to different origins based on the Referer header. This is useful for hotlink protection or for controlling access based on the source of the request.
Create a Referer rule condition
Log on to the CDN console, select the target domain, and navigate to Domain Names > Rules Engine.
Click Add Rule and configure the parameters as described in the following table:
Parameter
Value
Rule Name
referer-routing(A custom name for easy identification)Match type
Referer
Match operator
Include Any
Match value
example.comThe referer domain. You can configure multiple referer domains.Case sensitive
Case-insensitive
Click Submit to save the rule.
Configure the conditional origin
In the navigation pane on the left of the domain management page, go to the Basics tab. In the Origin Information section, expand the Conditional Origin settings.
Click Add Conditional Origin and configure the parameters in the dialog box as described in the following table:
Parameter
Value
Rule Condition
In the drop-down list, select
referer-routing.Origin Address
Enter the address of the origin for this Referer source.
Click OK to save the configuration.
FAQ
Troubleshooting conditional origin routing
Follow these steps to troubleshoot the issue:
Check the rule matching conditions: Verify that request parameters, such as the URI and Header, match the condition rules that you configured. Note that URI path matching requires wildcards, such as
/api/*. The wildcard*matches zero or more characters, and?matches any single character. If a match value does not contain a wildcard, the match may fail.Check the origin Host configuration: If your origin is an OSS bucket, confirm that you have specified an origin Host for each conditional origin and that its value exactly matches the corresponding OSS bucket domain. An incorrect origin Host configuration will cause OSS signature authentication to fail, resulting in a 403 error.
Check the origin address: Ensure that the origin address is correct and that the origin service is running properly. You can verify the origin's availability by directly accessing the OSS bucket domain.
Check the cache status: After you modify the configuration, CDN edge nodes may still serve content cached under the old configuration. Perform a cache refresh to ensure the new configuration takes effect immediately.
Check OSS permissions: If an origin pull from an OSS bucket returns a 403 error with the message "You have no right to access this object," check the Access Control List (ACL) permissions of the OSS bucket. If the bucket is private, you must either set its permissions to public-read or configure authentication for the origin pull in the CDN console.
Check the rule condition reference count: Confirm that the total number of rule condition references for the domain does not exceed the limit of five. If the limit is exceeded, new configurations will not take effect.
Routing traffic by region
You can use conditional origins with the rules engine to route traffic by geography. Configure it as follows:
Create a geographic rule condition: Log on to the CDN console, select the target domain, and navigate to Domain Names > Rules Engine. Click Add Rule.
Configure the Chinese mainland rule: Set Match Type to User Geographic Location, set the Match Value to Chinese mainland, and set the logical relationship to OR. Save the rule.
Configure the rule for regions outside the Chinese mainland: Set Match Type to User Geographic Location, and set the Match Value to Exclude Chinese mainland. Save the rule.
Configure conditional origins: In the Origin Information section, associate each rule with its corresponding origin:
Associate the Chinese mainland rule with a domestic origin, such as a local OSS bucket or server.
Associate the rule for outside the Chinese mainland with an overseas origin, such as an overseas OSS bucket or server.
Configure the origin Host: For each origin, specify an origin Host to ensure that the Host value matches the respective origin domain.
Configuration propagation and cache refresh
Time to take effect: After you modify a conditional origin configuration, it typically takes 5 to 10 minutes to propagate globally. During this time, the configuration is gradually distributed to all edge nodes, and both old and new configurations may coexist.
Cache refresh recommendation:
After the configuration takes effect, if your CDN edge nodes have cached content that was retrieved under the old configuration, perform a cache refresh. This ensures that users receive the latest content.
You can manually refresh the cache in the CDN console, or call the
RefreshObjectCachesAPI to refresh objects in batches.If the configuration change only affects the origin pull rule and not the cached content itself, a cache refresh is typically not necessary because origin pull rules are evaluated in real time by CDN edge nodes.
For users who are configuring a conditional origin for the first time, we recommend that you use the curl -I command to test the origin pull results for different paths after the configuration is complete to confirm that the configuration has taken effect.
Authentication for private OSS origins
When your OSS bucket is private, CDN requires proper authentication to retrieve resources. You can grant CDN access to your private OSS bucket by using a Service-Linked Role. After you grant the authorization, CDN automatically includes the authentication information when performing an origin pull from the private bucket, which requires no manual configuration.