Router 配置

路由配置说明。

router 用于描述 MOSN 的路由配置,通常与 proxy 配合使用。

  1. {
  2. "router_config_name":"",
  3. "virtual_hosts": [
  4. ]
  5. }
  • router_config_name,唯一的路由配置标识,与 proxy 中配置的字段对应。
  • virtual_hosts,描述具体的路由规则细节。

VirtualHost

  1. {
  2. "name":"",
  3. "domains":[],
  4. "routers":[]
  5. }
  • name,字符串。用作 virtual host 的唯一标识。
  • domains,字符串数组。表示一组可以匹配到该 virtual host 的 domain,支持配置通配符。domain 的匹配优先级如下:
    • 首先匹配精确的,如 www.foo.com
    • 其次匹配最长后缀的通配符,如 *.foo.com*-bar.foo.com,其中如果一个 domain 是 foo-bar.foo.com,那么会优先匹配 *-bar.foo.com
    • 最后匹配任意domain的通配符 *
  • routers,一组具体的路由匹配规则。

Router

  1. {
  2. "match":{},
  3. "route":{},
  4. "redirect":{},
  5. "direct_response":{},
  6. "per_filter_config":{}
  7. }
  • match,路由的匹配参数。
  • route,路由行为,描述请求将被路由的 upstream 信息。
  • redirect,路由行为,直接转发。
  • direct_response, 路由行为,直接响应。
  • per_filter_config,是一个 key: json 格式的 json。
  • 其中 key 需要匹配一个 stream filter 的 type,key 对应的 json 是该 stream filter 的 config。
    • 当配置了该字段时,对于某些 stream filter(依赖具体 filter 的实现),可以使用该字段表示的配置覆盖原有 stream filter 的配置,以此做到路由匹配级别的 stream filter 配置。

match

  1. {
  2. "prefix":"",
  3. "path":"",
  4. "regex":"",
  5. "headers": [],
  6. "variables": [],
  7. "dsl_expressions": []
  8. }
  • 路径(path)匹配
    • prefix,表示路由会匹配 path 的前缀,该配置的优先级高于 path 和 regex。 如果 prefix 被配置,那么请求首先要满足 path 的前缀与 prefix 配置相符合。
    • path,表示路由会匹配精确的 path,该配置的优先级高于 regex。如果 path被配置,那么请求首先要满足 path 与 path 配置相符合。
    • regex,表示路由会按照正则匹配的方式匹配 path。如果 regex 被配置,那么请求首先要满足 path 与 regex 配置相符合。
    • 路径匹配配置同时存在时,只有高优先级的配置会生效。
  • Header 匹配
    • headers,表示一组请求需要匹配的 header。请求需要满足配置中所有的 Header 配置条件才算匹配成功。
  • Variable 匹配
    • variables,表示一组请求需要匹配的 variable,请求需要满足配置中所有的 variable 配置条件才算匹配成功。
  • DSL 匹配
    • dsl_expressions,表示一组请求需要匹配的 dsl,请求满足配置条件才算匹配成功。

header

  1. {
  2. "name":"",
  3. "value":"",
  4. "regex":""
  5. }
  • name,表示 header 的 key。
  • value,表示 header 对应 key 的 value。
  • regex,bool 类型,如果为 true,表示 value 支持按照正则表达式的方式进行匹配。

variable

  1. {
  2. "name":"",
  3. "value":"",
  4. "regex":"",
  5. "model":""
  6. }
  • name,表示 variable 的 key。
  • value,表示 variable 对应 key 的 value。
  • regex,表示按照正则表达式的方式进行匹配。
  • model,可配置 “and” 和 “or”。

route

  1. {
  2. "cluster_name":"",
  3. "cluster_variable":"",
  4. "metadata_match":"",
  5. "timeout":"",
  6. "retry_policy":{},
  7. "hash_policy":{},
  8. "prefix_rewrite":"",
  9. "regex_rewrite":{},
  10. "host_rewrite":"",
  11. "request_headers_to_add":[],
  12. "request_headers_to_remove":[],
  13. "response_headers_to_add":[],
  14. "response_headers_to_remove":[]
  15. }

满足match之后的路由策略。

  • cluster_name,表示请求将路由到的 upstream cluster。
  • cluster_variable,表示请求将路由到的变量指定的 upstream cluster,可动态设置变量路由到不同的后端。
  • metadata_matchmetadata,如果配置了该字段,表示该路由会基于该 metadata 去匹配 upstream cluster 的 subset 。
  • timeoutDuration String,表示默认情况下请求转发的超时时间。如果请求中明确指定了超时时间,那么这个配置会被忽略。
  • retry_policy,重试配置,表示如果请求在遇到了特定的错误时采取的重试策略,默认没有配置的情况下,表示没有重试。
  • hash_policy,一致性Hash负载均衡算法使用的hash key。
  • prefix_rewrite regex_rewrite host_rewrite,修改请求的 pathhost
  • request_headers_to_add request_headers_to_remove,表示增加或者删除请求的 header。
  • response_headers_to_add response_headers_to_remove,表示增加或者删除响应的 header。

