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.

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.

ExtProc extensions

ExtProc extensions are Envoy External Processing gRPC servers that run outside the main Envoy process. The gRPC offers methods to manipulate the request and response metadata and payloads, but is much more complex to use than the Dynamic Modules API.

Using ExtProc extensions introduces latency and serialization overhead, but it is a good approach for extensions that are preferred to run outside the main Envoy process to make sure the extension code cannot affect the Envoy main process.

Manifest type: ext_proc

name: my-extproc-extension
type: ext_proc
version: 0.2.2
extProc:
  grpcPort: 50051
  failureModeAllow: false
  processingMode:
    requestHeaderMode: SEND
    responseHeaderMode: SEND
    requestBodyMode: BUFFERED
    responseBodyMode: NONE

How it works

  1. Your extension implements the Envoy ExternalProcessorServer gRPC service interface.
  2. The extension is compiled into a standalone binary that is started in parallel to Envoy.
  3. Envoy is configured to forward requests and responses to the external processor server.

You can see a full example in the extensions/example-ext-proc directory.