higress/plugins/wasm-go/README.md

English

介绍

此 SDK 用于开发 Higress 的 Wasm 插件

编译环境要求

(需要支持 go 范型特性)

Go 版本: >= 1.18

TinyGo 版本: >= 0.25.0

Quick Examples

使用 request-block 作为例子

step1. 编译 wasm

tinygo build -o main.wasm -scheduler=none -target=wasi ./extensions/request-block/main.go

step2. 构建并推送插件的 docker 镜像

使用这份简单的 dockerfile.

docker build -t <your_registry_hub>/request-block:1.0.0 .
docker push <your_registry_hub>/request-block:1.0.0

step3. 创建 WasmPlugin 资源

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: request-block
  namespace: higress-system
spec:
  selector:
    matchLabels:
      higress: higress-system-higress-gateway
  pluginConfig:
    block_urls:
    - "swagger.html"
  url: oci://<your_registry_hub>/request-block:1.0.0

创建上述资源后，如果请求url携带 swagger.html, 则这个请求就会被拒绝，例如：

curl <your_gateway_address>/api/user/swagger.html

HTTP/1.1 403 Forbidden
date: Wed, 09 Nov 2022 12:12:32 GMT
server: istio-envoy
content-length: 0

如果需要进一步控制插件的执行阶段和顺序

可以阅读此 文档 了解更多关于 wasmplugin 的配置

路由级或域名级生效

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: request-block
  namespace: higress-system
spec:
  selector:
    matchLabels:
      higress: higress-system-higress-gateway 
  pluginConfig:
   # 跟上面例子一样，这个配置会全局生效，但如果被下面规则匹配到，则会改为执行命中规则的配置
   block_urls:
   - "swagger.html"
   _rules_:
   # 路由级生效配置
   - _match_route_:
     - default/foo
     # default 命名空间下名为 foo 的 ingress 会执行下面这个配置
     block_bodys:
     - "foo"
   - _match_route_:
     - default/bar
     # default 命名空间下名为 bar 的 ingress 会执行下面这个配置
     block_bodys:
     - "bar"
   # 域名级生效配置
   - _match_domain_:
     - "*.example.com"
     # 若请求匹配了上面的域名, 会执行下面这个配置
     block_bodys:
     - "foo"
     - "bar"
  url: oci://<your_registry_hub>/request-block:1.0.0

所有规则会按上面配置的顺序一次执行匹配，当有一个规则匹配时，就停止匹配，并选择匹配的配置执行插件逻辑