Skip to content

Commit

Permalink
Merge pull request #821 from clarinette9/develop
Browse files Browse the repository at this point in the history 
update docs: introduction/route.md
  • Loading branch information
@mileszhang2016
mileszhang2016 authored Sep 9, 2021
2 parents 22aaf61 + 6046644 commit e0f460f
Show file tree
Hide file tree
Showing 2 changed files with 77 additions and 81 deletions.
72 changes: 35 additions & 37 deletions docs/en_us/introduction/route.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,15 +3,15 @@
## Overview

- In BFE [forwarding model](./forward_model.md), after "product name" for one request is determined, the destination cluster should be specified.
- A Forwarding Table is provided for each product inside BFE.
- BFE provides a Forwarding Table for each product.
- For each request, the forwarding table for the determined product is searched, and destination cluster is specified.

## Composition of Forwarding Table

A Forwarding Table is composed of two parts:

- **Basic Rule Table**, consists of "Basic Rules". BFE searches "host" and/or "path" conditions to match a Basic Rule.
- **Advanced Rule Table**, consists of "Advanced Rules". It's searched in listed order (from up to down). Various request contents can be used in search to match conditions in advanced rules. A Default Rule should be configured in Advanced Rule Table, as the last resort.
- **Advanced Rule Table**, consists of "Advanced Rules". It's searched in listed order (from up to down). Various request contents (including host, path, header, cookie, method, etc) can be used in search to match conditions in advanced rules. A Default Rule should be configured in Advanced Rule Table, as the last resort.

Basic Rule Table uses tree search and can be searched fast, even with large amount (thousands, for example) of rules configured. Advanced Rule Table has more powerful condition description capability, but its search performance may degrades when number of rules is large ( >100 rules, for example).

Expand All @@ -29,7 +29,7 @@ Basic Rule Table uses tree search and can be searched fast, even with large amou

**Basic Rule Table** consists of several "Basic Rules".

Each Basic Rule includes two conditions: Host and Path.
Each Basic Rule includes one or both of two conditions: Host and Path.

Destination Cluster is specified by a cluster name, or keyword "ADVANCED_MODE" which indicates to continue searching in Advanced Rule Table.

Expand All @@ -44,15 +44,15 @@ For each Basic Rule, at least one of two conditions (Host and Path) should be co
- Use "." to split labels within a host name
- Support "Exact Match", "Wildcard Match", "Any Match"
- Exact Match: An exact hostname (for example "www.test1.com")
- Wildcard Match: A host name with first label set to "\*". The "\*" can only appear once in a hostname and only covers a single label (for example "\*.test1.com"). Incorrect example of host condition descriptions includes "\*est.com" and "\*.\*.com".
- Any Match: A special Wildcard Match. Leaving the Host condition description empty or set to standalone "\*" makes the rule can match any host. (A standalone "\*" here can cover a hostname with multiple labels, which is different from Wildcard Match.)
- Host condition of a Basic Rule supports multiple host condition descriptions, split by a "," (for example: "www.test1.com, \*.example.com").
- Wildcard Match: A host name with first label set to "\*". The "\*" can only appear once in a hostname and only covers a single label (for example "\*.test1.com"). Examples of invalid host condition description include "\*est.com" and "\*.\*.com".
- Any Match: A special Wildcard Match. Standalone "\*" can match any host. (A standalone "\*" here can cover a hostname with multiple labels, which is different from Wildcard Match.)
- Host condition of a Basic Rule supports multiple host condition descriptions (for example: "www.test1.com,","\*.example.com").

**Examples:**

| Host Condition | Host in a request | Match？ |
| -------------- | ------------------ | ----------------------------------------- |
| null or \* | www.test1.com | Match |
| \* | www.test1.com | Match |
| \*.test1.com | host.test1.com | Match |
| \*.test1.com | vip.host.test1.com | No Match, "\*" only covers a single label |
| \*.test1.com | example.com | No Match |
Expand All @@ -61,33 +61,32 @@ For each Basic Rule, at least one of two conditions (Host and Path) should be co
**Path** condition description's syntax is as follow:

- Use "/" to split elements within a path
- Start with "/", except for Any Match.
- Start with "/", except for a standalone "\*".
- Support "Exact Match", "Prefix Match", "Any Match"
- Exact Match: An exact path (for example "/path")
- Prefix Match: A path prefix followed by a "\*" means it's a prefix match. It compares element by element from the left. The "\*" can only appear once, and can covers one or multiple consecutive path elements (for example both "/\*" and "/foo/\*" can match "/foo/bar"). Incorrect examples of path condition descriptions include "/fo\*" and "/\*/\*".
- Any Match: A special prefix match. Leaving the Path condition description empty or set to wildcard "\*" means this rule can match any path.
- Path condition of a Basic Rule supports multiple path condition descriptions, split by a "," (for example: "/foo/bar, /foo/cell/\*").
- Exact Match: An exact path (for example "/foo")
- Prefix Match: A path prefix followed by a "\*" means it's a prefix match. It compares element by element from the left. The "\*" can only appear once, and can covers one or multiple consecutive path elements. A standalone "\*" is also a prefix match. Examples:
- both /\* and /foo/\* can match path /foo/bar
- /foo/* is equivalent to /foo\*
- /foo/b\* can not match /foo/bar
- /\*/\* is not a valid path condition description
- Path condition of a Basic Rule supports multiple path condition descriptions (for example: "/foo/bar", "/foo/cell/\*").

