通过 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选填-匹配后生效的插件配置

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

  1. block_urls:
  2. - swagger.html
  3. - foo=bar
  4. case_sensitive: false

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

  1. apiVersion: extensions.higress.io/v1alpha1
  2. kind: WasmPlugin
  3. metadata:
  4.   name: request-block
  5.   namespace: higress-system
  6. spec:
  7.   defaultConfig:
  8.     block_urls:
  9.     - swagger.html
  10.     - foo=bar
  11.     case_sensitive: false
  12.   url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/request-block:1.0.0

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

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

  1. block_headers:
  2. - example-key
  3. - example-value

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

  1. apiVersion: extensions.higress.io/v1alpha1
  2. kind: WasmPlugin
  3. metadata:
  4.   name: request-block
  5.   namespace: higress-system
  6. spec:
  7.   defaultConfig:
  8.     block_urls:
  9.     - swagger.html
  10.     - foo=bar
  11.     case_sensitive: false
  12.   matchRules:
  13.    # 路由级生效配置
  14.   - ingress:
  15.     - default/foo
  16.      # default 命名空间下名为 foo 的 ingress 会执行下面这个配置
  17.     config:
  18.       block_headers:
  19.       - example-key
  20.       - example-value
  21.   url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/request-block:1.0.0

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

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

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

  1. curl http://exmaple.com/foo -H ‘exmaple-key: 123’

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

使用 Higress 控制台通过 UI 交互方式启用插件，无需关心这里的 oci 镜像地址，如果是通过黑屏 yaml 方式配置，所有官方插件的 oci 镜像地址可以在这里找到：

https://github.com/higress-group/higress-console/blob/main/backend/sdk/src/main/resources/plugins/plugins.properties

目前所有插件的稳定版本为 1.0.0，最新开发版本为 latest，如果希望始终使用稳定版本，可以固定镜像 tag 为指定版本，如果希望使用最新的插件能力，可以将镜像 tag 指定为 latest （插件有任意配置更新时就会自动拉取最新版本的插件）

Wasm 插件原理介绍

请查看电子书：《Wasm插件开发篇》