redirect

  1. {
  2. "response_code":"",
  3. "path_redirect":"",
  4. "host_redirect":"",
  5. "scheme_redirect":""
  6. }

满足 match 条件之后,对请求进行跳转。

  • response_code,跳转的 HTTP code,默认为 301
  • path_redirect,修改跳转的 path
  • host_redirect,修改跳转的 host
  • scheme_redirect,修改跳转的 scheme

direct_response

  1. {
  2. "status":"",
  3. "body":""
  4. }

直接回复响应, status是状态码,body是内容。

retry_policy

  1. {
  2. "retry_on":"",
  3. "retry_timeout":"",
  4. "num_retries":"",
  5. "status_codes":[]
  6. }
  • retry_on,bool 类型,表示是否开启重试。
  • retry_timeoutDuration String,表示每次重试的超时时间。当 retry_timeout 大于 route 配置的 timeout 或者请求明确指定的 timeout 时,属于无效配置。
  • num_retries,表示最大的重试次数。
  • status_codes,重试状态码,配置后仅列表中的状态码会触发重试。

例子

默认匹配规则

所有请求转发到名字为 backend 的 cluster 集群。

  1. "routers": [
  2. {
  3. "match":{
  4. "prefix":"/"
  5. },
  6. "route": {
  7. "cluster_name": "backend"
  8. }
  9. }
  10. ]

匹配规则 - 路径

请求 /index.html 转发到名字为 backend 的 cluster 集群。

  1. "routers": [
  2. {
  3. "match":{
  4. "path":"/index.html"
  5. },
  6. "route": {
  7. "cluster_name": "backend"
  8. }
  9. }
  10. ]

匹配规则 - 正则

数字开头的请求转发到名字为 backend 的 cluster 集群。

  1. "routers": [
  2. {
  3. "match":{
  4. "regex":"^/\\d+"
  5. },
  6. "route": {
  7. "cluster_name": "backend"
  8. }
  9. }
  10. ]

匹配规则 - header

包含 a:b header的请求转发到名字为 backend 的 cluster 集群。

  1. "routers": [
  2. {
  3. "match":{
  4. "headers": [{
  5. "name":"a",
  6. "value":"b",
  7. "regex":false
  8. }]
  9. },
  10. "route": {
  11. "cluster_name": "backend"
  12. }
  13. }
  14. ]

匹配规则 - 变量

可以通过 filter 设置新的变量,以及 MOSN 内置的变量,进行路由转发规则。
如下例子变量 x-mosn-path( MOSN 内置变量,表示请求的 path) 等于 /b 满足匹配。

  1. "routers": [
  2. {
  3. "match":{
  4. "variables": [{
  5. "name":"x-mosn-path",
  6. "value":"/b"
  7. }]
  8. },
  9. "route": {
  10. "cluster_name": "backend"
  11. }
  12. }
  13. ]

匹配行为 - 修改path

下例把请求的 path 修改为 /abc

  1. "routers": [
  2. {
  3. "match":{
  4. "prefix": "/"
  5. },
  6. "route":{
  7. "cluster_name": "backend",
  8. "prefix_rewrite": "/abc"
  9. }
  10. }
  11. ]

匹配行为 - 添加删除 header

下例在转发给后端之前,新增test:ok ,删除hello.

  1. "routers": [
  2. {
  3. "match":{
  4. "prefix": "/"
  5. },
  6. "route":{
  7. "cluster_name": "backend",
  8. "request_headers_to_add": [
  9. {
  10. "header": {
  11. "key": "test",
  12. "value": "ok"
  13. }
  14. }
  15. ],
  16. "request_headers_to_remove":["hello"]
  17. }
  18. }
  19. ]

匹配行为 - redirect

除了转发到 cluster 之外,也支持 redirect 的匹配动作。
下例将 301 跳转,Location: http://test/b

  1. "routers": [
  2. {
  3. "match":{
  4. "prefix": "/"
  5. },
  6. "redirect":{
  7. "response_code":301,
  8. "path_redirect":"/b",
  9. "host_redirect":"test",
  10. "scheme_redirect":"http"
  11. }
  12. }
  13. ]

匹配行为 - 直接响应

满足匹配条件直接响应请求。

  1. "routers": [
  2. {
  3. "match":{
  4. "prefix": "/"
  5. },
  6. "direct_response":{
  7. "status":404,
  8. "body":"no found"
  9. }
  10. }
  11. ]

高级技巧

MOSN 路由框架详解

修改于 2022年12月2日: Bump tar from 4.4.8 to 4.4.19 in /themes/docsy/userguide (942c999)