Wasm (proto)

This extension has the qualified name envoy.bootstrap.wasm

Note

This extension is functional but has not had substantial production burn time, use only with this caveat.

This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.bootstrap

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.extensions.wasm.v3.WasmService

extensions.wasm.v3.CapabilityRestrictionConfig

[extensions.wasm.v3.CapabilityRestrictionConfig proto]

Configuration for restricting Proxy-Wasm capabilities available to modules.

{
  "allowed_capabilities": {...}
}

allowed_capabilities

(repeated map<string, extensions.wasm.v3.SanitizationConfig>) The Proxy-Wasm capabilities which will be allowed. Capabilities are mapped by name. The SanitizationConfig which each capability maps to is currently unimplemented and ignored, and so should be left empty.

The capability names are given in the Proxy-Wasm ABI. Additionally, the following WASI capabilities from this list are implemented and can be allowed: fd_write, fd_read, fd_seek, fd_close, fd_fdstat_get, environ_get, environ_sizes_get, args_get, args_sizes_get, proc_exit, clock_time_get, random_get.

extensions.wasm.v3.SanitizationConfig

[extensions.wasm.v3.SanitizationConfig proto]

Configuration for sanitization of inputs to an allowed capability.

NOTE: This is currently unimplemented.

extensions.wasm.v3.VmConfig

[extensions.wasm.v3.VmConfig proto]

Configuration for a Wasm VM.

{
  "vm_id": ...,
  "runtime": ...,
  "code": {...},
  "configuration": {...},
  "allow_precompiled": ...,
  "nack_on_code_cache_miss": ...,
  "environment_variables": {...}
}

vm_id: (string) An ID which will be used along with a hash of the wasm code (or the name of the registered Null VM plugin) to determine which VM will be used for the plugin. All plugins which use the same vm_id and code will use the same VM. May be left blank. Sharing a VM between plugins can reduce memory utilization and make sharing of data easier which may have security implications.

runtime

(string) The Wasm runtime type, defaults to the first available Wasm engine used at Envoy build-time. The priority to search for the available engine is: v8 -> wasmtime -> wamr. Available Wasm runtime types are registered as extensions. The following runtimes are included in Envoy code base:

envoy.wasm.runtime.null: Null sandbox, the Wasm module must be compiled and linked into the Envoy binary. The registered name is given in the code field as inline_string.

envoy.wasm.runtime.v8: V8-based WebAssembly runtime.

envoy.wasm.runtime.wamr: WAMR-based WebAssembly runtime. This runtime is not enabled in the official build.

envoy.wasm.runtime.wasmtime: Wasmtime-based WebAssembly runtime. This runtime is not enabled in the official build.

Tip

This extension category has the following known extensions:

envoy.wasm.runtime.null
envoy.wasm.runtime.v8
envoy.wasm.runtime.wamr
envoy.wasm.runtime.wasmtime

code: (config.core.v3.AsyncDataSource) The Wasm code that Envoy will execute.

configuration: (Any) The Wasm configuration used in initialization of a new VM (proxy_on_start). google.protobuf.Struct is serialized as JSON before passing it to the plugin. google.protobuf.BytesValue and google.protobuf.StringValue are passed directly without the wrapper.

allow_precompiled: (bool) Allow the wasm file to include pre-compiled code on VMs which support it. Warning: this should only be enable for trusted sources as the precompiled code is not verified.

nack_on_code_cache_miss: (bool) If true and the code needs to be remotely fetched and it is not in the cache then NACK the configuration update and do a background fetch to fill the cache, otherwise fetch the code asynchronously and enter warming state.

environment_variables: (extensions.wasm.v3.EnvironmentVariables) Specifies environment variables to be injected to this VM which will be available through WASI’s environ_get and environ_get_sizes system calls. Note that these functions are mostly implicitly called in your language’s standard library, so you do not need to call them directly and you can access to env vars just like when you do on native platforms. Warning: Envoy rejects the configuration if there’s conflict of key space.

extensions.wasm.v3.EnvironmentVariables

[extensions.wasm.v3.EnvironmentVariables proto]

{
  "host_env_keys": [],
  "key_values": {...}
}

host_env_keys: (repeated string) The keys of Envoy’s environment variables exposed to this VM. In other words, if a key exists in Envoy’s environment variables, then that key-value pair will be injected. Note that if a key does not exist, it will be ignored.

key_values: (repeated map<string, string>) Explicitly given key-value pairs to be injected to this VM in the form of “KEY=VALUE”.

extensions.wasm.v3.PluginConfig

[extensions.wasm.v3.PluginConfig proto]

Base Configuration for Wasm Plugins e.g. filters and services.

{
  "name": ...,
  "root_id": ...,
  "vm_config": {...},
  "configuration": {...},
  "fail_open": ...,
  "capability_restriction_config": {...}
}

name: (string) A unique name for a filters/services in a VM for use in identifying the filter/service if multiple filters/services are handled by the same vm_id and root_id and for logging/debugging.

root_id: (string) A unique ID for a set of filters/services in a VM which will share a RootContext and Contexts if applicable (e.g. an Wasm HttpFilter and an Wasm AccessLog). If left blank, all filters/services with a blank root_id with the same vm_id will share Context(s).

vm_config: (extensions.wasm.v3.VmConfig) Configuration for finding or starting VM.

configuration: (Any) Filter/service configuration used to configure or reconfigure a plugin (proxy_on_configure). google.protobuf.Struct is serialized as JSON before passing it to the plugin. google.protobuf.BytesValue and google.protobuf.StringValue are passed directly without the wrapper.

fail_open: (bool) If there is a fatal error on the VM (e.g. exception, abort(), on_start or on_configure return false), then all plugins associated with the VM will either fail closed (by default), e.g. by returning an HTTP 503 error, or fail open (if ‘fail_open’ is set to true) by bypassing the filter. Note: when on_start or on_configure return false during xDS updates the xDS configuration will be rejected and when on_start or on_configuration return false on initial startup the proxy will not start.

capability_restriction_config: (extensions.wasm.v3.CapabilityRestrictionConfig) Configuration for restricting Proxy-Wasm capabilities available to modules.

extensions.wasm.v3.WasmService

[extensions.wasm.v3.WasmService proto]

WasmService is configured as a built-in envoy.wasm_service WasmService This opaque configuration will be used to create a Wasm Service.

{
  "config": {...},
  "singleton": ...
}

config: (extensions.wasm.v3.PluginConfig) General plugin configuration.

singleton: (bool) If true, create a single VM rather than creating one VM per worker. Such a singleton can not be used with filters.