envoyextensions

The github.com/hashicorp/consul/envoyextensions module is the public framework for in-process Envoy resource modifications, plus the bundled extensions Consul ships and the shared Envoy version metadata used by the rest of the codebase.

Sub-packages

envoyextensions/
├── extensioncommon/       # Shared types: extension interface, runner, builder helpers
├── xdscommon/             # Envoy version compatibility, supported version metadata, helpers
└── (root has go.mod / go.sum)

There are also extensions inside the root module under agent/envoyextensions/ and agent/xds/extensionruntime/ that import this module to participate in the runtime.

extensioncommon

extensioncommon defines the Extension interface that every extension implements:

type Extension interface {
    PatchClusters(api.ClusterPayload) (api.ClusterPayload, error)
    PatchListeners(api.ListenerPayload) (api.ListenerPayload, error)
    PatchRoutes(api.RoutePayload) (api.RoutePayload, error)
    // ... and matching predicates
}

The runner walks a snapshot's resource set and gives every registered extension a chance to mutate clusters, listeners, routes, and secrets. Built-in extensions and operator-supplied extensions both flow through this interface.

xdscommon

xdscommon holds Envoy version compatibility:

• ENVOY_VERSIONS — text file listing every supported Envoy version. Read by the Makefile to pick the latest for builds and by the agent at runtime to refuse newer/older Envoys.
• EnvoyVersion parsing/comparison helpers.
• Common naming helpers used by both the xDS server and external test harnesses (e.g., consul-k8s).

Bundled extensions

The actual extension implementations live in the root module under agent/envoyextensions/builtinextensions/:

Extension	Purpose
aws-lambda	Treat an AWS Lambda function as a mesh service
awsauth	Sign requests with AWS SigV4 before they leave the mesh
lua	Apply a Lua filter to one or more listeners
otelaccesslogging	OTEL-format access logs
propertyoverride	Patch arbitrary fields on generated Envoy resources (escape hatch)
extauthz	External authorization filter
wasm	Wasm filter wiring

Operators reference extensions via service-defaults.envoy_extensions in a config entry. The runtime in agent/xds/extensionruntime/ invokes them per snapshot.

Module boundary

This module is intentionally narrow. It exposes the interfaces and Envoy version metadata publicly, but the bundled extensions stay in the root module so they can use private agent helpers. External projects that want to write a Consul extension implement extensioncommon.Extension, register it via the agent's plugin mechanism, and ship a separate binary (or fork the agent).

Integration points

• Service defaults — operators attach a list of extensions to a service via service-defaults.
• xDS server — calls into the runtime in agent/xds/extensionruntime/ after building base resources, before serializing.
• Envoy version checks — xdscommon.SupportedVersions() is consulted by the xDS server's bootstrap negotiation.

Entry points for modification

• Add a new bundled extension: implement extensioncommon.Extension and register it in agent/envoyextensions/builtinextensions/.
• Bump supported Envoy versions: edit envoyextensions/xdscommon/ENVOY_VERSIONS. The Makefile and runtime read it at build / start time.
• Reshape the extension API: extensioncommon is public. Major changes need backwards compatibility shims and coordination with consul-k8s.