Skip to content

Add a dynamic-mod-rust example (Rust dynamic module HTTP filter) #1440

Description

@phlax

Summary

This repo currently has two examples of extending Envoy with custom code, both in C++:

  • filter-cc — a statically linked in-tree filter, built with Bazel against the Envoy source
  • wasm-cc — a proxy-wasm filter

What is missing is an example of a dynamic module, which is the more common pattern for out-of-tree extensions these days. Dynamic modules are shared libraries loaded at runtime via envoy.filters.http.dynamic_modules and have an official Rust SDK (envoy-proxy-dynamic-modules-rust-sdk). We should add a dynamic-mod-rust sandbox alongside the existing two.

Proposed layout

Mirror the wasm-cc sandbox structure so it slots into the existing docs/verify tooling:

dynamic-mod-rust/
  Cargo.toml
  Cargo.lock
  src/lib.rs               # minimal HTTP filter: add a response header + append to body
  Dockerfile-proxy         # multi-stage: build the .so, copy into envoyproxy/envoy:dev
  Dockerfile-echo          # same echo backend as wasm-cc
  docker-compose.yaml
  envoy.yaml               # DynamicModuleFilter config
  example.rst
  verify.sh
  README.md
  • envoy.yaml uses envoy.filters.http.dynamic_modules with DynamicModuleFilter (dynamic_module_config.name, filter_name, filter_config as google.protobuf.Struct).
  • Dockerfile-proxy builds the module in a rust: stage and copies lib<name>.so into the Envoy image, setting ENVOY_DYNAMIC_MODULES_SEARCH_PATH accordingly.
  • verify.sh follows the same shape as wasm-cc/verify.sh (check header/body from the filter, then optionally modify → rebuild → re-check).
  • example.rst should link to the dynamic modules arch overview and the Rust SDK docs, and note that the SDK version must match the Envoy ABI version of the image being used.

No committed binaries

Unlike wasm-cc, which ships a prebuilt x86_64 .wasm in lib/, this example should not commit any built artifacts. Committing binaries is generally bad practice, and a Rust dynamic module build is lightweight enough (no Bazel, no Envoy source checkout) that it can be built as part of docker compose up --build in reasonable time. This also removes the arch-specific caveat that wasm-cc carries.

Wiring

  • Add dynamic-mod-rust to EXAMPLE_TESTS in the root BUILD so it runs with the normal envoy_examples verification. Since it builds with cargo rather than Bazel, it should not need to be added to the _verify_build.yml matrix, and no MODULE.bazel / root bazel_dep is required.
  • :configs and docs_rst globs should pick up envoy.yaml and example.rst automatically.
  • Consider adding a cargo ecosystem entry for dynamic-mod-rust/ to .github/dependabot.yaml.

References

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions