●Change8

Migrating to Envoy v1.38.0

Version v1.38.0 introduces 5 breaking changes. This guide details how to update your code.

Released: 4/23/2026

5
Breaking Changes
9
Migration Steps
62
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

tcp_proxymax_early_data_bytesupstream_connect_modeon_demand filterenvoy.reloadable_features.on_demand_cluster_no_recreate_streamBoringSSL/FIPS--define=boringssl=fips--config=boringssl-fipsenforce_rsa_key_usageext_procprocessing_effect_libextensions/filters/http/ext_procextensions/filters/common/processing_effectroute()clusterInfo()virtualHost()OptRef<const T>*SharedPtr()x-forwarded-client-cert (XFCC)envoy.filters.http.sse_to_metadataenvoy.content_parsers.jsonenvoy.filters.http.file_serverext_authzshadow_modestatus_on_errorOAuth2TLS_CLIENT_AUTHOauthExpiresoauth2_encrypt_tokensdisable_token_encryptionRBAC header matcher%DOWNSTREAM_PEER_ISSUER_FINGERPRINT_256%%DOWNSTREAM_PEER_ISSUER_SERIAL%OpenSSLHTTP/3 (QUIC)SPAN_IDQUERY_PARAMSUPSTREAM_LOCAL_CLOSE_REASONDOWNSTREAM_LOCAL_CLOSE_REASONUPSTREAM_DETECTED_CLOSE_TYPEDOWNSTREAM_DETECTED_CLOSE_TYPE%UPSTREAM_HOSTS_ATTEMPTED%%FILE_CONTENT(...)%SECRET(name)%*_WITHOUT_PORTMASK_PREFIX_LENx-envoy-degradedRedis ClusterLOCAL_ZONE_AFFINITYLOCAL_ZONE_AFFINITY_REPLICAS_AND_PRIMARYupstream_rq_active_overflowODCDSADSSRDSdrop_overloadEDS metadata comparisonORCA weight manageris_negative_hitshits_addendRemoteAddressMatchx-ratelimit-*timeout: 0s

Breaking Changes

●Issue #1

The tcp_proxy configuration now requires explicit setting of `max_early_data_bytes` when `upstream_connect_mode` is not `IMMEDIATE`; missing configurations cause startup validation failure.

●Issue #2

The on-demand filter no longer performs internal redirects after a successful CDS fetch, meaning earlier filters are not invoked twice. This behavior can be reverted using the runtime feature `envoy.reloadable_features.on_demand_cluster_no_recreate_stream`.

●Issue #3

The `--define=boringssl=fips` Bazel flag for building BoringSSL/FIPS has been removed; users must now use `--config=boringssl-fips`.

●Issue #4

The `enforce_rsa_key_usage` option now defaults to `true` for TLS contexts (both upstream and implicitly for general TLS configuration). This option will be removed in the next release.

●Issue #5

The location of the external processing filter library (`processing_effect_lib`) has moved from `extensions/filters/http/ext_proc` to `extensions/filters/common/processing_effect`.

Migration Steps

  1. 1
    If using `upstream_connect_mode` other than `IMMEDIATE` in `tcp_proxy`, ensure `max_early_data_bytes` is explicitly configured.
  2. 2
    If relying on the on-demand filter to invoke earlier filters twice after CDS fetch, enable the runtime feature `envoy.reloadable_features.on_demand_cluster_no_recreate_stream`.
  3. 3
    Replace the Bazel flag `--define=boringssl=fips` with `--config=boringssl-fips` when building FIPS-enabled binaries.
  4. 4
    Review configurations using `enforce_rsa_key_usage` as it now defaults to `true` on upstream TLS contexts; explicitly set it to `false` if required, knowing it will be removed next release.
  5. 5
    Update dynamic module code referencing `processing_effect_lib` path from `extensions/filters/http/ext_proc` to `extensions/filters/common/processing_effect`.
  6. 6
    If using OAuth2 token encryption, use the runtime guard `disable_token_encryption` to opt-out instead of the removed `oauth2_encrypt_tokens` guard.
  7. 7
    Update any code relying on concatenation-based bypasses in RBAC header matchers, as individual value validation is now enforced.
  8. 8
    Ensure query parameter mutations using `query_parameter_mutations` are correctly URL-encoded if they contain special characters.
  9. 9
    When building with OpenSSL, note that HTTP/3 (QUIC) will be disabled.

Release Summary

This release introduces extensive new capabilities for dynamic module extensibility, significant enhancements to the MCP and A2A protocols, and security hardening across TLS and authorization components. Several configuration defaults have been tightened, notably around RSA key usage enforcement.

Need More Details?

View the full release notes and all changes for Envoy v1.38.0.

View Full Changelog