Executing WebAssembly Modules

3 minute read page test

Istio provides the ability to extend proxy functionality using WebAssembly (Wasm). One of the key advantages of Wasm extensibility is that extensions can be loaded dynamically at runtime. These extensions must first be distributed to the Envoy proxy. Istio makes this possible by allowing the proxy agent to dynamically download Wasm modules.

Before you begin

Deploy the Bookinfo sample application.

Configure a Wasm module

In this example, you will add an HTTP Basic auth extension to your mesh. You will configure Istio to pull the Basic auth module from a remote image registry and load it. It will be configured to run on calls to /productpage.

To configure a WebAssembly filter with a remote Wasm module, create a TrafficExtension resource:

$ kubectl apply -f - <<EOF
apiVersion: extensions.istio.io/v1alpha1
kind: TrafficExtension
metadata:
  name: basic-auth
  namespace: istio-system
spec:
  selector:
    matchLabels:
      istio: ingressgateway
  phase: AUTHN
  wasm:
    url: oci://ghcr.io/istio-ecosystem/wasm-extensions/basic_auth:1.12.0
    pluginConfig:
      basic_auth_rules:
        - prefix: "/productpage"
          request_methods:
            - "GET"
            - "POST"
          credentials:
            - "ok:test"
            - "YWRtaW4zOmFkbWluMw=="
EOF

An HTTP filter will be injected into ingress gateway proxies as an authentication filter. The Istio agent will interpret the TrafficExtension configuration, download remote Wasm modules from the OCI image registry to a local file, and inject the HTTP filter into Envoy by referencing that file.

Verify the Wasm module

Determine the ingress IP and port.

Test /productpage without credentials:

$ curl -s -o /dev/null -w "%{http_code}" "http://$INGRESS_HOST:$INGRESS_PORT/productpage"
401

Test /productpage with credentials:

$ curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Basic YWRtaW4zOmFkbWluMw==" "http://$INGRESS_HOST:$INGRESS_PORT/productpage"
200

Ordering and scoping

When multiple TrafficExtension resources target the same workload, execution order is controlled by phase and priority.

phase sets the broad position in the filter chain: AUTHN, AUTHZ, or STATS. Extensions without a phase are inserted near the end of the chain, before the router.
priority breaks ties within the same phase. Higher values run first.

The match field restricts a TrafficExtension to specific traffic by mode and port:

spec:
  match:
  - mode: CLIENT
    ports:
    - number: 8080

Valid modes are CLIENT (outbound), SERVER (inbound), and CLIENT_AND_SERVER (both, the default).

Clean up

$ kubectl delete trafficextension -n istio-system basic-auth

Monitor Wasm module distribution

The following stats are collected by the Istio agent:

istio_agent_wasm_cache_lookup_count: number of Wasm remote fetch cache lookups.
istio_agent_wasm_cache_entries: number of Wasm config conversions and results, including success, no remote load, marshal failure, remote fetch failure, and miss remote fetch hint.
istio_agent_wasm_config_conversion_duration_bucket: total time in milliseconds the Istio agent spends on config conversion for Wasm modules.
istio_agent_wasm_remote_fetch_count: number of Wasm remote fetches and results, including success, download failure, and checksum mismatch.

If a Wasm filter configuration is rejected, either due to download failure or other reasons, istiod will also emit pilot_total_xds_rejects with the type label type.googleapis.com/envoy.config.core.v3.TypedExtensionConfig.

Develop a Wasm extension

To learn more about Wasm module development, please refer to the guides provided in the istio-ecosystem/wasm-extensions repository, which is maintained by the Istio community and used to develop Istio’s Telemetry Wasm extension:

For more details on the API, see the TrafficExtension reference.

Limitations

There are known limitations with this module distribution mechanism, which will be addressed in future releases:

Only HTTP filters are supported.