envoyproxy/envoy

envoy-contrib

envoy-contrib is a build of Envoy that includes the in-tree extensions plus the third-party / experimental / restricted-licence extensions in contrib/. It is the binary you want when you need a contrib extension; otherwise prefer envoy-static.

Bazel target

//contrib/exe:envoy-static

The build entry is in contrib/exe/. It re-uses the same source/exe/main.cc but links in CONTRIB_EXTENSIONS from contrib/contrib_build_config.bzl.

Why a separate build?

contrib/ holds extensions that don't meet the extension policy's "in-tree" bar. Reasons include:

External dependencies that aren't acceptable for envoy-static (e.g. golang, vcl, hyperscan, dlb, qat, kae, cryptomb).
Vendor-specific functionality (Istio metadata-exchange, Datadog, Hyperscan).
Licence concerns that prevent inclusion in the canonical binary.
Maintainer-by-vendor rather than the core Envoy maintainer team.
Experimental / not-yet-ready-for-core extensions.

A contrib extension is held to lower stability and review bars; users opt in by running envoy-contrib.

Notable contrib extensions

Extension	Path	What it does
`envoy.filters.http.golang`, `envoy.filters.network.golang`	`contrib/golang/`	Run cgo-bridged Go filters. Big in the cloud-native ecosystem.
`envoy.filters.network.kafka_broker`, `envoy.filters.network.kafka_mesh`	`contrib/kafka/`	Kafka protocol awareness; mesh routes Kafka traffic.
`envoy.filters.network.postgres_proxy`	`contrib/postgres_proxy/`	PostgreSQL wire-protocol observability.
`envoy.filters.network.mysql_proxy`	`contrib/mysql_proxy/`	MySQL wire-protocol observability.
`envoy.filters.network.rocketmq_proxy`	`contrib/rocketmq_proxy/`	Apache RocketMQ.
`envoy.filters.network.sip_proxy`	`contrib/sip_proxy/`	SIP.
`envoy.filters.http.peer_metadata`, `envoy.filters.network.metadata_exchange`, `envoy.filters.http.istio_stats`	`contrib/istio/`	Istio plumbing.
`envoy.filters.http.checksum`, `envoy.filters.http.dynamo`, `envoy.filters.http.peak_ewma`, `envoy.filters.http.sxg`	various	Specialised HTTP filters.
`envoy.tls.key_providers.kae`, `envoy.tls.key_providers.cryptomb`, `envoy.tls.key_providers.qat`	`contrib/kae/`, `contrib/cryptomb/`, `contrib/qat/`	Hardware-accelerated TLS private keys.
`envoy.compression.qatzip.compressor`, `envoy.compression.qatzstd.compressor`	`contrib/qat/`	Intel QuickAssist–accelerated compression.
`envoy.matching.input_matchers.hyperscan`, `envoy.regex_engines.hyperscan`	`contrib/hyperscan/`	Intel Hyperscan regex engine.
`envoy.network.connection_balance.dlb`	`contrib/dlb/`	Intel DLB connection balancing.
`envoy.bootstrap.vcl`	`contrib/vcl/`	VPP VCL socket interface.
`envoy.load_balancing_policies.peak_ewma`	`contrib/peak_ewma/`	Peak-EWMA load balancing.
`envoy.tap_sinks.udp_sink`	`contrib/tap_sinks/`	Stream tap data over UDP.

The full list is in contrib/contrib_build_config.bzl.

Layout of a contrib extension

contrib/<name>/
├── README.md                 # Vendor / extension info, contacts
├── filters/<layer>/source/   # Implementation
├── filters/<layer>/test/     # Tests
└── extensions_metadata.yaml  # Maturity, security posture, owners

Authors are typically the vendor of the dependency or a champion outside the core maintainer team. Each extension has its own CODEOWNERS entry pointing to the maintainer responsible for it.

Adding to contrib

The criteria are looser than for source/extensions/, but the structure is the same:

New directory contrib/<name>/.
Proto under api/contrib/envoy/extensions/... (or api/envoy/extensions/... if shared schema).
Register in contrib_build_config.bzl.
Tests under contrib/<name>/.../test/.
A README explaining the dependency and constraints.
An entry in contrib/extensions_metadata.yaml.

See the extension policy for the full criteria.

Security stance

Contrib extensions are not covered by the Envoy security team's hardening guarantees. Vulnerabilities are reported through the same channel but the response is best-effort. Operators using contrib extensions should be aware that some are vendor-supported only.

Distribution

The release pipeline produces a parallel envoyproxy/envoy-contrib Docker image and binary at every release. Same versioning, same release cadence.