Introduction to the use of Wasm plugins

Configure through the Higress console

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

  1. Global configuration: plug-in market -> select plug-in to configure
  2. Domain-level configuration: domain name management->select domain name->click policy->select plug-in to configure
  3. 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 NameData TypeFilling RequirementsDescription
defaultConfigobjectOptionalThe default configuration of the plugin, which takes effect globally for requests that do not match specific domain names and routing configurations
matchRulesarray of objectoptionalconfigurations that match domain names or routes to take effect

Description of configuration fields for each item in matchRules:

Field NameData TypeFilling RequirementsConfiguration ExampleDescription
ingressarray of stringone of ingress and domain is required[“default/foo”,“default/bar”]Matching ingress resource object, the matching format is: namespace/ingress name
domainarray of stringone of ingress and domain is required[“example.com”,“*.test.com”]match domain name, support generic domain name
configobjectoptional-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):

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

Then the corresponding WasmPlugin needs to be configured as follows:

  1. 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:

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

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

Then the corresponding WasmPlugin needs to be configured as follows:

  1. 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:

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:

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

  1. 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

Official plugin mirror address

Plugin nameMirror address
Key authenticationhigress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/key-auth:1.0.0
Basic authenticationhigress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/basic-auth:1.0.0
HMAC authenticationhigress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/hmac-auth:1.0.0
JWT authenticationhigress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/jwt-auth:1.0.0
Bot detectionhigress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/bot-detect:1.0.0
Custom Responsehigress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/custom-response:1.0.0
request blockhigress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/request-block:1.0.0
Key-based rate limithigress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/key-rate-limit:1.0.0
WAF Protectionhigress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/waf:1.0.0

Wasm plugin principle introduction

What is Wasm

// TODO…

Plug-in effective process

// TODO…

Plug-in execution sequence arrangement

// TODO…

How does the Wasm plugin achieve lossless traffic when changing

// TODO…