Wasm Plugin
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.
VmConfig
Configuration for a Wasm VM. more details can be found here.
EnvVar
WasmPlugin.TrafficSelector
TrafficSelector provides a mechanism to select a specific traffic flow for which this Wasm Plugin will be enabled. When all the sub conditions in the TrafficSelector are satisfied, the traffic will be selected.
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 |
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 |
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 |
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. |
FailStrategy
Name | Description |
---|---|
FAIL_CLOSE | A fatal error in the binary fetching or during the plugin execution causes all subsequent requests to fail with 5xx. |
FAIL_OPEN | Enables the fail open behavior for the Wasm plugin fatal errors to bypass the plugin execution. A fatal error can be a failure to fetch the remote binary, an exception, or abort() on the VM. This flag is not recommended for the authentication or the authorization plugins. |