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.

Setup the Test Application

Before you begin this task, please deploy the Bookinfo sample application.

Configure Wasm Modules

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:

$ kubectl apply -f - <<EOF
apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: basic-auth
  namespace: istio-system
spec:
  selector:
    matchLabels:
      istio: ingressgateway
  url: oci://ghcr.io/istio-ecosystem/wasm-extensions/basic_auth:1.12.0
  phase: AUTHN
  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 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.

Check the configured Wasm module

1. Test /productpage without credentials

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

2. Test /productpage with credentials

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

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

Clean up Wasm modules

$ kubectl delete wasmplugins.extensions.istio.io -n istio-system basic-auth

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:

• Write, test, deploy, and maintain a Wasm extension with C++
• Build Istio Wasm plugin-compatible OCI images
• Write unit tests for C++ Wasm extensions
• Write integration tests for Wasm extensions

Limitations

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

• Only HTTP filters are supported.