status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/docs/connect/proxies/envoy-extensions/configuration/wasm.mdx

485 lines
19 KiB
Plaintext
Raw Blame History

---
layout: docs
page_title: WebAssembly extension configuration reference
description: Learn how to configure the wasm Envoy extension, which is a builtin Consul extension that allows you to run WebAssembly plugins in Envoy proxies.
---
# 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](/consul/docs/connect/proxies/envoy-extensions/usage/wasm) 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:
- [`EnvoyExtensions` in proxy defaults](/consul/docs/connect/config-entries/proxy-defaults#envoyextensions)
- [`EnvoyExtensions` in service defaults](/consul/docs/connect/config-entries/service-defaults#envoyextensions)
Click on a property name to view additional details, including default values.
- [`Protocol`](#protocol): string
- [`ListenerType`](#listenertype): string | required
- [`ProxyType`](#proxytype): string | `connect-proxy`
- [`PluginConfig`](#pluginconfig): map | required
- [`Name`](#pluginconfig-name): string
- [`RootID`](#pluginconfig-rootid): string | required
- [`VmConfig`](#pluginconfig-vmconfig): map
- [`VmID`](#pluginconfig-vmconfig-vmid): string
- [`Runtime`](#pluginconfig-vmconfig): string | `v8`
- [`Code`](#pluginconfig-vmconfig-code): map
- [`Local`](#pluginconfig-vmconfig-code-local): map
- [`Filename`](#pluginconfig-vmconfig-code-local): string
- [`Remote`](#pluginconfig-vmconfig-code-remote): map
- [`HttpURI`](#pluginconfig-vmconfig-code-remote-httpuri): map
- [`Service`](#pluginconfig-vmconfig-code-remote-httpuri-service): map
- [`Name`](#pluginconfig-vmconfig-code-remote-httpuri-service): string
- [`Namespace`](#pluginconfig-vmconfig-code-remote-httpuri-service): string
- [`Partition`](#pluginconfig-vmconfig-code-remote-httpuri-service): string
- [`URI`](#pluginconfig-vmconfig-code-remote-httpuri-uri): string
- [`Timeout`](#pluginconfig-vmconfig-code-remote-httpuri-timeout): string
- [`SHA256`](#pluginconfig-vmconfig-code-remote-sha256): string
- [`RetryPolicy`](#pluginconfig-vmconfig-code-remote-retrypolicy): map
- [`RetryBackOff`](#pluginconfig-vmconfig-code-remote-retrypolicy-retrybackoff): map
- [`BaseInterval`](#pluginconfig-vmconfig-code-remote-retrypolicy-retrybackoff): string
- [`MaxInterval`](#pluginconfig-vmconfig-code-remote-retrypolicy-retrybackoff): string
- [`NumRetries`](#pluginconfig-vmconfig-code-remote-retrypolicy-numretries): number | `-1`
- [`Configuration`](#pluginconfig-vmconfig-configuration): string
- [`EnvironmentVariables`](#pluginconfig-vmconfig-environmentvariables): map
- [`HostEnvKeys`](#pluginconfig-vmconfig-environmentvariables-hostenvkeys): list of strings
- [`KeyValues`](#pluginconfig-vmconfig-environmentvariables-keyvalues): map
- [`Configuration`](#pluginconfig-configuration): string
- [`CapabilityRestrictionConfiguration`](#pluginconfig-vmconfig-capabilityrestrictionconfiguration): map
- [`AllowedCapabilities`](#pluginconfig-vmconfig-capabilityrestrictionconfiguration): map of strings
## Complete configuration
When all parameters are set for the extension, the configuration has the following form:
```hcl
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:
- [`Name`](#pluginconfig-name)
- [`RootID`](#pluginconfig-rootid)
- [`VmConfig`](#pluginconfig-vmconfig)
- [`Configuration`](#pluginconfig-configuration)
- [`CapabilitiesRestrictionConfiguration`](#pluginconfig-capabilitiesrestrictionconfiguration)
#### 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:
- [`VmID`](#pluginconfig-vmconfig-vmid)
- [`Runtime`](#pluginconfig-vmconfig-runtime)
- [`Code`](#pluginconfig-vmconfig-code)
- [`Configuration`](#pluginconfig-vmconfig-configuration)
- [`EnvironmentVariables`](#pluginconfig-vmconfig-environmentvariables)
#### 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:
- `v8`
- `wastime`
- `wamr`
- `wavm`
### `PluginConfig{}.VmConfig{}.Code{}`
Map containing one of the following configuration parameters:
- [`Local`](#pluginconfig-vmconfig-code-local)
- [`Remote`](#pluginconfig-vmconfig-code-local)
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`](#pluginconfig-vmconfig-code-local)
- [`Remote`](#pluginconfig-vmconfig-code-local)
### `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:
- [`HttpURI`](#pluginconfig-vmconfig-code-remote-httpuri)
- [`SHA256`](#pluginconfig-vmconfig-code-remote-sha256)
- [`RetryPolicy`](#pluginconfig-vmconfig-code-remote-retrypolicy)
#### 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:
- [`Service`](#pluginconfig-vmconfig-code-remote-httpuri-service)
- [`URI`](#pluginconfig-vmconfig-code-remote-httpuri-uri)
- [`Timeout`](#pluginconfig-vmconfig-code-remote-httpuri-uri)
#### 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` | <EnterpriseAlert inline/> Specifies the Consul namespace that the upstream service belongs to. | String | `default` |
| `Partition` | <EnterpriseAlert inline/> 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:
- [`RetryBackoff`](#pluginconfig-vmconfig-code-remote-retrypolicy)
- [`NumRetries`](#pluginconfig-vmconfig-code-remote-numretries)
#### 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](https://github.com/proxy-wasm/spec/tree/cefc2cbab70eaba2c187523dff0b38fce2f90771/abi-versions/vNEXT#proxy_on_vm_start) 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. | <nobr>Map of </nobr>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](https://github.com/proxy-wasm/spec/tree/cefc2cbab70eaba2c187523dff0b38fce2f90771/abi-versions/vNEXT#proxy_on_configure) 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](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/wasm/v3/wasm.proto#extensions-wasm-v3-capabilityrestrictionconfig) 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](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/wasm/v3/wasm.proto#extensions-wasm-v3-capabilityrestrictionconfig) 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.
```hcl
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.
```hcl
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 = "..."
}
}
}
]
```
Reference in New Issue View Git Blame Copy Permalink