Deploy a Mock Response Wasm Plugin with Higress: Step‑by‑Step Guide

On November 15 a live demo showed how to configure a Higress Wasm plugin for an Ingress resource to return mock HTTP responses. The demo assumes a Kubernetes cluster with Higress installed and uses the quickstart configuration at

https://github.com/alibaba/higress/releases/download/v0.5.2/quickstart.yaml

.

Writing the Plugin Code

The plugin is a 30‑line Go program that defines a configuration struct, parses a JSON config, and sends a static HTTP response using the proxy‑wasm SDK:

package main

import (
    . "github.com/alibaba/higress/plugins/wasm-go/pkg/wrapper"
    "github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm"
    "github.com/tetratelabs/proxy-wasm-go-sdk/proxywasm/types"
    "github.com/tidwall/gjson"
)

func main() {
    SetCtx(
        "my-plugin",
        ParseConfigBy(parseConfig),
        ProcessRequestHeadersBy(onHttpRequestHeaders),
    )
}

type MyConfig struct { content string }

func parseConfig(json gjson.Result, config *MyConfig, log Log) error {
    config.content = json.Get("content").String()
    return nil
}

func onHttpRequestHeaders(ctx HttpContext, config MyConfig, log Log) types.Action {
    proxywasm.SendHttpResponse(200, nil, []byte(config.content), -1)
    return types.ActionContinue
}

The three functions are:

main : registers the plugin name, the config parser, and the request‑header handler.

parseConfig : extracts the content field from the JSON configuration.

onHttpRequestHeaders : sends the HTTP response defined in the configuration.

Compiling the Plugin

Compile the Go source to a WebAssembly binary using TinyGo:

tinygo build -o plugin.wasm -scheduler=none -target=wasi main.go

Packaging and Pushing the Image

Create a minimal Dockerfile that copies the plugin.wasm file:

FROM scratch
COPY plugin.wasm ./

Build and push the image to the Higress registry (replace the tag as needed):

docker build -t higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/demo:1.0.0 .

docker push higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/demo:1.0.0

Deploying the WasmPlugin Resource

Apply a WasmPlugin custom resource that points to the OCI image and provides the plugin configuration:

# wasmplugin.yaml
apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: mock-response
  namespace: higress-system
spec:
  selector:
    matchLabels:
      higress: higress-system-higress-gateway
  pluginConfig:
    content: "hello higress"
  url: oci://higress-registry.cn-hangzhou.cr.aliyuncs.com/plugins/demo:1.0.0

Deploy it with:

kubectl apply -f wasmplugin.yaml

Testing the Plugin

Without the plugin, requests to /foo and /bar return the literal path. After the WasmPlugin is applied, both return hello higress. The plugin can also be scoped to specific routes or domains by adding a _rules_ section:

# wasmplugin.yaml (partial)
pluginConfig:
  content: "hello higress"
  _rules_:
  - content: "hello foo"
    _match_route_:
    - "default/foo"
  - content: "hello bar"
    _match_route_:
    - "default/bar"
  - content: "hello world"
    _match_domain_:
    - "*.example.com"
    - "www.test.com"

Applying this configuration yields route‑specific responses ( /foo → hello foo, /bar → hello bar) and domain‑specific responses ( www.example.com → hello world).

Plugin Activation Mechanism

The overall activation flow is:

Compile Go code to a Wasm file.

Package the Wasm file into a Docker image.

Push the image to a registry.

Create a WasmPlugin resource.

Istio watches the resource and notifies the xDS proxy.

The xDS proxy fetches the image, extracts the Wasm binary, and makes it available to the Envoy sidecar.

Envoy loads the Wasm module via Extension Config Discovery Service (ECDS), enabling hot‑reload without traffic interruption.

Three Revolutionary Features of Wasm Plugins

Feature 1: Decoupled Lifecycle

Wasm plugins are versioned and deployed independently via OCI images. Updating a plugin only requires publishing a new image and updating the WasmPlugin resource; the gateway itself does not need to be rebuilt or redeployed.

Feature 2: High‑Performance Multi‑Language Support

Wasm enables writing plugins in Go, Rust, C++, AssemblyScript, etc. Benchmarks show request‑latency overhead comparable to Lua (≈0.20 ms) and significantly lower than external process plugins.

Lua – 0.20 ms

Wasm (C++) – 0.19 ms

Wasm (Go) – 0.20 ms

Wasm (Rust) – 0.21 ms

Wasm (AssemblyScript) – 0.21 ms

Feature 3: Secure Sandbox

Envoy supports multiple Wasm runtimes (V8, WAMR, Wasmtime) that isolate plugin crashes. Faulty plugins can be configured for fail‑open handling, ensuring they do not crash the host process.

For further details, see the Higress Wasm‑Go SDK documentation ( https://higress.io/zh-cn/docs/user/wasm-go.html) and the upstream proxy‑wasm‑go‑sdk repository ( https://github.com/tetratelabs/proxy-wasm-go-sdk).