Wasm Plugin

6 minute read

WasmPlugins provides a mechanism to extend the functionality provided by the Istio proxy through WebAssembly filters.

Order of execution (as part of Envoy’s filter chain) is determined by phase and priority settings, allowing the configuration of complex interactions between user-supplied WasmPlugins and Istio’s internal filters.

Examples:

AuthN Filter deployed to ingress-gateway that implements an OpenID flow and populates the Authorization header with a JWT to be consumed by Istio AuthN.

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: openid-connect
  namespace: istio-ingress
spec:
  selector:
    matchLabels:
      istio: ingressgateway
  url: file:///opt/filters/openid.wasm
  sha256: 1ef0c9a92b0420cf25f7fe5d481b231464bc88f486ca3b9c83ed5cc21d2f6210
  phase: AUTHN
  pluginConfig:
    openid_server: authn
    openid_realm: ingress

This is the same as the last example, but using an OCI image.

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: openid-connect
  namespace: istio-ingress
spec:
  selector:
    matchLabels:
      istio: ingressgateway
  url: oci://private-registry:5000/openid-connect/openid:latest
  imagePullPolicy: IfNotPresent
  imagePullSecret: private-registry-pull-secret
  phase: AUTHN
  pluginConfig:
    openid_server: authn
    openid_realm: ingress

This is the same as the last example, but using VmConfig to configure environment variables in the VM.

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: openid-connect
  namespace: istio-ingress
spec:
  selector:
    matchLabels:
      istio: ingressgateway
  url: oci://private-registry:5000/openid-connect/openid:latest
  imagePullPolicy: IfNotPresent
  imagePullSecret: private-registry-pull-secret
  phase: AUTHN
  pluginConfig:
    openid_server: authn
    openid_realm: ingress
  vmConfig:
    env:
    - name: POD_NAME
      valueFrom: HOST
    - name: TRUST_DOMAIN
      value: "cluster.local"

This is also the same as the last example, but the Wasm module is pulled via https and updated for each time when this plugin resource is changed.

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: openid-connect
  namespace: istio-ingress
spec:
  selector:
    matchLabels:
      istio: ingressgateway
  url: https://private-bucket/filters/openid.wasm
  imagePullPolicy: Always
  phase: AUTHN
  pluginConfig:
    openid_server: authn
    openid_realm: ingress
  vmConfig:
    env:
    - name: POD_NAME
      valueFrom: HOST
    - name: TRUST_DOMAIN
      value: "cluster.local"

And a more complex example that deploys three WasmPlugins and orders them using phase and priority. The (hypothetical) setup is that the openid-connect filter performs an OpenID Connect flow to authenticate the user, writing a signed JWT into the Authorization header of the request, which can be verified by the Istio authn plugin. Then, the acl-check plugin kicks in, passing the JWT to a policy server, which in turn responds with a signed token that contains information about which files and functions of the system are available to the user that was previously authenticated. The acl-check filter writes this token to a header. Finally, the check-header filter verifies the token in that header and makes sure that the token’s contents (the permitted ‘function’) matches its plugin configuration.

The resulting filter chain looks like this: -> openid-connect -> istio.authn -> acl-check -> check-header -> router

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: openid-connect
  namespace: istio-ingress
spec:
  selector:
    matchLabels:
      istio: ingressgateway
  url: oci://private-registry:5000/openid-connect/openid:latest
  imagePullPolicy: IfNotPresent
  imagePullSecret: private-registry-pull-secret
  phase: AUTHN
  pluginConfig:
    openid_server: authn
    openid_realm: ingress

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: acl-check
  namespace: istio-ingress
spec:
  selector:
    matchLabels:
      istio: ingressgateway
  url: oci://private-registry:5000/acl-check/acl:latest
  imagePullPolicy: Always
  imagePullSecret: private-registry-pull-secret
  phase: AUTHZ
  priority: 1000
  pluginConfig:
    acl_server: some_server
    set_header: authz_complete

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: check-header
  namespace: istio-ingress
spec:
  selector:
    matchLabels:
      istio: ingressgateway
  url: oci://private-registry:5000/check-header:latest
  imagePullPolicy: IfNotPresent
  imagePullSecret: private-registry-pull-secret
  phase: AUTHZ
  priority: 10
  pluginConfig:
    read_header: authz_complete
    verification_key: a89gAzxvls0JKAKIJSBnnvvvkIO
    function: read_data

