Rules determine how requests for a specific environment will be processed.
Common Uses:
- Define when requests will be prefetched.
- Override or define a custom cache policy.
- Secure or deny requests for sensitive content.
- Redirect requests.
- Store custom log data.
Quick Start
Set up your rules through the following steps:
- Identify the environment (e.g.,
production
) that will be configured. - Define one or more rule(s) for that environment. Each rule should contain at least one feature.
- Apply your rules to that environment by deploying your changes.
Rules and CDN-as-Code
There are two workflows for defining your CDN configuration:
- Generate and deploy rules through the Edgio Console.
- Define a CDN-as-Code configuration and then deploy it through the Edgio CLI.
Deploying to an environment always overrides the previous configuration. However, if you use a different workflow, you may not be aware of how a deployment will override your current configuration.
For example, if you deploy rules to an environment and a teammate deploys a CDN-as-code configuration at a later date, then your teammate may not be aware of the configuration defined within your rules.
There are benefits and disadvantages to each approach. For example, some teams may prefer the straightforward approach of setting up rules, while other teams may prefer writing code. Another important factor is that the integration of a JavaScript framework through Edgio Sites requires the CDN-as-code approach.
Complex CDN-as-code configurations are displayed in JSON format instead of being displayed as rules.
Rules
A rule consists of a set of IF, ELSE, and ELSE IF statements that define the logic through which requests are identified and processed.
Each statement may contain:
-
A set of match conditions that define the criteria used to identify requests.For example, you may identify requests by URL path, request headers, or geolocation.
-
A set of features that define how the CDN will process requests identified by its conditional expression.For example, you may define a caching policy, set response headers, or redirect requests.
Each of these components are identified in the following illustration.
For example, the following rule applies a caching policy to all
GET
requests whose relative path starts with /marketing/
.Statements
There are three types of statement:
- IF: By default, adding a match condition or feature creates an IF statement and places the new entry within it. You may then add additional match conditions and features.
- ELSE: Adding
Else
to a rule adds an ELSE statement. This type of statement determines how Edgio will process all requests that do not satisfy at least one IF or ELSE IF statement defined within the same rule. - ELSE IF: Adding a match condition to an ELSE statement converts it into an ELSE IF statement. This type of statement determines how Edgio will process requests that meet the following requirements:
- The request does not satisfy the IF statement or any ELSE IF statements above this statement.
- The request must satisfy all of the match condition(s) defined within this ELSE IF statement.
By default, an IF or ELSE IF statement requires requests to satisfy all match condition(s) defined within that statement.
Nested Rules
A nested rule is a rule that is added to another rule’s IF, ELSE IF, or ELSE statement. Edgio will only check a nested rule’s logic when the following prerequisites are satisfied:
-
The request satisfies the rule’s logic to reach the statement where the rule was nested.For example, if a rule is nested under the second ELSE IF statement, then it must not satisfy the match condition(s) defined under the IF statement or the ELSE IF statement that is listed above this one.Alternatively, if a rule is nested under an ELSE statement, then a request cannot satisfy any other IF or ELSE IF statement in that rule.
-
The request satisfies all of the match condition(s) associated with the IF or ELSE IF statement where the rule was nested. This prerequisite is automatically satisfied for ELSE statements, since they do not have match conditions.
For example, the following illustration demonstrates a nested rule whose logic will only be applied for specific types of images:
Key information:
- You may nest a rule under any statement.
- Add a nested rule by finding the desired statement, clicking
+ Add
, and then selectingAdd Nested Rule
.
Conditions
A condition identifies a set of requests. Setting up a condition requires:
-
Selecting the type of condition.For example, you may identify requests by HTTP method, path, or request headers.
-
Defining how a request will be compared against a value or state. In some cases, this involves selecting a comparison operator and defining the value that will be compared against the request.
Example:
Identify all
GET
requests through the following condition:- Type of condition (aka variable): Method
- Operator: Equals
- Match Value: GET
Learn more about types of conditions and operators.
Multiple Conditions
By default, an IF or ELSE IF statement requires requests to satisfy all match condition(s) defined within that statement. This is indicated by an
and
label. However, you may modify an IF or ELSE IF statement to only require a single condition by toggling the and
label to or
.To toggle matching logic
-
Create a rule with multiple condition(s).
-
From the desired IF or ELSE IF statement, click on the
and
label that appears directly to left of a match condition. -
When prompted, click Change operators to only require a single condition before matching a request for this IF or ELSE IF statement.
Switch it back to requiring all conditions by clicking on the
or
label and then confirming this change by clicking Change operators.Your changes will not take effect until they are deployed.
Features
A feature determines how requests will be processed. They are categorized as follows:
- Access: Controls access to content.
- Caching: Customizes when and how content is cached.
- Client: Controls how the client communicates with our CDN.
- Comment: Adds a note or metadata to your configuration. This feature is solely informational and does not affect your configuration.
- Headers: Adds, modifies, or deletes headers from the request or response.
- Logs: Customizes how log data is stored.
- Origin: Controls how the CDN communicates with an origin server.
- Response: Customizes the response sent to the client and determines whether we will allow prefetching instructions to be sent to the client.
- Set Variables: Assigns a value to one or more user-defined variable(s) that are passed to your bespoke traffic processing solution.
- URL: Redirects or rewrites requests to a different URL.
Rule Precedence
You may create multiple rules. The use of multiple rules facilitates:
- The setup of a default configuration that will be applied to all requests.
- The creation of rules that specialize according to request type or behavior.
- Additional control over how requests for content are handled.
Rules are typically processed in the order that they are listed. If a request satisfies the criteria for multiple rules, then all of the features associated with those features will be applied to the request. This could lead to a situation where conflicting actions will take place. In such a case, the last action to take place will take precedence over previous actions. Therefore, it is recommended to place rules that should take precedence as close to the bottom of the list as possible.
Move a rule by dragging the rule’s icon to the desired position.
A good rule of thumb when determining where a rule should be positioned is to order rules according to the level of detail in the criteria. Rules with general criteria should be placed closer to the top of the list, while more detailed criteria should be placed closer to the bottom. This type of configuration allows catch-all rules to assign default handling behavior for your assets without interfering with the manner in which specific types of assets are handled.
Exceptions to Rule Precedence
The following cases are exceptions to the order-based rule precedence stated above:
-
Identical Matching Criteria: If multiple rules share the same matching criteria, then the actions associated with those rules will take place at the same time. Thus, a rule at the bottom could be combined with a rule at the top of the list. This type of situation would prevent the rule at the bottom from taking precedence over other rules.
-
URL Rewrite Precedence: The URL Rewrite feature takes precedence when multiple features will be applied to a request. This occurs regardless of rule order.Example:In this sample scenario, a policy contains two rules. The first rule applies the URL Redirect feature, while the second one applies the URL Rewrite feature. If a request satisfies both rules, then the URL Rewrite feature will always be applied to a request before the URL Redirect feature.
-
Token Auth Precedence: The Token Auth feature takes precedence over most features with the exception of the URL Rewrite feature. This occurs regardless of rule order.
Fine-Tuning Your Rules
If the response provided by Edgio does not match your expectations, you can check the x-edg-mr response header to find out which rules were applied to a request. This response header identifies each rule that was applied to a request by its number. Display rule numbers by clicking Show Rule Numbers.
For example, the following value indicates that the request matched both the first rule (i.e.,
0
) and the second rule (i.e., 1
) within deployment version #16.x-edg-mr: 16:0;16:1;
You can now use this information to adjust your rules. For example, you may adjust the second rule to exclude this type of request or modify another rule to match this type of request.
Rule Precedence Scenario
This scenario assumes that the following three rules have been created:
Order | Purpose | Description |
---|---|---|
1 | Assign a default cache policy for all requests. | Placing this rule at the top of the list ensures that this cache policy is assigned by default to all requests. |
2 | Define an alternative cache policy based on origin type. | The rule’s position allows it to override the default behavior defined in the first rule for requests to a specific origin. |
3 | Deny access based on the requester’s location. | This rule denies access for requests that originate from a specific location. Although this rule does not contradict the above two rules, segregating these instructions improves readability and facilitates rule management. |
Rule order can drastically affect how requests are handled. In the above example, moving the default cache policy rule below the other rules will nullify the cache policy defined by origin type.
Managing Rules
You may create, modify, and delete rules.
Key information:
-
You may make changes without affecting an environment’s traffic. This allows you to collaborate with other teammates when setting up rules and to stage changes until they are needed.For example, a sales event may require URL redirects or a different caching policy than standard site traffic. You can stage these changes until they are needed for the sales event.
-
Apply your changes to the current environment by clicking Deploy Changes.
-
Add a comment or a note to a rule by clicking Add Comments and then typing the desired message. Comments or notes are informational and do not affect your configuration.
-
An alternative method for setting up your configuration is CDN-as-code. CDN-as-code is a developer-oriented solution that provides more flexibility during CDN setup. You may create a base CDN-as-code configuration by setting up your rules through the Edgio Console, exporting them as EdgeJS code, and then pasting that code into your
routes.[js|ts]
file.The Rules page will display a complex CDN-as-code configuration in JSON format. You may modify the JSON directly within the Rules page or yourroutes.[js|ts]
file.
To set up rules
-
Load the Rules page.
- From the Edgio Console, select the desired property.
- From the left-hand pane, select the desired environment from under the Environments section.
- From the left-hand pane, select Rules.
-
Add a rule by clicking + Add Rule.
-
Add a condition that defines the set of requests for which this rule will be applied. Repeat this step as needed.
- Click + Add and then select Add Condition.
- From the Variable option, select the method by which requests will be identified.
- From the Operator option, define the relationship between the variable selected in the previous step and the value that will be defined in the next step.
- In the Value option, define a value that will be compared against for each request.
- Click Add Condition.
-
Add a feature that determines how the requests defined in the previous step will be processed. Repeat this step as needed.
-
Click + Add and then select Add Feature.
-
From the Feature option, select the desired feature.Features are listed by category. If you already know the name of the desired feature, type any part of its name to filter the list.
-
Configure the selected feature.
-
Click Add Feature.
-
-
Optional. Add an ELSE or ELSE IF statement to define an alternate set of logic for identifying and processing requests.
- Click + Add and then select Add Else. An ELSE statement will appear.
- Convert this ELSE statement to an ELSE IF statement by adding one or more match condition(s).
-
Add more rules as needed by repeating steps 2 - 5.
-
Review your rules to verify how requests will be handled and the order in which rules will be applied to requests.Move a rule by dragging the rule’s icon to the desired position.
-
Click Deploy Changes.
To delete a rule
- Load the Rules page.
- From the Edgio Console, select the desired property.
- From the left-hand pane, select the desired environment from under the Environments section.
- From the left-hand pane, select Rules.
- Click the icon next to the desired rule.
- Confirm the deletion by clicking Delete Rules.
- Apply your changes to this environment by clicking Deploy Changes.
- Load the Rules page.
- From the Edgio Console, select the desired property.
- From the left-hand pane, select the desired environment from under the Environments section.
- From the left-hand pane, select Rules.
- Click Export and then select EdgeJS to display your rules as a CDN-as-code (EdgeJS) configuration.
- Copy the code by clicking the icon.
- Optional. Paste your code into your
routes.[js|ts]
.
Deploying your CDN-as-code configuration through the Edgio CLI will overwrite your rules. Likewise, deploying rule changes from the Edgio Console will override a previously deployed CDN-as-code configuration.