Create a Proxy-Wasm filter

You are browsing documentation for an older version. See the latest documentation here.

Create a Proxy-Wasm filter

Your first Proxy-Wasm filter

Selecting a language

In order to be viable for filter development, your programming language of choice must meet the following criteria:

Supports WebAssembly as a build target
Has a Proxy-Wasm SDK

The following language SDKs are currently well-tested in Kong Gateway, making them a good choice for your first filter:

Other languages and/or Proxy-Wasm SDKs are theoretically supported but have not yet been fully tested.

Kong has made Go and Rust Proxy-Wasm filter templates available. They can be used to start writing your own filters, or to build as they are and get your first hello world-type filter:

Deploying the filter with Kong

After writing and building the filter, the next steps are to configure Kong to enable Wasm support and add the filter, then associate the filter to a route or a service. You will then be able to start Kong and issue requests that go through the filter.

Configuration

WebAssembly support must be enabled in Kong Gateway:

$ export KONG_WASM=on

Additionally, the wasm_filters_path parameter must be configured in order for Kong Gateway to load the filter at runtime. This can be any folder containing .wasm files.

During local development, when a short feedback loop is desired, you can set this parameter to your build toolchain’s output directory (wherever the compiled <filter-name>.wasm file is produced):

$ export KONG_WASM_FILTERS_PATH=/path/to/my_filter/build

Link to a Kong service and route

Now, the next step is to create a Kong Filter Chain entity using the filter created in the previous step and associate it with a Kong route or service. This will be done by creating a declarative yaml config file, e.g. kong.yml:

---
_format_version: '3.0'
services:
  - name: my-wasm-service
    url: http://httpbin.org
    routes:
      - name: my-wasm-route
        paths:
          - /
    filter_chains:
      - name: my-wasm-demo
        filters:
          - name: my_filter
            config: >-
              {
                "my_greeting": "Hello from Kong using WebAssembly!"
              }

$ export KONG_DATABASE=off
$ export KONG_DECLARATIVE_CONFIG="$PWD/kong.yml"

Start Kong

Now Kong can be started:

$ export KONG_PREFIX="$PWD/wasm-servroot"
$ kong prepare
$ kong start

And the Proxy-Wasm filter is ready to be used:

$ http --headers http://127.0.0.1:8000/
HTTP/1.1 200 OK
Connection: keep-alive
Content-Encoding: gzip
Content-Type: text/html; charset=utf-8
Date: Thu, 03 Aug 2023 19:28:27 GMT
Vary: Accept-Encoding
Via: kong/3.4.0
X-Greeting: Hello from Kong using WebAssembly!
X-Kong-Proxy-Latency: 1
X-Kong-Upstream-Latency: 342

Create a Proxy-Wasm Filter