WasmPlugin

WasmPlugins provides a mechanism to extend the functionality provided by the Istio proxy through WebAssembly filters.

Field	Type	Description	Required
`selector`	`WorkloadSelector`	Criteria used to select the specific set of pods/VMs on which this plugin configuration should be applied. If omitted, this configuration will be applied to all workload instances in the same namespace. If the `WasmPlugin` is present in the config root namespace, it will be applied to all applicable workloads in any namespace.	No
`url`	`string`	URL of a Wasm module or OCI container. If no scheme is present, defaults to `oci://`, referencing an OCI image. Other valid schemes are `file://` for referencing .wasm module files present locally within the proxy container, and `http[s]://` for .wasm module files hosted remotely.	No
`sha256`	`string`	SHA256 checksum that will be used to verify Wasm module or OCI container. If the `url` field already references a SHA256 (using the `@sha256:` notation), it must match the value of this field. If an OCI image is referenced by tag and this field is set, its checksum will be verified against the contents of this field after pulling.	No
`imagePullPolicy`	`PullPolicy`	The pull behaviour to be applied when fetching Wasm module by either OCI image or http/https. Only relevant when referencing Wasm module without any digest, including the digest in OCI image URL or sha256 field in `vm_config`. Defaults to IfNotPresent, except when an OCI image is referenced in the `url` and the `latest` tag is used, in which case `Always` is the default, mirroring K8s behaviour.	No
`imagePullSecret`	`string`	Credentials to use for OCI image pulling. Name of a K8s Secret in the same namespace as the `WasmPlugin` that contains a docker pull secret which is to be used to authenticate against the registry when pulling the image.	No
`pluginConfig`	`Struct`	The configuration that will be passed on to the plugin.	No
`pluginName`	`string`	The plugin name to be used in the Envoy configuration (used to be called `rootID`). Some .wasm modules might require this value to select the Wasm plugin to execute.	No
`phase`	`PluginPhase`	Determines where in the filter chain this `WasmPlugin` is to be injected.	No
`priority`	`Int64Value`	Determines ordering of `WasmPlugins` in the same `phase`. When multiple `WasmPlugins` are applied to the same workload in the same `phase`, they will be applied by priority, in descending order. If `priority` is not set, or two `WasmPlugins` exist with the same value, the ordering will be deterministically derived from name and namespace of the `WasmPlugins`. Defaults to `0`.	No
`vmConfig`	`VmConfig`	Configuration for a Wasm VM. more details can be found here.	No

VmConfig

Configuration for a Wasm VM. more details can be found here.

Field	Type	Description	Required
`env`	`EnvVar[]`	Specifies environment variables to be injected to this VM. Note that if a key does not exist, it will be ignored.	No

EnvVar

Field	Type	Description	Required
`name`	`string`	Required Name of the environment variable. Must be a C_IDENTIFIER.	No
`valueFrom`	`EnvValueSource`	Required Source for the environment variable’s value.	No
`value`	`string`	Value for the environment variable. Note that if `value_from` is `HOST`, it will be ignored. Defaults to “”.	No

PluginPhase

The phase in the filter chain where the plugin will be injected.

Name	Description
`UNSPECIFIED_PHASE`	Control plane decides where to insert the plugin. This will generally be at the end of the filter chain, right before the Router. Do not specify `PluginPhase` if the plugin is independent of others.
`AUTHN`	Insert plugin before Istio authentication filters.
`AUTHZ`	Insert plugin before Istio authorization filters and after Istio authentication filters.
`STATS`	Insert plugin before Istio stats filters and after Istio authorization filters.

PullPolicy

The pull behaviour to be applied when fetching a Wam module, mirroring K8s behaviour.

Name	Description
`UNSPECIFIED_POLICY`	Defaults to IfNotPresent, except for OCI images with tag `latest`, for which the default will be Always.
`IfNotPresent`	If an existing version of the image has been pulled before, that will be used. If no version of the image is present locally, we will pull the latest version.
`Always`	We will always pull the latest version of an image when changing this plugin. Note that the change includes `metadata` field as well.

EnvValueSource

Name	Description
`INLINE`	Explicitly given key-value pairs to be injected to this VM
`HOST`	Istio-proxy’s environment variables exposed to this VM.