The conditional origin feature uses the rules engine to filter user requests based on specified criteria, such as request headers, query string parameters, paths, or client IP addresses. CDN routes requests that match the criteria to a specific origin address. You can add multiple configurations to direct requests to different origins based on 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 URI match value supports the wildcard
*(matches any number of characters) and?(matches any single character). Path matching in the advanced origin feature supports only exact values, not wildcards.Rule priority and matching order: Conditional origins are evaluated based on the priority of the associated Rule Condition in the rules engine, not the order of the conditional origin configurations. When a request matches a rule, evaluation stops. Rule priority in the rules engine is determined by creation order: rules created earlier have higher priority. To adjust the matching priority, you must delete and recreate the rules in the desired order.
Multi-path configuration tip: When creating rules to "include" or "exclude" a path, you can enter multiple paths (in multiple lines or as multiple values) in the match value field of a single rule to simplify your configuration.
Rule limit: The number of Rule Conditions that a conditional origin can reference is subject to a global limit in the rules engine. For a single domain, the total number of references to Rule Conditions across all features, including conditional origin, advanced origin, and Referer-based hotlink protection, cannot exceed five. In complex multi-origin scenarios, exceeding this limit causes the configuration to fail. We recommend that you plan your rule usage carefully or use separate domains for acceleration if you have many origins.
Considerations for OSS origins
If an origin is an OSS bucket, you must add its address under Domain Names > Basics > Origin Information and set the origin type to OSS Domain. This enables CDN to authenticate correctly with OSS.
Multi-OSS origin scenarios: When you configure multiple OSS origins, you must configure a specific origin Host for each one. The Host value must exactly match the corresponding OSS bucket domain, such as
dev-3mir.oss-cn-guangzhou.aliyuncs.com.If the origin Host is not configured correctly or if you rely on the default origin Host, requests may be routed to the wrong bucket. This can cause 403 SignatureDoesNotMatch or 404 Not Found errors. You must explicitly bind every conditional origin rule, including match rules and fallback rules, to its corresponding origin and origin Host. When you configure multiple origins, we recommend setting equal weights for the basic origins and creating 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 routing 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 origin or advanced origin rule (default fallback). |
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 Conditional Origin next to Expand.
Click Add Conditional Origin.
Set the Rule Condition.
If this is your first time adding a configuration or you need to modify an existing Rule Condition, click Conditional Origin in the Rules Engine dialog box. This opens the rules engine where you can add or modify configurations. 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 origin address. The origin address can be an IP address, a domain name, an OSS bucket, or a Function Compute (FC) endpoint.
Click OK to complete the configuration.
Example: Routing /api/* requests to FC
The advanced origin feature supports only exact value matching and does not support wildcards or regular expressions. To implement path-based origin routing, use conditional origins with the rules engine. By combining the conditional origin feature 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 rule in the rules engine
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
Enter a custom name for easy identification, such as
api-to-fc.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
In the navigation pane on the left, go to Domain Names > Basics. In the Origin Information section, click the expand icon next to Conditional Origin.
Click Add Conditional Origin and configure the parameters in the dialog box as described in the following table:
Parameter
Value
Rule Condition
From the drop-down list, select the rule that you 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 a URL rewrite (optional)
If you need to rewrite the /api/ path to the /print/api/ path on your FC origin, you must also use the URL rewrite feature in CDN:
In the rules engine, configure a URL rewrite rule to rewrite
/api/to/print/api/.Ensure that the URI matching condition in the rules engine from Step 1 covers the rewritten path. For example, use
*/api/*or match the specific path/print/api/*.
After you complete these configurations, CDN routes frontend requests to /api/* to the FC service, while routing other requests to the OSS origin 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
Enter a descriptive name, such as
referer-routing.Match type
Referer
Match operator
Include Any
Match value
example.com. This value specifies the referer domain. You can add multiple 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, click the expand icon next to Conditional Origin.
Click Add Conditional Origin and configure the parameters in the dialog box as described in the following table:
Parameter
Value
Rule Condition
From 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
Why are requests routed incorrectly or failing?
Check the following items:
Check the rule matching conditions: Verify that request parameters, such as the URI and headers, match the rules 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 causes OSS signature authentication to fail, which results 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 that was cached under the old configuration. Perform a cache refresh to ensure that the new configuration takes effect immediately. For cookie-based conditional origin rules, the rule will not be triggered if the test account is not logged in (the request does not carry the cookie) or the cache is not cleared. When you test, we recommend that you use the
curl -v -H "Cookie: key=value"command to simulate a request with a cookie to verify that the rule matches correctly.Check OSS permissions: If an origin request to 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 set its permissions to public-read or configure authentication for the origin request in CDN.
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 do not take effect.
Geo-based routing
You can use conditional origins with the rules engine to route traffic by geography. Configure the settings as follows:
Create a geographic Rule Condition: Log on to the CDN console, select the target domain, navigate to Domain Names > Rules Engine, and click Add Rule.
Configure the Chinese mainland rule: Set Match type to User Geographic Location, set Match value to Chinese mainland, set the logical relationship to OR, and save the rule.
Configure the overseas rule (fallback): Set Match type to User Geographic Location, set Match value to regions outside the Chinese mainland, and save the rule.
Configure conditional origins: In the Origin Information section, associate each of the two rules with its corresponding origin:
Associate the Chinese mainland rule with a domestic origin, such as a domestic OSS bucket or server.
Associate the regions outside the Chinese mainland (overseas) rule with an overseas origin, such as an overseas OSS bucket or server.
Configure the origin Host: For each origin, configure a specific origin Host to ensure that the Host value matches the respective origin domain.
Cross-border optimization recommendations
If users in regions outside the Chinese mainland experience high latency or unstable connections when they access origins in the Chinese mainland, we recommend using OSS Transfer Acceleration to optimize the cross-border origin connection:
The conditional origin for users in the Chinese mainland makes a request to a regular public OSS domain, such as
bucket.oss-cn-hangzhou.aliyuncs.com.The conditional origin for users in regions outside the Chinese mainland makes a request to an OSS Transfer Acceleration domain, such as
bucket.oss-accelerate.aliyuncs.com.
OSS Transfer Acceleration uses globally distributed acceleration nodes to optimize cross-border connections and can effectively reduce origin request latency. For more information about OSS Transfer Acceleration, see Access OSS by using Transfer Acceleration.
Propagation time and cache refresh
Propagation time: After you modify a conditional origin configuration, the change typically takes 5 to 10 minutes to propagate globally. The CDN configuration is gradually deployed to all edge nodes. During this period, both old and new configurations may coexist.
Cache refresh recommendations:
After the configuration takes effect, if CDN edge nodes have cached content that was retrieved under the old configuration, perform a cache refresh to ensure that users can access 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 affects only the origin request rule and not the cached content itself, a cache refresh is typically not necessary because CDN edge nodes evaluate origin request rules in real time.
If you are configuring a conditional origin for the first time, we recommend that you use the curl -I command to test the origin request 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. Grant CDN access to your private OSS bucket by using a Service-Linked Role. For detailed instructions, see Enable CDN to access a private OSS bucket. CDN uses the Service-Linked Role to obtain access permissions for OSS. After you grant the authorization, CDN automatically includes the authentication information when it retrieves content from the private bucket, requiring no manual configuration.
Troubleshooting 502 errors with GA
If you encounter 502 errors when using CDN with Global Accelerator (GA) and conditional origins, check the following:
Check the origin Host configuration: When you use conditional origins, you must delete the default origin Host and configure a specific origin Host instead. We recommend that you configure two rules to handle traffic from the Chinese mainland and regions outside the Chinese mainland separately: one rule that matches traffic from the Chinese mainland, with the origin set to the IP address of a server in the Chinese mainland and the specific origin Host set to the CDN accelerated domain, and another rule that matches traffic from regions outside the Chinese mainland, with the origin set to the GA origin domain and the specific origin Host set to the GA origin domain.
Check protocol and port consistency: Ensure that the GA listener port matches the CDN origin request port. If GA uses HTTPS port 443, we recommend that CDN also retrieve content from GA through port 443. If the origin is not configured with an HTTPS certificate, you can create a listener on HTTP port 80 in GA and configure CDN to retrieve content from GA through HTTP port 80. This avoids 502 errors caused by protocol or port mismatches.
Alternative solution: If the preceding configuration is too complex, consider migrating to Edge Security Acceleration (ESA). ESA supports more flexible conditional origin configurations and independent origin request port configurations.
Impact on hotlink protection
No. Hotlink protection policies, including Referer-based hotlink protection and URL authentication, apply globally to the entire CDN domain and are unaffected by conditional origin configurations. After you configure conditional origins, the hotlink protection feature continues to work as intended based on its existing policies.
Origin server path configuration
No. You only need to configure the domain name on the origin and do not need to add URL path rules. CDN determines the origin for the request based on the full URL of the request:
If a request satisfies a conditional origin rule, the request is routed to the origin that is associated with that rule.
If the request does not satisfy any conditional origin rule and a basic origin exists, the request is routed to the basic origin.
You only need to add the corresponding origin domain in the CDN console and configure a specific origin Host, which is the origin domain, for each conditional origin. You do not need to configure additional URI matching rules on the origin.