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: string
ListenerType: string | required
ProxyType: string | connect-proxy
PluginConfig: map | required
- Name: string
- RootID: string | required
- VmConfig: map
  - VmID: string
  - Runtime: string | v8
  - Code: map
    - Local: map
      - Filename: string
    - Remote: map
      - HttpURI: map
        Service: map
        Name: string
        Namespace: string
        Partition: string
        URI: string
        Timeout: string
      - SHA256: string
      - RetryPolicy: map
        RetryBackOff: map
        BaseInterval: string
        MaxInterval: string
        NumRetries: number | -1
  - Configuration: string
  - EnvironmentVariables: map
    - HostEnvKeys: list of strings
    - KeyValues: map
- Configuration: string
- CapabilityRestrictionConfiguration: map
  - AllowedCapabilities: map of strings

Complete configuration

When all parameters are set for the extension, the configuration has the following form:

Protocol = "<tcp or http>"
ListenerType = "<inbound or outbound>"
ProxyType = "connect-proxy"
PluginConfig = {
   Name = "<name for the filter>"
   RootID = "<ID for the set of filters on a VM>"
   VmConfig = {
      VmID = "<ID of the VM>"
      Runtime = "v8"
      Code = {
         Local = {      # Set either `Local` or `Remote', not both
            Filename = "</path/to/plugin>"
         }
         Remote = {     # Set either `Local` or `Remote', not both
            HttpURI =  {
               Service = {
                  Name = "<name of the upstream service>"
                  Namespace = "<Consul namespace containing the upstream service>"
                  Partition = "<Consul partition containing the upstream service>"
               }
               URI = "<URI of the plugin data>"
               Timeout = "1s"
            SHA256 = "<SHA256 for verifying the remote data>"
            RetryPolicy = {
                  RetryBackOff = {
                     BaseInterval = "1s"
                     MaxInterval = "10s"
                  }
                  NumRetries = -1
               }
            }
      Configuration = "<configuration passed to plugin on VM startup>"
      EnvironmentVariables = {
         HostEnvKeys = [
            <"keys">
         ]
         KeyValues = {
            [
               <"key = value">
            ]
         }
      }
   Configuration = "<configuration passed to plugin on plugin startup>"
   CapabilityRestrictionConfiguration = {
      AllowedCapabilities = {
         "fd_read"        = {}
         "fd_seek"        = {}
         "environ_get"    = {}
         "clock_get_time" = {}
      }
   }
}

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

Default: None
This field is required.
Data type is one of the following string values:
- tcp
- http

`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

Default: None
This field is required.
Data type is one of the following string values:
- inbound
- outbound

`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 Contexts.

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

Default: v8
Data type is one of the following string 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:
- Local
- Remote

`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. The Filename 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 Envoy 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.	Map of string keys and values	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. The AllowedCapabilities 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.


Kind = "service-defaults"
Name = "db"
Protocol = "tcp"
EnvoyExtensions = [
  {
    Name      = "builtin/wasm"
    Required  = true
    Arguments = {
      Protocol = "tcp"
      ListenerType = "inbound"
      PluginConfig = {
        VmConfig = {
          Code = {
            Local = {
              Filename = "file:///consul/extensions/sqli.wasm"
            }
          }
        }
        Configuration = <<EOF
{
  "key": "value"
}
EOF
      }
    }
  }
]

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.

Kind   = "proxy-defaults"
Name   = "global"
EnvoyExtensions = [
  {
    Name      = "builtin/wasm"
    Arguments = {
      Protocol = "http"
      ListenerType = "inbound"
      PluginConfig = {
        VmConfig = {
          Code = {
            Remote = {
              HttpURI = {
                URI     = "https://extension-server/waf.wasm"
                Timeout = "3s"
              }
              SHA256 = "ef57657e..."
            }
          }
        }
        Configuration = "..."
      }
    }
  }
]