Distributing WebAssembly Modules [Experimental]

    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. But first these extensions must be distributed to the proxy. Starting in version 1.9, Istio makes this possible by allowing the Istio agent to dynamically download Wasm modules.

    Here we will walk through an example of adding a basic auth extension to our mesh. We will configure Istio to pull a from a remote URI and load it with configuration to run the module on calls to the path.

    To configure a WebAssembly filter with a remote Wasm module, two EnvoyFilter resources will be installed: one injects the HTTP filter, and the other provides configuration for the filter to use the remote Wasm module.

    With the first EnvoyFilter, an HTTP filter will be injected into gateway proxies. It is configured to request the extension configuration named istio.basic_auth from ads (i.e. Aggregated Discovery Service), which is the same configuration source that Istiod uses to provide all other configuration resources. Within the configuration source, the initial fetch timeout is set to 0s, which means that when the Envoy proxy processes a listener update with this filter, it will wait indefinitely for the first extension configuration update before accepting requests with this listener.

    The second provides configuration for the filter, which is an EXTENSION_CONFIG patch and will be distributed to the proxy as an Envoy Extension Configuration Discovery Service (ECDS) resource. Once this update reaches the Istio agent, the agent will download the Wasm module and store it in the local file system. If the download fails, the agent will reject the ECDS update to prevent invalid Wasm filter configuration from reaching the Envoy proxy. Because of this protection, with the initial fetch timeout being set to 0, the listener update will not become effective and invalid Wasm filter will not disturb the traffic. The important parts of this configuration are:

    • Wasm extension configuration, which is a JSON string that is consumed by the Wasm extension.

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

    • Envoy’s extension configuration discovery service only supports HTTP filters.
    • Modules can only be downloaded through HTTP/HTTPS.

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

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

    An update on Envoy and Istio’s WebAssembly-based extensibility effort.

    Extended and Improved WebAssemblyHub to Bring the Power of WebAssembly to Envoy and Istio

    Community partner tooling of Wasm for Istio by Solo.io.

    Configuring Wasm extensions for Envoy and Istio declaratively.

    The future of Istio extensibility using WASM.