Distributing WebAssembly Modules

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.

Configure an HTTP Filter with a Remote Wasm Module

In this example, you will add a 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 WasmPlugin resource:

  1. apiVersion: extensions.istio.io/v1alpha1
  2. kind: WasmPlugin
  3. metadata:
  4.   name: basic-auth
  5.   namespace: istio-system
  6. spec:
  7.   selector:
  8.     matchLabels:
  9.       istio: ingressgateway
  10.   url: oci://ghcr.io/istio-ecosystem/wasm-extensions/basic_auth:1.12.0
  11.   phase: AUTHN
  12.   pluginConfig:
  13.     basic_auth_rules:
  14.       - prefix: "/productpage"
  15.         request_methods:
  16.           - "GET"
  17.           - "POST"
  18.         credentials:
  19.           - "ok:test"
  20.           - "YWRtaW4zOmFkbWluMw=="

An HTTP filter will be injected into ingress gateway proxies as an authentication filter. The Istio agent will interpret the WasmPlugin 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. The pluginConfig field will be converted to the following JSON string, which will be loaded by the Basic auth plugin at initialization:

  1. {
  2.   "basic_auth_rules": [
  3.     {
  4.       "prefix": "/productpage",
  5.       "request_methods":[ "GET", "POST" ],
  6.       "credentials":[ "ok:test", "YWRtaW4zOmFkbWluMw==" ]
  7.     }
  8.   ]
  9. }

For more example usage of the WasmPlugin API, please take a look at the API reference.

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

  • Only HTTP filters are supported.
  • Modules can only be fetched from a public OCI image registry.

Monitor Wasm Module Distribution

There are several stats which track the distribution status of remote Wasm modules.

The following stats are collected by 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 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: