Envoy Logo

Extension Types

Built On Envoy supports several extension types, each suited to different use cases and workflows. The type field in your extension manifest determines how your extension is packaged and loaded by Envoy.

Rust Dynamic Module Extensions

Rust extensions are compiled HTTP filters that run inside Envoy as native Dynamic Modules. They use the Rust SDK and are compiled to a C-compatible shared library that Envoy loads directly - no intermediate runtime or plugin loader is needed.

Manifest type: rust

name: my-rust-extension
version: 0.1.0
type: rust

How it Works

  1. Your extension implements the HttpFilterConfig and HttpFilter traits from the Rust SDK.
  2. The crate is compiled with cargo build --release to produce a shared library (.so on Linux, .dylib on macOS).
  3. The declare_init_functions! macro wires up the init and filter-creation entry points that Envoy expects from a dynamic module.
  4. At runtime, Envoy loads the shared library directly with no additional host module.

Getting Started with Rust Extensions

See the Writing Rust Extensions guide for a complete walkthrough of the filter API, lifecycle callbacks, and build process.

Go Extensions

Go extensions are compiled HTTP filters that run inside Envoy through the Dynamic Modules system. They offer full access to the Dynamic Modules Go SDK and support advanced operations such as metrics, body modification, metadata, and local replies.

🚧 There are some limitations related to how the Go runtime loads dependencies that affect how different Go extensions can be loaded in the same Envoy process. To overcome these, a special dynamic module is used to load the Go extensions at runtime.

Manifest type: go

name: my-extension
type: go
composerVersion: 0.2.2

The composerVersion field is required and must match the version of the Composer dynamic module (the special loader module) that will load the plugin.

How it works

  1. Your extension exports a WellKnownHttpFilterConfigFactories() function as its entry point.
  2. The extension is compiled with go build -buildmode=plugin to produce a .so file.
  3. At runtime, the Composer’s plugin loader opens the .so file and validates that it was built with the same Go version and matching dependency versions before registering its filters.

You can see a full example in the extensions/composer/example directory.

Getting Started with Go Extensions

See the Writing Go Extensions guide for a complete walkthrough of the filter API, lifecycle callbacks, and build process.

Lua Extensions

Lua extensions use Envoy’s built-in Lua HTTP filter to run scripts directly inside Envoy with no compilation step. This makes them the simplest way to get started with Built On Envoy.

Manifest type: lua

Providing the Lua Script

The lua field in your manifest defines the script source. You can either reference an external file or inline the script directly.

File reference:

name: my-lua-extension
type: lua
lua:
  path: plugin.lua

Inline script:

name: my-lua-extension
type: lua
lua:
  inline: |
    function envoy_on_request(request_handle)
      request_handle:headers():add("x-custom-header", "hello")
    end

    function envoy_on_response(response_handle)
      response_handle:headers():add("x-response-header", "world")
    end

You must provide exactly one of path or inline - not both.

When to Use Lua

Lua extensions are a good fit when you need:

  • Quick header manipulation or request routing logic
  • Simple request/response transformations without a build step
  • Rapid prototyping before investing in a compiled extension

Limitations: Lua extensions have access only to the APIs exposed by Envoy’s Lua filter. For advanced features like custom metrics, body buffering, or tight performance requirements, consider a Go extension instead.