**Examples:**

| Path Condition | Path in the request | Match? |
| -------------- | ------------------- | ------------------------------------------------------------ |
| Empty or \* | Empty | Match |
| Empty or \* | / | Match |
| Empty or \* | /a/b | Match |
| / | Empty | No match |
| / | / | Match |
| / | /a | No match |
| /\* | Empty | No match |
| /\* | / | Match, \* can match null |
| /\* | /a | Match |
| /\* | /a/b | Match, \* covers multiple consecutive path elements |
| /\* | /a/ | Match, ignores trailing slash |
| /a/b/\* | /a/b/c | Match |
| /a/b/\* | /a/b/c/d | Match, \* covers multiple consecutive path elements |
| /a/b/\* | /a/b | Match, ignores trailing slash and \* covers multiple consecutive path elements |
| /a/b/\* | /a/c | No match |
| /a/b/\* | /a/ | No match |
| Path Condition | Path in the request | Match? |
| ------------------------------ | ------------------- | --------------------------------------------------- |
| \* | Any path | Match |
| / | Empty | No match |
| / | /a | No match |
| /\* | Empty | No match |
| /\* | / | Match, \* can match null |
| /\* | /a/ | Match, ignores trailing slash |
| /a/b/\* (equivalent to /a/b\*) | /a/b/c | Match |
| /a/b/\* (equivalent to /a/b\*) | /a/b/c/d | Match, \* covers multiple consecutive path elements |
| /a/b/\* (equivalent to /a/b\*) | /a/b | Match, ignores trailing slash and \* can match null |
| /a/b/\* (equivalent to /a/b\*) | /a/c | No match |
| /a/b/\* (equivalent to /a/b\*) | /a/ | No match |
| /a/b\* | /a/bacon | No match |

### Search in Basic Rule Table

Expand All @@ -99,11 +98,11 @@ Detailed steps of search in Basic Rule Table are described below:
- For rules that match (may be one or multiple rules), search path condition of them;
- If a rule matches the path, the rule is hit;
- If no rule matches path, then search in Basic Rule Table ends and BFE will continue to search in Advanced Rule Table.
2. If no rule matches as Exact Match, search host condition using **Wildcard Match**
2. If no rule matches as host Exact Match, search host condition using **Wildcard Match**
- For rules that match (may be one or multiple rules), search path condition of them;
- If a rule matches the path, the rule is hit;
- If no rule matches path, then search in Basic Rule Table ends and BFE will continue to search in Advanced Rule Table.
3. If no rule matches as Wildcard Match, search host condition using **Any Match**
3. If no rule matches as host Wildcard Match, search host condition using **Any Match**
- For rules that match (may be one or multiple rules), search path condition of them;
- If a rule matches the path, the rule is hit;
- If no rule matches path, then search in Basic Rule Table ends and BFE will continue to search in Advanced Rule Table.
Expand All @@ -113,7 +112,6 @@ Among above steps, when searching path condition in rules that has matches the h

1. Search path condition using **Exact Match**
2. If no rule matches as Exact Match, search path condition using **Prefix Match**. Precedence will be given to the longest matching path. So if more than one rule matches the path in the request, the rule with most matching path elements is hit.
3. If no rule matched as Prefix Match, search path condition using **Any Match**.

### Examples

Expand All @@ -130,7 +128,7 @@ BFE searches host condition first：

1.**Exact Match** for host, no match

2.**Wildcard Match** for host, both Rule2 and Rule3 match host (vip.b.test1.com) of the request
2.**Wildcard Match** for host, both Rule2 and Rule3 match host (vip.b.test1.com) of the request (Notice, Rule1 does not match this host, as wildcard "\*" only covers a single label)

Then BFE searches path condition：

Expand All @@ -149,9 +147,9 @@ Advanced Rule Table consists of one or more "Advanced Rules" which have an order

When searching in Advanced Rule Table, the rules are searched from up to down, in listed order:

- Try to match the condition of the rule with information in the HTTP request. If it matches, the rule is hit.
- Try to match the condition of the rule with information in the HTTP request (such as host，path，query，cookie，method). If it matches, the rule is hit.
- If a rule is hit, the search stops.
- A Default Rule must be configured in the Advanced Rule Table. If no other rules match a request, the Default Rule is hit.
- A Default Rule must be configured in the Advanced Rule Table. If no other rule matches a request, the Default Rule is hit.

## Examples

Expand All @@ -176,7 +174,7 @@ When searching in Advanced Rule Table, the rules are searched from up to down, i

There's no order for Basic Rules. Refer to "Search in Basic Rule Table" above.

For the canary release of cluster Demo-D1 that depends on cookie information, the rule uses ADVANCED_MODE to do further search in Advanced Rule Table for related requests. If canary release is not required, the Destination Cluster of this rule can be set to Demo-D.
As cookie information is need for the canary release of applications on Demo-D, the rule uses ADVANCED_MODE to do further search in Advanced Rule Table for related requests. If canary release is not required, the Destination Cluster of this rule can be set to Demo-D.

- The **Advanced Rule Table** can be configured as below:

Expand Down
Loading

0 comments on commit e0f460f

Please sign in to comment.