Run WebAssembly plug-ins in Envoy proxy

This topic describes how to use the wasm extension, which directs Consul to run your WebAssembly (Wasm) plug-ins for Envoy proxies.

Workflow

You can create Wasm plugins for Envoy and integrate them using the wasm extension. Wasm is a binary instruction format for stack-based virtual machines that has the potential to run anywhere after it has been compiled. Wasm plug-ins run as filters in a service mesh application’s sidecar proxy.

The following steps describe the process of integrating Wasm plugins:

  • Create your Wasm plugin. You must ensure that your plugin functions as expected. Refer to the WebAssembly website for information and links to documentation.
  • Configure an EnvoyExtensions block in a service defaults or proxy defaults configuration entry.
  • Apply the configuration entry.

Add the EnvoyExtensions

Add Envoy extension configuration to a proxy defaults or service defaults configuration entry. Place the extension configuration in an EnvoyExtensions block in the configuration entry.

  • When you configure Envoy extensions on proxy defaults, they apply to every service.
  • When you configure Envoy extensions on service defaults, they apply to a specific service.

Consul applies Envoy extensions configured in proxy defaults before it applies extensions in service defaults. As a result, the Envoy extension configuration in service defaults may override configurations in proxy defaults.

In the following example, the extension uses an upstream service named file-server to serve a Wasm-based web application firewall (WAF).

Run WebAssembly plug-ins in Envoy proxies - 图1

wasm-extension-serve-waf.hcl

  1. Kind = "service-defaults"
  2. Name = "api"
  3. Protocol = "http"
  4. EnvoyExtensions = [
  5.   {
  6.     Name = "builtin/wasm"
  7.     Arguments = {
  8.       Protocol = "http"
  9.       ListenerType = "inbound"
  10.       PluginConfig = {
  11.         VmConfig = {
  12.           Code = {
  13.             Remote = {
  14.               HttpURI = {
  15.                 Service = {
  16.                   Name = "file-server"
  17.                 }
  18.                 URI = "https://file-server/waf.wasm"
  19.               }
  20.               SHA256  = "c9ef17f48dcf0738b912111646de6d30575718ce16c0cbde3e38b21bb1771807"
  21.             }
  22.           }
  23.         }
  24.       Configuration =  <<EOF
  25. {
  26.   "rules": [
  27.     "Include @demo-conf",
  28.     "Include @crs-setup-demo-conf",
  29.     "SecDebugLogLevel 9",
  30.     "SecRuleEngine On",
  31.     "Include @owasp_crs/*.conf"
  32.   ]
  33. }
  34. EOF
  35.       }
  36.     }
  37.   }
  38. ]

Run WebAssembly plug-ins in Envoy proxies - 图2

wasm-extension-serve-waf.json

  1. {
  2.     "kind": "service-defaults",
  3.     "name": "api",
  4.     "protocol": "http",
  5.     "envoyExtensions": [{
  6.         "name": "builtin/wasm",
  7.         "arguments": {
  8.             "protocol": "http",
  9.             "listenerType": "inbound",
  10.             "pluginConfig": {
  11.                 "VmConfig": {
  12.                     "Code": {
  13.                         "Remote": {
  14.                             "HttpURI": {
  15.                                 "Service": {
  16.                                     "Name": "file-server"
  17.                                 },
  18.                                 "URI": "https://file-server/waf.wasm"
  19.                             }
  20.                         }
  21.                     }
  22.                 },
  23.                 "Configuration": {
  24.                     "rules": [
  25.                         "Include @demo-conf",
  26.                         "Include @crs-setup-demo-conf",
  27.                         "SecDebugLogLevel 9",
  28.                         "SecRuleEngine On",
  29.                         "Include @owasp_crs/*.conf"
  30.                     ]
  31.                 }
  33.             }
  34.         }
  35.     }]
  36. }

Run WebAssembly plug-ins in Envoy proxies - 图3

wasm-extension-serve-waf.yaml

  1. kind: service-defaults
  2. name: api
  3. protocol: http
  4. envoyExtensions:
  5.   - name: builtin/wasm
  6.     required: true
  7.     arguments:
  8.       protocol: http
  9.       listenerType: inbound
  10.       pluginConfig:
  11.         VmConfig:
  12.           Code:
  13.             Remote:
  14.               HttpURI:
  15.                 Service:
  16.                   Name: file-server
  17.                   URI: https://file-server/waf.wasm
  18.          Configuration:
  19.            rules:
  20.            - Include @demo-conf
  21.            - Include @crs-setup-demo-conf
  22.            - SecDebugLogLevel 9
  23.            - SecRuleEngine On
  24.            - Include @owasp_crs/*.conf

Refer to the Wasm extension configuration reference for details on how to configure the extension.

Refer to the proxy defaults configuration entry reference and service defaults configuration entry reference for details on how to define the configuration entries.

Warning: Adding Envoy extensions default proxy configurations may have unintended consequences. We recommend configuring EnvoyExtensions in service defaults configuration entries in most cases.

Apply the configuration entry

If your network is deployed to virtual machines, use the consul config write command and specify the proxy defaults or service defaults configuration entry to apply the configuration. For Kubernetes-orchestrated networks, use the kubectl apply command. The following example applies the extension in a proxy defaults configuration entry.

  1. $ consul config write wasm-extension-serve-waf.hcl
  1. $ consul config write wasm-extension-serve-waf.json
  1. $ kubectl apply wasm-extension-serve-waf.yaml