Distributing WebAssembly Modules (Experimental)

    Istio provides the ability to . 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 basic auth module 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.

    The second provides configuration for the filter, which is an EXTENSION_CONFIG patch and will be distributed to the proxy as an Envoy (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 vm configuration which points to a remote Wasm module.

    The Istio agent will only intercept and download remote Wasm modules configured via ECDS resources. This feature is enabled by default. To disable ECDS interception and Wasm downloading in the Istio agent, set the ISTIO_AGENT_ENABLE_WASM_REMOTE_LOAD_CONVERSION environment variable to false. For example, to set it globally:

    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.

    The following stats are collected by Istio agent:

    • istio_agent_wasm_cache_lookup_count: number of Wasm remote fetch cache lookups.
    • : 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_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 istio-ecosystem/wasm-extensions repository, which is maintained by the Istio community and used to develop Istio’s Telemetry Wasm extension: