Introduction to the use of Wasm plugins

Configure through the Higress console

The Higress console provides 3 entries for plug-in configuration:

Global configuration: plug-in market -> select plug-in to configure
Domain-level configuration: domain name management->select domain name->click policy->select plug-in to configure
Routing-level configuration: Routing configuration->select routing->click policy->select plug-in to configure

The effective priority of these three configurations is: route level > domain name level > global

That is, the global configuration will only take effect for requests that do not match a specific route or domain name

For general plugins, including custom plugins, the routing/domain name level configuration fields are exactly the same as the global configuration fields;

For authentication plug-ins (Key authentication, HMAC authentication, Basic authentication, JWT authentication, etc.), it is different. The global configuration only configures the Consumer credential and whether to enable global authentication, and configures the allowed access through the allow field at the routing/domain name level. Consumer list, for details, please refer to Configuration Instructions of Key Authentication

Configuration via Higress WasmPlugin CRD

The Higress WasmPlugin CRD extends the Istio WasmPlugin CRD, adding the following configuration fields:

Field Name	Data Type	Filling Requirements	Description
`defaultConfig`	object	Optional	The default configuration of the plugin, which takes effect globally for requests that do not match specific domain names and routing configurations
`matchRules`	array of object	optional	configurations that match domain names or routes to take effect

Description of configuration fields for each item in matchRules:

Field Name	Data Type	Filling Requirements	Configuration Example	Description
`ingress`	array of string	one of `ingress` and `domain` is required	[“default/foo”,“default/bar”]	Matching ingress resource object, the matching format is: `namespace/ingress name`
`domain`	array of string	one of `ingress` and `domain` is required	[“example.com”,“*.test.com”]	match domain name, support generic domain name
`config`	object	optional	-	plug-in configuration that takes effect after matching

Take the Request Blocking plugin as an example, if you want the following configuration of the plugin to take effect globally (please refer to the Request Blocking document for configuration field descriptions):

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

Then the corresponding WasmPlugin needs to be configured as follows:

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

The following requests will be blocked immediately after configuration:

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

If you want to apply the following configuration to the Ingress named foo under the default namespace (matching requests whose path prefix is /foo):

block_headers:
- example-key
- example-value

Then the corresponding WasmPlugin needs to be configured as follows:

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:
    # Route-level effective configuration
   - ingress:
     - default/foo
      # The ingress named foo under the default namespace will execute the following configuration
     config:
       block_headers:
       - example-key
       - example-value
   url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/request-block:1.0.0

After configuration, the following request will not match a specific ingress, so it still hits the global default configuration and is denied access:

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

Since the following request matches the Ingress of foo, the routing-level configuration is not affected by the default configuration and will not be denied access:

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

Because the route-level configuration blocks requests with example-key characters in the request header, the following request will be denied access:

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

When there are multiple rules in matchRules, they will be matched according to the order of the rules. It is recommended to place the ingress matching configuration before the domain matching, which is also the practice of the Higress console

Enable plugins via UI interaction using the Higress console, without needing to concern yourself with the OCI image address here. If configuring via YAML in a non-interactive environment, the OCI image addresses for all official plugins can be found at:

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

Currently, the stable version for all plugins is 1.0.0, while the latest development version is tagged as latest. To consistently use the stable version, you may pin the image tag to a specific version. To leverage the newest capabilities of the plugins, set the image tag to latest, which will automatically pull the newest version of the plugin whenever there are configuration updates available.