consul/website/content/docs/connect/proxies/envoy-extensions/usage/wasm.mdx

---
layout: docs
page_title: Run WebAssembly plug-ins in Envoy proxy
description: Learn how to use the Consul wasm extension for Envoy, which directs Consul to run your WebAssembly (Wasm) plugins for Envoy proxies in your service mesh.
---


# 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](https://webassembly.org/) 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). 

<Tabs>
<Tab heading="HCL" group="hcl">
<CodeBlockConfig filename="wasm-extension-serve-waf.hcl">

```hcl
Kind = "service-defaults"
Name = "api"
Protocol = "http"
EnvoyExtensions = [
  {
    Name = "builtin/wasm"
    Arguments = {
      Protocol = "http"
      ListenerType = "inbound"
      PluginConfig = {
        VmConfig = {
          Code = {
            Remote = {
              HttpURI = {
                Service = {
                  Name = "file-server"
                }
                URI = "https://file-server/waf.wasm"
              }
              SHA256  = "c9ef17f48dcf0738b912111646de6d30575718ce16c0cbde3e38b21bb1771807"
            }
          }
        }
      Configuration =  <<EOF
{
  "rules": [
    "Include @demo-conf",
    "Include @crs-setup-demo-conf",
    "SecDebugLogLevel 9",
    "SecRuleEngine On",
    "Include @owasp_crs/*.conf"
  ]
}
EOF
      }
    }
  }
]
```
</CodeBlockConfig>
</Tab>
<Tab heading="JSON" group="json">
<CodeBlockConfig filename="wasm-extension-serve-waf.json">

```json
{
	"kind": "service-defaults",
	"name": "api",
	"protocol": "http",
	"envoyExtensions": [{
		"name": "builtin/wasm",
		"arguments": {
			"protocol": "http",
			"listenerType": "inbound",
			"pluginConfig": {
				"VmConfig": {
					"Code": {
						"Remote": {
							"HttpURI": {
								"Service": {
									"Name": "file-server"
								},
								"URI": "https://file-server/waf.wasm"
							}
						}
					}
				},
				"Configuration": {
					"rules": [
						"Include @demo-conf",
						"Include @crs-setup-demo-conf",
						"SecDebugLogLevel 9",
						"SecRuleEngine On",
						"Include @owasp_crs/*.conf"
					]
				}

			}
		}
	}]
}
```


</CodeBlockConfig>
</Tab>
<Tab heading="YAML" group="yaml">
<CodeBlockConfig filename="wasm-extension-serve-waf.yaml">

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
  name: api
spec:
  protocol: http
  envoyExtensions:
    - name: builtin/wasm
      required: true
      arguments:
        protocol: http
        listenerType: inbound
        pluginConfig:
          VmConfig:
            Code:
              Remote:
                HttpURI:
                  Service:
                    Name: file-server
                    URI: https://file-server/waf.wasm
          Configuration:
            rules:
            - Include @demo-conf
            - Include @crs-setup-demo-conf
            - SecDebugLogLevel 9
            - SecRuleEngine On
            - Include @owasp_crs/*.conf
```

</CodeBlockConfig>
</Tab>
</Tabs>


Refer to the [Wasm extension configuration reference](/consul/docs/connect/proxies/envoy-extensions/configuration/wasm) for details on how to configure the extension. 

Refer to the [proxy defaults configuration entry reference](/consul/docs/connect/config-entries/proxy-defaults) and [service defaults configuration entry reference](/consul/docs/connect/config-entries/service-defaults) 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.

<Tabs>
<Tab heading="HCL" group="hcl">

```shell-session
$ consul config write wasm-extension-serve-waf.hcl
```

</Tab>
<Tab heading="JSON" group="json">

```shell-session
$ consul config write wasm-extension-serve-waf.json
```

</Tab>
<Tab heading="Kubernetes" group="kubernetes">

```shell-session
$ kubectl apply wasm-extension-serve-waf.yaml
```

</Tab>
</Tabs>