跳到主要内容

Wasm 插件使用简介

通过 Higress 控制台进行配置​

Higress 控制台提供了 3 个入口进行插件配置:

  1. 全局配置：插件市场->选择插件进行配置
  2. 域名级配置：域名管理->选择域名->点击策略->选择插件进行配置
  3. 路由级配置: 路由配置->选择路由->点击策略->选择插件进行配置

这三个配置的生效优先级是: 路由级 > 域名级 > 全局

即对于没有匹配到具体路由或域名的请求才会生效全局配置

对于一般的插件，包括自定义插件在内，路由/域名级的配置字段和全局配置字段是完全一样的；

对于认证类插件(Key 认证，HMAC 认证，Basic 认证，JWT 认证等)则不同，全局配置仅做 Consumer 凭证配置，以及是否开启全局认证，而在路由/域名级通过allow字段配置允许访问的 Consumer 列表，详情可以查看 Key 认证的配置说明

通过 Higress WasmPlugin CRD 进行配置​

Higress WasmPlugin CRD 在 Istio WasmPlugin CRD 的基础上进行了扩展，新增以下配置字段：

字段名称数据类型填写要求描述
defaultConfigobject选填插件默认配置，全局生效于没有匹配具体域名和路由配置的请求
matchRulesarray of object选填匹配域名或路由生效的配置

matchRules中每一项的配置字段说明：

字段名称数据类型填写要求配置示例描述
ingressarray of stringingress和domain中必填一项["default/foo","default/bar"]匹配 ingress 资源对象，匹配格式为: 命名空间/ingress名称
domainarray of stringingress和domain中必填一项["example.com","*.test.com"]匹配域名，支持泛域名
configobject选填-匹配后生效的插件配置

以请求屏蔽插件举例说明，如果希望全局生效插件的如下配置（请查看请求屏蔽文档了解配置字段说明）：

block_urls:
- swagger.html
- foo=bar
case_sensitive: false

则对应的 WasmPlugin 需要配置如下：

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: request-block
  namespace: higress-system
spec:
  defaultConfig:
    block_urls:
    - swagger.html
    - foo=bar
    case_sensitive: false
  url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/request-block:1.0.0

配置后下列请求将立即被禁止访问:

curl http://example.com?foo=Bar
curl http://exmaple.com/foo/Swagger.html

如果希望对 default 命名空间下名称为 foo 的 Ingress (匹配path前缀为/foo的请求)生效如下配置:

block_headers:
- example-key
- example-value

则对应的 WasmPlugin 需要配置如下：

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: request-block
  namespace: higress-system
spec:
  defaultConfig:
    block_urls:
    - swagger.html
    - foo=bar
    case_sensitive: false
  matchRules:
   # 路由级生效配置
  - ingress:
    - default/foo
     # default 命名空间下名为 foo 的 ingress 会执行下面这个配置
    config:
      block_headers:
      - example-key
      - example-value
  url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/request-block:1.0.0

配置后，下面请求不会匹配到具体的 ingress，因此仍然命中全局默认配置，被拒绝访问：

curl http://example.com?foo=Bar

下面请求由于匹配到 foo 这个 Ingress，因此走路由级的配置，不受默认配置影响，不会被拒绝访问:

curl http://exmaple.com/foo/Swagger.html

因为路由级配置屏蔽了请求 Header 中出现 example-key 字符的请求，所以下面这个请求会被拒绝访问:

curl http://exmaple.com/foo -H 'exmaple-key: 123'

当 matchRules 中存在多个规则时，按规则排列顺序优先匹配，建议将 ingress 匹配配置放在 domain 匹配之前，这也是 Higress 控制台的做法

官方插件镜像地址​

插件名称镜像地址
Key 认证higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/key-auth:1.0.0
Basic 认证higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/basic-auth:1.0.0
HMAC 认证higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/hmac-auth:1.0.0
JWT 认证higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/jwt-auth:1.0.0
机器人拦截higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/bot-detect:1.0.0
自定义应答higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/custom-response:1.0.0
请求屏蔽higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/request-block:1.0.0
基于 Key 限流higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/key-rate-limit:1.0.0
WAF 防护higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/waf:1.0.0

Wasm 插件原理介绍​

什么是 Wasm​

// TODO...

插件生效流程​

// TODO...

插件执行顺序编排​

// TODO...

Wasm 插件如何做到变更时流量无损​

// TODO...