envoy-knowledge-patch

# Envoy Proxy Knowledge Patch Load this skill when changing Envoy configuration, extending Envoy, or investigating behavior that may have shifted across recent releases. Start with the upgrade notes below. Then open only the topic references needed for the configuration or code under review. ## Reference index | Reference | Topics | | --- | --- | | [Upgrades, builds, and operations](references/upgrades-build-and-operations.md) | Removed guards and extensions, build toolchains, process defaults, admin controls, workers, file watching | | [HTTP routing and filters](references/http-routing-and-filters.md) | HTTP codecs, routing, matching, rewrites, filter chains, header mutation, compression, custom responses | | [Authentication and security](references/authentication-and-security.md) | OAuth2, JWT, API keys, credentials, RBAC, identity metadata, hardening | | [External processing and authorization](references/external-processing-and-authorization.md) | ext-proc, ext-authz, processor lifecycle, failure policies, mutations | | [TLS, QUIC, and networking](references/tls-quic-and-networking.md) | TLS, certificates, QUIC, listeners, TCP, UDP, PROXY protocol, sockets, namespaces | | [Discovery, DNS, and load balancing](references/discovery-dns-and-load-balancing.md) | xDS, SDS, RDS, resolvers, DNS caches, clusters, endpoints, host and LB selection | | [Extensions, Lua, Wasm, and dynamic modules](references/extensions-lua-wasm-and-modules.md) | Extension APIs, Lua, Wasm, Go plugins, composite filters, native modules | | [Observability and formatting](references/observability-and-formatting.md) | Access logs, formatters, tracing, metrics, taps, exporters, diagnostics | | [Resilience, rate limits, and overload](references/resilience-rate-limits-and-overload.md) | Rate limits, retries, overload actions, resource monitors, health checks, outlier detection | | [Application protocols and data filters](references/application-protocols-and-data-filters.md) | Redis, Valkey, PostgreSQL, MySQL, gRPC, GeoIP, Thrift, SSE, MCP | ## Upgrade blockers and irreversible migrations ### Do not rely on expired rollback guards Many behavior changes initially shipped with runtime guards and later removed their legacy paths. Before prescribing a rollback, check [upgrades-build-and-operations.md](references/upgrades-build-and-operations.md) for the guard's removal and then check the owning topic reference. In particular: - Explicit internal-address behavior became mandatory after its rollback guard was removed. Configure `internal_address_config`; do not assume RFC1918 addresses are internal. - The old HTTP/2 propagation, streaming-shadow, RDS normalization, xDS-copy, and empty-host dynamic-forward-proxy paths have also lost their rollback guards. - OAuth2 cookie encryption can no longer be disabled with `envoy.reloadable_features.oauth2_encrypt_tokens`; only the filter's explicit trusted-environment plaintext mode remains. - The old TCP-proxy idle-timer behavior is gone. ### Remove deleted extensions before startup Configuration still naming a removed extension fails at load time. - Replace the deleted `grpc_credentials/aws_iam` extension. - Remove the contrib Squash HTTP filter. - Remove OpenCensus tracing configuration. - Review every removed-runtime-control list before copying old runtime files. ### Update source-build automation - Build extension code as C++20. - Use the supported compiler configurations instead of the removed `clang-libstdc++` setup. - Use `--config=boringssl-fips` for FIPS builds. - Bazel 8 source builds retain WORKSPACE mode only with `--enable_workspace --noenable_bzlmod`; account for the changed external runfiles layout. - Treat `--config=openssl` as a constrained build: it disables HTTP/3 and is outside the stated security-policy coverage. ### Treat TLS enforcement as mandatory Peer RSA certificate `keyUsage` is always enforced. The old `enforce_rsa_key_usage` option is ignored, so fix incompatible certificates instead of trying to turn validation off. Also account for TLS Inspector's ClientHello version checks and the rejection of empty trusted-CA material. ## Security-critical configuration checks ### Migrate OAuth2 cookies in the safe order For the AES-256-GCM migration: 1. Enable `envoy.reloadable_features.oauth2_use_gcm_encryption`. 2. Wait until every instance can read `gcm.` cookies. 3. Confirm `oauth_legacy_cbc_decrypt` has fallen to zero. 4. Disable `envoy.reloadable_features.oauth2_legacy_cbc_decrypt_compat`. Reversing the order invalidates newly issued cookies. Leaving CBC fallback enabled retains the vulnerable path. Review the full OAuth2 sequence in [authentication-and-security.md](references/authentication-and-security.md). ### Bound dynamic-forward-proxy destinations Use `DnsCacheConfig.resolved_address_filter` to remove disallowed CIDR ranges from DNS answers. For defense in depth, apply the upstream RBAC filter after host selection and default-deny unwanted `upstream_ip_port` values. ### Avoid disclosing transport failures Do not restore upstream transport failure details to downstream response bodies. Diagnose with `%UPSTREAM_TRANSPORT_FAILURE_REASON%` in controlled logs instead. ### Recheck repeated-header policy `HeaderMatcher` evaluates separately encoded header values individually. CEL and generic matcher inputs still see comma-joined values. Audit policy that depended on joined strings. ## High-impact default changes ### Size HTTP/2 explicitly Safer HTTP/2 defaults cap concurrent streams at `1024`, the initial stream window at `16MiB`, and the connection window at `24MiB`. Set intentional values after measuring workload needs instead of retaining the temporary legacy-default guard. Cookie reassembly participates in request-header limits. A separate cookie limit and an nghttp2 Rapid Reset token bucket are configurable. ### Review parser and protocol limits - HTTP Inspector uses Balsa by default. - JSON parsing is capped at 1,000 nesting levels. - Oversized combined PROXY-protocol TLVs are removed. - HTTP/3 pseudo-headers are validated. - Strict HTTP/1 chunk parsing remains opt-in. ### Account for effective sampling The tap filter and tap transport socket now honor `tap_enabled` before their match predicate. OpenTelemetry tracing gives Envoy's request-entry decision, including `overall_sampling`, precedence over incoming and tracer-level sampling signals. ### Revalidate worker and socket sizing Unset Linux worker concurrency considers hardware threads, CPU affinity, and cgroup CPU limits. io_uring now applies default write-watermark backpressure. Use worker CPU affinity and listener CPU-locality balancing only after checking reuse-port and process-affinity assumptions. ## Common implementation recipes ### External processing - Choose HTTP or gRPC transport intentionally. - Select buffered, streamed, or `FULL_DUPLEX_STREAMED` body handling based on mutation and failure semantics. - Set `failure_mode_allow`, `status_on_error`, and per-route overrides deliberately. - Treat gRPC-client creation as a processor failure; fail-open no longer means silently ignoring startup failure. - When chaining processors, account for state updates and `Content-Length`. See [external processing and authorization](references/external-processing-and-authorization.md) for lifecycle, local replies, processing effects, and network controls. ### External authorization - Use per-route backend selection and retry policy where needed. - Validate mutated request and response header limits. - Bound denial bodies and decide whether denied headers may reach clients. - Use shadow mode for evaluation without enforcement. - For UDP, authorize when the session is created. ### Routing and request mutation - Refresh route or cluster selection after writing routing-relevant filter state. - Use body-aware on-demand recreation only when filters can replay safely. - Apply formatter-backed host, path, redirect, and direct-response rewrites with explicit trust boundaries. - Test matcher changes with dynamic metadata and repeated headers. - When delaying TCP route selection, set early-data and drain behavior explicitly. ### DNS and cluster selection - Prefer typed DNS-cluster configuration over deprecated direct cluster DNS fields. - Recheck resolver inheritance when a DNS cache or filter has empty local resolver configuration. - Use DNS-layer address filtering plus post-selection authorization for dynamic destinations. - Expect EDS hostname-only changes to recreate hosts and drain pools. - Use `refresh_cluster_on_retry` only when a dynamically selected cluster can safely change between attempts. ### Native dynamic modules Check extension-family and callback coverage before implementing a module. Loading supports local paths and digest-verified remote artifacts; cache misses and fetch failures differ. Validate callback signatures and isolation. Use [extensions-lua-wasm-and-modules.md](references/extensions-lua-wasm-and-modules.md) for request, worker, listener, network, bootstrap, load-balancer, transport, health-check, formatter, stats-sink, and filter-state APIs. ### Rate limiting and overload - `timeout: 0s` means no timeout for HTTP rate limit and ext-authz. - A local token bucket with `max_tokens: 0` rejects every match. - Negative hits refill budget; shadow mode evaluates without enforcing. - Retry budgets can include requests from a configured interval. - Fixed-heap maximums can be runtime-adjusted. - Treat connection-pool, HTTP/2 dispatch, stream flush, idle HTTP/3, and high-watermark closures as separate load-shed mechanisms. ## Diagnostic workflow 1. Identify the owning subsystem and open its reference from the index. 2. Search the exact field, extension name, formatter, runtime guard, or stat. 3. If a guard is suggested, verify it was not removed in the upgrade reference. 4. Separate default changes from opt-in features and disabled-by-default guards. 5. For extensions, check both configuration API changes and callback ABI changes. 6. For traffic-policy changes, test request, response, retry, local-reply, and stream-close paths independently. 7. For security migrations, stage changes so every instance can read both old and new state before disabling compatibility. 8. Prefer observability fields and counters over exposing diagnostic details to downstream clients. ## Configuration review checklist - Removed fields, extensions, and runtime guards are absent. - TLS secrets are non-empty and key usage is compatible. - OAuth2 redirect domains, cookie attributes, token forwarding, and encryption migration state are explicit. - Dynamic destinations are constrained before and after DNS resolution. - Header-count, header-size, cookie, body, metadata, and JSON-depth limits are intentional. - ext-proc and ext-authz failure, timeout, retry, and shadow behavior are explicit. - Route-cache or route-cluster refresh occurs after relevant state mutation. - Listener namespaces, socket options, keepalive, and connection watermarks match the deployment platform. - Load-shed actions have corresponding metrics and capacity tests. - Access logs avoid secrets while retaining controlled transport and identity diagnostics.