diff --git a/docs/en_us/introduction/route.md b/docs/en_us/introduction/route.md index f82f5d53d..e6726aeca 100644 --- a/docs/en_us/introduction/route.md +++ b/docs/en_us/introduction/route.md @@ -3,7 +3,7 @@ ## 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 @@ -11,7 +11,7 @@ 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). @@ -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. @@ -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 | @@ -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 @@ -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. @@ -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 @@ -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: @@ -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 @@ -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: diff --git a/docs/zh_cn/introduction/route.md b/docs/zh_cn/introduction/route.md index e5603026c..83804336d 100644 --- a/docs/zh_cn/introduction/route.md +++ b/docs/zh_cn/introduction/route.md @@ -4,7 +4,7 @@ ## 概述 - 在BFE的[接入转发流程](./forward_model.md)中,在确定产品线后,要进一步确定处理该请求的目标集群 -- 在BFE内,为每个产品线维护一张“转发表” +- BFE为每个产品线维护一张“转发表” - 对每个属于该产品线的请求,查询转发表,获得目标集群 @@ -12,8 +12,8 @@ 转发表包括2部分: -- **基础规则表**:可使用域名(Host)和路径(Path)作为匹配条件。支持最长匹配原则。 -- **高级规则表**:支持使用请求中的多种信息做匹配。支持顺序匹配。在高级规则表中可以设置默认规则。 +- **基础规则表**:由基础规则组成。使用域名(Host)和路径(Path)作为匹配条件,基础规则表中的规则按最长匹配原则进行匹配。 +- **高级规则表**:由高级规则组成。使用请求中的多种信息(如host、path、header、cookie、method等)进行匹配,高级规则表中的规则按先后顺序进行顺序匹配。在高级规则表中可以设置默认规则。 基础规则表使用树形查找,匹配速度快,可以支持较大数量(几千甚至上万)转发规则的快速查找;高级规则表支持更强大的条件描述能力,但是在规则数量较多(超过100条)时会有明显的性能下降。 @@ -21,7 +21,7 @@ BFE会按照基础规则表、高级规则表的顺序来查找,以确定目标集群。 -在基础规则表中,也可以将某条规则的目标集群设置为“ADVANCED_MODE”(高级模式)。如果在基础规则表中匹配到这条规则,则转至高级规则表进一步匹配。 +在基础规则表中,也可以将某条规则的目标集群设置为“ADVANCED_MODE”(高级模式),命中此规则的请求将转至高级规则表进一步匹配。 详细的匹配顺序见下图。 @@ -38,28 +38,28 @@ BFE会按照基础规则表、高级规则表的顺序来查找,以确定目 - 基础规则的匹配条件包括域名(host)和路径(path)两个部分。 - 目的集群通过集群名称来指定,也可以设置为“ADVANCED_MODE”转至高级规则表继续匹配。 -多条基础规则之间没有前后顺序关系,而是基于精确优先的原则。详细的匹配方式见后面的“基础规则匹配顺序”。 +基础规则没有前后顺序关系,而是基于精确优先、最长匹配的原则。详细的匹配方式见后面的“基础规则匹配顺序”。 ### 基础规则匹配条件 -一条基础规则的host条件和path条件,需要至少有一个不为空值。 +一条基础规则可以指定host条件或path条件,或者同时指定host条件和path条件。 host条件的描述语法遵循以下规则: - 以"."作为域名标签元素的分割符(域名标签元素指的是由 "."分隔的host中的标签。) -- 支持“精确匹配”、“通配符匹配”、“任意匹配” +- 支持“精确匹配”、“通配符匹配”和“任意匹配” - 精确匹配:完整的域名,如:www.test1.com - - 通配符匹配:第一个域名标签元素为通配符"\*"表示这个描述为通配符匹配。 "\*"仅能出现一次,且仅可以表示一个域名标签元素,例如\*.test.com。而\*est.com和\*.\*.com均不符合语法 - - 任意匹配:一种特殊的通配符匹配,可以通过空值或者填写通配符"\*"来表示匹配任意的host值(与通配符匹配不同,单独的\*作为任意匹配,可以匹配包含多个域名标签元素的host) -- 一条规则的host条件,支持逗号分割的多个host描述,如:www.test1.com, \*.example.com + - 通配符匹配:第一个域名标签元素为通配符"\*"表示这个描述为通配符匹配。 "\*"仅能出现一次,且仅可以表示一个域名标签元素,例如\*.test.com。而\*est.com和\*.\*.com均不符合语法。 + - 任意匹配:一种特殊的通配符匹配,可以填写单独的通配符"\*"来表示匹配任意的host值(与通配符匹配不同,任意匹配的\*可以匹配包含多个域名标签元素的host) +- 一条规则的host条件,支持多个host描述,如:"www.test1.com", "\*.example.com" 示例: -| host条件 | 请求的host | 是否匹配? | +| host描述 | 请求的host | 是否匹配? | | ----------- | -------------------------------------- | ------------------------------- | -| 空值 或者 \* | www.test1.com | 匹配 | +| \* | www.test1.com | 匹配 | | \*.test1.com | host.test1.com | 匹配 | -| \*.test1.com | vip.host.test1.com | 不匹配,\*只匹配一个域名标签元素 | +| \*.test1.com | vip.host.test1.com | 不匹配,\* 只匹配一个域名标签元素 | | \*.test1.com | example.com | 不匹配 | | \*.test1.com | test1.com | 不匹配 | @@ -67,57 +67,55 @@ path条件的描述语法遵循以下规则: - 以"/"作为路径元素的分割符(路径元素指的是由 "/" 分隔符分隔的路径中的标签。) - 除了任意匹配,均以"/"开始 -- 支持“精确匹配”、“前缀匹配”、“任意匹配” +- 支持“精确匹配”和“前缀匹配” - 精确匹配:完整的路径,如/path - - 前缀匹配:在路径前缀后面使用"\*"来表示这个描述为前缀匹配,即从左开始对path中的路径元素逐个匹配。 "\*"仅能出现一次,且可以表示一个或多个连续的路径元素,如/foo/bar这个path,被 /\* 和 /foo/\* 均能匹配到。而/fo\*和/\*/\*均不符合path描述的语法。 - - 任意匹配:一种特殊的前缀匹配,可以通过空值或者填写通配符\*来表示匹配任意的path值 -- 一条规则的path条件,支持逗号分割的多个path描述,如:/foo/bar, /foo/cell/\* + - 前缀匹配:在路径前缀后面使用"\*"来表示这个描述为前缀匹配,即从左开始对path中的路径元素逐个匹配。 "\*"仅能出现一次,且可以表示一个或多个连续的路径元素。前缀匹配的描述也可以是一个单独的"\*"。举例如下: + - /foo/bar 这个path,条件 /\* 和 /foo/\* 均能匹配到; + - /foo/\* 和 /foo\* 是等价的; + - /foo/bar 这个path,不能被条件 /foo/b\* 匹配到; + - /\*/\* 不符合path描述的语法 +- 一条规则的path条件,支持多个path描述,如:"/foo/bar", "/foo/cell/\*" -示例: +更多示例: -| path条件 | 请求的path | 是否匹配 | +| path描述 | 请求的path | 是否匹配 | | ----------- | ---------- | ----------------------------------------- | -| 空值 或者 \* | 空值 | 匹配 | -| 空值 或者 \* | / | 匹配 | -| 空值 或者 \* | /a/b | 匹配 | +| \* | 任何path值 | 匹配 | | / | 空值 | 不匹配 | -| / | / | 匹配 | | / | /a | 不匹配 | | /\* | 空值 | 不匹配 | | /\* | / | 匹配,\*可以匹配空值 | -| /\* | /a | 匹配 | -| /\* | /a/b | 匹配,\*可以匹配多个路径元素 | | /\* | /a/ | 匹配,忽略尾部斜线 | -| /a/b/\* | /a/b/c | 匹配 | -| /a/b/\* | /a/b/c/d | 匹配,\*可以匹配多个路径元素 | -| /a/b/\* | /a/b | 匹配,忽略尾部斜线,\*可以匹配多个路径元素 | -| /a/b/\* | /a/c | 不匹配 | -| /a/b/\* | /a/ | 不匹配 | +| /a/b/\* (与 /a/b\* 等价) | /a/b/c | 匹配 | +| /a/b/\* (与 /a/b\* 等价) | /a/b/c/d | 匹配,\*可以匹配多个路径元素 | +| /a/b/\* (与 /a/b\* 等价) | /a/b | 匹配,忽略尾部斜线,\*可以匹配空值 | +| /a/b/\* (与 /a/b\* 等价) | /a/c | 不匹配 | +| /a/b/\* (与 /a/b\* 等价) | /a | 不匹配 | +| /a/b\* | /a/bacon | 不匹配 | ### 基础规则匹配顺序 -基础规则中,host条件和path条件优先级不同,按照如下顺序匹配: +在基础规则表中查找时,先host条件匹配,符合host条件的规则,再进行path条件匹配: 1. 首先对host进行**精确匹配** - 对匹配到的规则(可能是一条或多条),再尝试匹配这些规则的path条件; - 若匹配path条件成功,即为命中规则; - 若匹配path条件未成功,则判定为未命中基础规则,转由高级规则进行匹配 -2. 精确匹配未成功的,对host进行**通配符匹配** +2. host精确匹配未成功的,对host进行**通配符匹配** - 对匹配到的规则(可能是一条或多条),再尝试匹配这些规则的path条件; - 若匹配path条件成功,即为命中规则; - 若匹配path条件未成功,则判定为未命中基础规则,转由高级规则进行匹配 -3. 通配符匹配未成功的,对host进行**任意匹配** +3. host通配符匹配未成功的,对host进行**任意匹配** - 对匹配到的规则(可能是一条或多条),再尝试匹配这些规则的path条件; - 若匹配path条件成功,即为命中规则; - 若匹配path条件未成功,则判定为未命中基础规则,转由高级规则进行匹配 4. 基础规则匹配结束,未命中的,转由高级规则进行匹配 -其中,对于上面步骤中,对host条件匹配到的规则,进行匹配path条件时的匹配顺序如下: +其中,对于上面步骤中,对host条件匹配到的规则,进行匹配path条件时的匹配逻辑如下: 1. 首先对path进行精确匹配 2. 精确匹配未成功的,对path进行前缀匹配。前缀匹配使用最长匹配原则,即若请求的path符合多条规则的path条件,匹配到从左开始有最多路径元素的那条规则(只会是一条规则) -3. 前缀匹配未成功的,对path进行任意匹配 ### 基础规则匹配示例 @@ -134,7 +132,7 @@ path条件的描述语法遵循以下规则: 1.host**精确匹配**,未匹配成功 -2.host**通配符匹配**,发现请求的host(vip.b.test1.com)可以满足规则2,3的host条件。 +2.host**通配符匹配**,发现请求的host(vip.b.test1.com)可以满足规则2,3的host条件(注意,规则1不匹配该请求,因为通配符"\*"只能匹配一个域名标签元素)。 继续进行path匹配: @@ -161,10 +159,10 @@ path条件的描述语法遵循以下规则: - 产品线demo,包含多种服务集群:Demo-A, Demo-B, Demo-C, Demo-D,Demo-E -- 期望的转发条件如下: - + 对于host为www.a.com,path为"/a/b"的请求,转发至Demo-B集群 - + 对于host为www.a.com,path为"/a/*"的请求,转发至Demo-A集群 - + 对于host为\*.a.com的请求,转发至Demo-C集群 +- 期望的集群间分流如下: + + 对于host为www.a.com,且path为"/a/\*" (除了"/a/b") 的请求,转发至Demo-A集群 + + 对于host为www.a.com,且path为"/a/b"的请求,转发至Demo-B集群 + + 对于其他host为\*.a.com的请求,转发至Demo-C集群 + 对于host为www.c.com的请求,转发至Demo-D集群 + 针对Demo-D集群,另外开启了一个灰度集群Demo-D1。如果cookie中包含deviceid,且这个cookie的值以“x”开头,则转发至Demo-D1 + 其它请求,都发往Demo-E @@ -175,12 +173,12 @@ path条件的描述语法遵循以下规则: | ----------- | --------------------------- | ------------------ | | www.a.com | /a/\* | Demo-A | | www.a.com | /a/b | Demo-B | -| \*.a.com | * | Demo-C | -| www.c.com | * | ADVANCED_MODE | +| \*.a.com | \* | Demo-C | +| www.c.com | \* | ADVANCED_MODE | -在基础规则表中,多条规则之间是无序的。匹配顺序见上面关于“基础规则匹配顺序”的说明。 +在基础规则表中,规则之间没有前后顺序。见前面关于“基础规则匹配顺序”的说明。 -针对Demo-D1集群的灰度发布,由于需要使用cookie中的信息,所以使用ADVANCED_MODE将满足条件的请求透传到高级规则表继续处理;在不需要灰度发布的时候,在基础规则表中目标集群可以写为Demo-D。 +针对Demo-D集群上应用的灰度发布,由于需要使用cookie中的信息,所以使用ADVANCED_MODE将满足条件的请求透传到高级规则表继续处理;在不需要灰度发布的时候,在基础规则表中www.c.com对应规则的目标集群写为Demo-D即可。 - **高级规则表**的配置为: