WebAssembly extension configuration reference
This topic describes how to configure the wasm
extension, which directs Consul to run WebAssembly (Wasm) plugins in Envoy proxies. Refer to Run WebAssembly plug-ins in Envoy proxy for usage information.
Configuration model
The following list outlines the field hierarchy, data types, and requirements for the wasm
configuration. Place the configuration inside the EnvoyExtension.Arguments
field in the proxy defaults or service defaults configuration entry. Refer the following documentation for additional information:
Click on a property name to view additional details, including default values.
Protocol
: stringListenerType
: string | requiredProxyType
: string |connect-proxy
PluginConfig
: map | requiredName
: stringRootID
: string | requiredVmConfig
: mapVmID
: stringRuntime
: string |v8
Code
: mapLocal
: mapFilename
: string
Remote
: mapHttpURI
: mapSHA256
: stringRetryPolicy
: mapRetryBackOff
: mapBaseInterval
: stringMaxInterval
: string
NumRetries
: number |-1
Configuration
: stringEnvironmentVariables
: mapHostEnvKeys
: list of stringsKeyValues
: map
Configuration
: stringCapabilityRestrictionConfiguration
: mapAllowedCapabilities
: map of strings
Complete configuration
When all parameters are set for the extension, the configuration has the following form:
Specification
This section provides details about the fields you can configure for the wasm
extension.
Protocol
Specifies the type of Wasm filter to apply. You can set either tcp
or http
. Set the Protocol
to the protocol that the Wasm plugin implements when loaded by the filter. For Consul to apply the filter, the protocol must match the service's protocol.
Values
ListenerType
Specifies the type of listener the extension applies to. The listener type is either inbound
or outbound
. If the listener type is set to inbound
, Consul applies the extension so the Wasm plugin is run when other services in the mesh send messages to the service attached to the proxy. If the listener type is set to outbound
, Consul applies the extension so the Wasm plugin is run when the attached proxy sends messages to other services in the mesh.
Values
ProxyType
Specifies the type of Envoy proxy that the extension applies to. The only supported value is connect-proxy
.
Values
- Default:
connect-proxy
- This field is required.
- Data type: String
PluginConfig{}
Map containing the following configuration parameters for your Wasm plugin:
Values
- Default: None
- This field is required.
- Data type: Map
PluginConfig{}.Name
Specifies a unique name for a filter in a VM. Envoy uses the name to identify specific filters if multiple filters are processed on a VM with the same VmID
and RootID
. The name also appears in logs for debugging purposes.
Values
- Default: None
- Data type: String
PluginConfig{}.RootID
Specifies a unique ID for a set of filters in a VM that share a RootContext
and Contexts
, such as a Wasm HttpFilter
and a Wasm AccessLog
, if applicable. All filters with the same RootID
and VmID
share Context
s.
Values
- Default: None
- Data type: String
PluginConfig{}.VmConfig{}
Map containing the following configuration parameters for the VM that runs your Wasm plugin:
Values
- Default: None
- Data type: Map
PluginConfig{}.VmConfig{}.VmID
Specifies an ID that Envoy uses with a hash of the Wasm code to determine which VM runs the plugin. All plugins with the same VmID
and Code
use the same VM. If unspecified, all plugins with the same code run in the same VM. Sharing a VM between plugins may have security implications, but can reduce memory utilization and can make data sharing easier.
Values
- Default: None
- Data type: String
PluginConfig{}.VmConfig{}.Runtime
Specifies the type of Wasm runtime.
Values
PluginConfig{}.VmConfig{}.Code{}
Map containing one of the following configuration parameters:
You can configure either Local
or Remote
, but not both. The Code
block instructs Consul how to find the Wasm plugin code for Envoy to execute.
Values
- Default: None
- This field is required.
- Data type is a map containing one of the following configurations:
PluginConfig{}.VmConfig{}.Code{}.Local{}
Instructs Envoy to load the plugin code from a local volume. Do not configure the Local
parameter if the plugin code is on a remote server.
The Local
field is a map that contains a Filename
parameter. The Filename
parameter takes a string value that specifies the path to the plugin on the local file system.
Local plug-ins are not supported in Kubernetes-orchestrated environments.
Values
- Default: None
- Data type is a map containing the
Filename
parameter. TheFilename
parameter takes a string value that specifies the path to the plugin on the local file system.
PluginConfig{}.VmConfig{}.Code{}.Remote{}
Instructs Envoy to load the plugin code from a remote server. Do not configure the Remote
parameter if the plugin code is on the local VM.
The Remote
field is a map containing the following parameters:
Values
- Default: None
- Data type: Map
PluginConfig{}.VmConfig{}.Code{}.Remote{}.HttpURI{}
Specifies the configuration for fetching the remote data. The HttpURI
field is a map containing the following parameters:
Values
- Default: None
- Data type: Map
PluginConfig{}.VmConfig{}.Code{}.Remote{}.HttpURI{}.Service
Specifies the upstream service to fetch the remote plugin from.
Values
- Default: None
- Data type: Map
The following table describes the fields you can specify in the Service
map:
Parameter | Description | Data type | Default |
---|---|---|---|
Name | Specifies the name of the upstream service. | String | None |
Namespace | Enterprise Specifies the Consul namespace that the upstream service belongs to. | String | default |
Partition | Enterprise Specifies the Consul admin partition that the upstream service belongs to. | String | default |
PluginConfig{}.VmConfig{}.Code{}.Remote{}.HttpURI{}.URI
Specifies the URI Envoy uses to fetch the plugin file from the upstream. This field is required for Envoy to retrieve plugin code from a remote location. You must specify the fully-qualified domain name (FQDN) of the remote URI, which includes the protocol, host, and path.
Values
- Default: None
- This field is required.
- Data type: String value that specifies a FQDN
PluginConfig{}.VmConfig{}.Code{}.Remote{}.HttpURI{}.Timeout
Specifies the maximum duration that a response can take to complete the request for the plugin data.
Values
- Default:
1s
- Data type: String
PluginConfig{}.VmConfig{}.Code{}.Remote{}.SHA256
Specifies the required SHA256 string for verifying the remote data.
Values
- Default: None
- This field is required.
- Data type: String
PluginConfig{}.VmConfig{}.Code{}.Remote{}.RetryPolicy{}
Defines a policy for retrying requests to the upstream service when fetching the plugin data. The RetryPolicy
field is a map containing the following parameters:
Values
- Default: None
- Data type: Map
PluginConfig{}.VmConfig{}.Code{}.Remote{}.RetryPolicy{}.RetryBackOff{}
Specifies parameters that control retry backoff strategy.
Values
- Default: None
- Data type: Map
The following table describes the fields you can specify in the RetryBackOff
map:
Parameter | Description | Data type | Default |
---|---|---|---|
BaseInterval | Specifies the base interval for determining the next backoff computation. Set a value greater than 0 and less than or equal to the MaxInterval value. | String | 1s |
MaxInterval | Specifies the maximum interval between retries. Set the value greater than or equal to the BaseInterval value. | String | 10s |
PluginConfig{}.VmConfig{}.Code{}.Remote{}.RetryPolicy{}.NumRetries
Specifies the number of times Envoy retries to fetch plugin data if the initial attempt is unsuccessful.
Values
- Default:
1
- Data type: Integer
PluginConfig{}.VmConfig{}.Configuration
Specifies the configuration Envoy encodes as bytes and passes to the plugin during VM startup. Refer to proxy_on_vm_start
in the Proxy Wasm ABI documentation for additional information.
Values
- Default: None
- This field is required.
- Data type: String
PluginConfig{}.VmConfig{}.EnvironmentVariables{}
Specifies environment variables for Enovy to inject into this VM so that they are available through WASI's environ_get
and environ_get_sizes
system calls.
In most cases, WASI calls the functions implicitly in your language's standard library. As a result, you do not need to call them directly. You can also access environment variables as you would on native platforms.
Envoy rejects the configuration if there is a key space conflict.
The EnvironmentVariables
field is a map containing parameters for setting the keys and values.
Values
- Default: None
- Data type: Map
The following table describes the parameters contained in the EnvironmentVariables
map:
Parameter | Description | Data type | Default |
---|---|---|---|
HostEnvKeys | Specifies a list of Envoy environment variable keys to expose to the VM. If a key exists in Envoy's environment variables, then the key-value pair is injected. Envoy ignores HostEnvKeys that do not exist in its environment variables. | List | None |
KeyValues | Specifies a map of explicit key-value pairs to inject into the VM. | None |
PluginConfig{}.Configuration
Specifies the configuration Consul encodes as bytes and passes to the plugin during plugin startup. Refer to proxy_on_configure
in the Envoy documentation for additional information.
Values
- Default: None
- Data type: String
PluginConfig{}.CapabilityRestrictionConfiguration{}
Specifies a configuration for restricting the proxy-Wasm capabilities that are available to the module.
The CapabilityRestrictionConfiguration
field is a map that contains a AllowedCapabilities
parameter. The AllowedCapabilities
parameter takes a map of string values that correspond to Envoy capability names. Refer to the Envoy documentation for additional information.
Security warning: Consul ignores the value that each capability maps to. You can leave the AllowedCapabilities
empty to allow all capabilities, but doing so gives the configured plugin full unrestricted access to the runtime API provided by the Wasm VM. You must set this to a non-empty map if you want to restrict access to specific capabilities provided by the Wasm runtime API.
Values
- Default:
""
- Data type is a map containing the
AllowedCapabilities
parameter. TheAllowedCapabilities
parameter takes a map of string values that correspond to Envoy capability names. Refer to the Envoy documentation for additional information.
Examples
The following examples demonstrate patterns that you may be able to model your configurations on.
Run a Wasm plugin from a local file
In the following example, Consul figures the Envoy proxy for the db
service with an inbound TCP Wasm filter that uses the plugin code from the local /consul/extensions/sqli.wasm
file.
Run a Wasm plugin from a remote file
In the following example, Consul configures the Envoy proxy for all HTTP services with an HTTP Wasm filter. The filter uses the plugin code from a remote https://extension-server/waf.wasm
file. The Envoy proxy for each service fetches the remote file and verify the SHA256 checksum. The proxy times if Consul cannot fetch the remote plugin after three seconds.