WASM Extension

The differences between TSB and TSE API

Tetrate Service Express (TSE) utilizes many of the same components as the Tetrate Service Bridge(TSB) product but has the several distinctions. Go to Comparing TSE and TSB for more details.

The WASM extension resource allows defining custom WASM extensions that are packaged in OCI images. The resource allows specifying extension metadata that helps understand how extensions work and how they can be used. Once defined, extensions can be referenced in Ingress and Egress Gateways and Security Groups so that traffic is captured and processed by the extension accordingly. By default, extensions are globally available, but they can be assigned to specific Tenants as well to further control and constraint where in the Organization the extensions are allowed to be used.

apiVersion: extension.tsb.tetrate.io/v2
kind: WasmExtension
metadata:
  organization: tse
  name: wasm-auth
spec:
  allowedIn:
    - organizations/org/tenants/tenant1
  url: oci://docker.io/example/my-wasm-extension:1.0
  source: https://github.com/example/wasm-extension
  description: |
    Long description for the extension such as an
    entire README file
  phase: AUTHZ
  priority: 1000
  config:
    some_key: some_value

WASM extensions can also reference HTTP endpoints:

apiVersion: extension.tsb.tetrate.io/v2
kind: WasmExtension
metadata:
  organization: tse
  name: wasm-http
spec:
  url: http://tetrate.io/my-extension.wasm
  source: https://github.com/example/wasm-extension
  description: |
    Long description for the extension such as an
    entire README file
  phase: AUTHZ
  priority: 1000
  config:
    some_key: some_value

EnvVar

Field	Description	Validation Rule
name	string REQUIRED Name of the environment variable. Must be a C_IDENTIFIER, by following this regex: [A-Za-z_][A-Za-z0-9_]*	string = {   pattern: [A-Za-z_][A-Za-z0-9_]* }
valueFrom	tetrateio.api.tsb.extension.v2.EnvValueSource REQUIRED Source for the environment variable's value.	enum = {   defined_only: true }
value	string Value for the environment variable. Note that if value_from is HOST, it will be ignored. Defaults to "".	–

GlobalTrafficSelector

GlobalTrafficSelector provides a mechanism to select a specific traffic flow for which this Wasm Extension will be enabled. This setting applies to all WASM Extension attachments. These selectors can be overridden at attachments. When all the sub conditions in the TrafficSelector are satisfied, the traffic will be selected.

Field	Description	Validation Rule
mode	tetrateio.api.tsb.types.v2.WorkloadMode Criteria for selecting traffic by their direction. Note that CLIENT and SERVER are analogous to OUTBOUND and INBOUND, respectively. For the gateway, the field should be CLIENT or CLIENT_AND_SERVER. If not specified, the default value is CLIENT_AND_SERVER.	–

VmConfig

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

Field	Description	Validation Rule
env	List of tetrateio.api.tsb.extension.v2.EnvVar Specifies environment variables to be injected to this VM. Note that if a key does not exist, it will be ignored.	–

WasmExtension

Field	Description	Validation Rule
image	string Deprecated. Use the url field instead. Repository and tag of the OCI image containing the WASM extension.	–
source	string Source to find the code for the WASM extension	–
phase	tetrateio.api.tsb.extension.v2.WasmExtension.PluginPhase The phase in the filter chain where the extension will be injected. https://istio.io/latest/docs/reference/config/proxy_extensions/wasm-plugin/#PluginPhase	enum = {   defined_only: true }
priority	int32 Determines the ordering of WasmExtensions in the same phase. When multiple WasmExtensions are applied to the same workload in the same phase, they will be applied by priority, in descending order. If no priority is assigned it will use the default 0 value. In case of several extensions having the same priority in the same phase, the fqn will be used to sort them.	–
config	google.protobuf.Struct Configuration parameters sent to the WASM plugin execution The configuration can be overwritten when instantiating the extensions in IngressGateways or Security groups. The config is serialized using proto3 JSON marshaling and passed to proxy_on_configure when the host environment starts the plugin.	–
imagePullPolicy	tetrateio.api.tsb.extension.v2.WasmExtension.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.	enum = {   defined_only: true }
imagePullSecret	string Credentials to use for OCI image pulling. Name of a K8s Secret that contains a docker pull secret which is to be used to authenticate against the registry when pulling the image. If TSB is configured to use the WASM download proxy, this secret must exist in the istio-system namespace of each cluster that has applications that use the extension. If the downlaod proxy is disabled, the secret must exist in each application namespace that is using the extension.	–
vmConfig	tetrateio.api.tsb.extension.v2.VmConfig VM Configuration sent to the WASM plugin execution	–
url	string REQUIRED 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.	string = {   pattern: ^(oci|https?|file)://   ignore_empty: true }
match	tetrateio.api.tsb.extension.v2.GlobalTrafficSelector Specifies the criteria to determine which traffic is passed to WasmExtension. These settings are propagated to all WASMExtension Attachments. It can be overridden at attachment points. If a traffic satisfies the TrafficSelector, the traffic passes to the WasmExtension.	–

EnvValueSource

Field	Number	Description
INLINE	0	Explicitly given key-value pairs to be injected to this VM.
HOST	1	Istio-proxy's* environment variables exposed to this VM.

PluginPhase

Plugin phases following Istio definition: https://istio.io/latest/docs/reference/config/proxy_extensions/wasm-plugin/#PluginPhase

Field	Number	Description
UNSPECIFIED_PHASE	0	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	1	Insert plugin before Istio authentication filters.
AUTHZ	2	Insert plugin before Istio authorization filters and after Istio authentication filters.
STATS	3	Insert plugin before Istio stats filters and after Istio authorization filters.

PullPolicy

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

Field	Number	Description
UNSPECIFIED_POLICY	0	Defaults to IfNotPresent, except for OCI images with tag latest, for which the default will be Always.
IfNotPresent	1	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	2	We will always pull the latest version of an image when changing this plugin. Note that the change includes metadata field as well.