You are browsing unreleased documentation. See the latest documentation here.

WebAssembly

WebAssembly in Kong

In addition to Lua plugins, Kong Gateway supports WebAssembly as a means of extending proxy functionality and performing custom business logic. This is made possible by Kong’s open source implementation of the Proxy-Wasm specification.

Concepts

Filter

In the context of Proxy-Wasm, a “filter” refers to a specific component or module that is executed at some stage of request/response handling. Filters can perform actions like:

read or write request or response headers
read or write the request or response body
terminate the request early and send a self-generated response

If you are familiar with Kong’s Lua plugin support, you can think of filters as semi-analogous to plugins.

Filters differ from Lua plugins in their file format at runtime. A Lua plugin typically spans several different Lua source code files, all packaged and deployed in text format. Filters must be compiled from source code into a single binary file with the .wasm extension.

In order to be usable in Kong Gateway, all filter files must be present on disk in a single directory, denoted by the wasm_filters_path configuration directive.

Filter Chain

A Filter Chain is the database entity representing one or more filters executed for each request to a particular service or route, each one with its configuration.

Example:

---
filter_chains:
  name: my-filter-chain
  # Filter Chains can be toggled on/off for testing
  enabled: true
  filters:
    # this maps to $wasm_filters_path/my_filter.wasm
    - name: my_filter
      # at runtime, configuration is passed to the filter as a byte array
      #
      # filter configuration is inherently untyped--schema and
      # encoding/serialization are left up to the filter code itself
      config: "foo=bar baz=bat"

    - name: my_other_filter
      # individual filters within a chain can be toggled on/off for testing
      enabled: false
      config: >-
          {
            "some_settings": {
              "a": "b",
              "c": "d"
            },
            "foo": "bar"
          }

    # the same filter may occur more than once in a single chain, and all   entries will be
    # executed
    - name: my_filter
      config: "foo=123 baz=456"

Relationships

Filter Chains must be linked to a service or route, and as of Kong Gateway version 3.4, the relationship is one-to-one:

A service or route may only be linked to a single Filter Chain.
A Filter Chain may only be linked to a single service or route.

Filter execution behavior

The list of filters that will be executed for a given request is determined during the access phase, after Lua plugins execution. If the service entity for the request is linked to a Filter Chain, the filters are executed. If the route entity that was matched to the request is linked to a Filter Chain, its filters are also executed, after service-related filters (if any) have been executed. You can inspect the full filter execution plan for a given route via the Admin API, through the endpoint /routes/{route_name_or_id}/filters/enabled.

Filters are always executed in the order in which they are defined in the filter chain. The same filter may appear in the execution plan multiple times, either coming from the service and route chains, or even within the same Filter Chain. Each entry will execute with its own configuration.

Can Lua plugins and Proxy-Wasm filters be used at the same time?

Yes. Keep in mind though that for each request phase, Lua plugins are executed before Wasm filters.

There is one side effect of this ordering that is crucial to be aware of: if a Lua plugin terminates the request during or prior to the access phase (by throwing an exception or explicitly sending a response with kong.response.exit() or other PDK function), no Wasm filters will be executed for the request, including other phases (e.g. header_filter).

Limitations and known issues

Kong PDK

At the time of this writing, filters do not have access to any of Kong’s Lua-land PDK utilities and are restricted to the functionality defined by Proxy-Wasm.

Filter configuration schema

Filter configuration is untyped. That means that Kong cannot validate a filter configuration ahead of time, e.g. when you create a Filter Chain instance using the Admin API. This is not so much a limitation of Kong’s implementation as it is a limitation of the Proxy-Wasm specification itself.

Proxy-Wasm functionality

The Proxy-Wasm specification is relatively new and still evolving. Some behaviors of the specification may not yet be fully-implemented. Additionally, there may be some behavioral discrepancies between Kong Gateway and other Proxy-Wasm implementations.

Please refer to the ngx_wasm_module Proxy-Wasm documentation for more details.