API versioning

The Envoy / xDS API is one of the most stable parts of the project. The rules are codified in api/API_VERSIONING.md. This page summarises them.

Package layout

Every Envoy API proto lives directly in a versioned namespace:

envoy.config.bootstrap.v3.Bootstrap
envoy.service.cluster.v3.ClusterDiscoveryService
envoy.extensions.filters.http.router.v3.Router

Subpackages such as envoy.service.trace.v3.somethingelse are not allowed. The major version (v3) is part of the proto package and the directory layout under api/envoy/.

When people say "the v3 API" they mean the major version of the root configuration resources (Bootstrap, Cluster, Listener, etc.). Within v3, dependencies may transitively pull in earlier majors of unrelated packages.

Policy: never break v3

Within a major version, the Envoy project does not allow:

• Renumbering fields.
• Changing field types.
• Renaming fields or packages.
• Promoting a singleton to repeated.
• Wrapping an existing field in oneof.
• Tightening protoc-gen-validate constraints.

Wire format compatibility is not enough — YAML / JSON / text-proto compatibility is also a hard requirement, because every of those formats are first-class config inputs.

Exceptions

Three narrow carve-outs let new fields be reshaped:

1. Within 14 days of introduction, before the field has shipped in a stable Envoy release.
2. vNalpha packages are unstable by design.
3. Protos annotated work_in_progress (via udpa.annotations.file_status or xds.annotations.v3.*_status) are unstable.

v3 is the final major version

At one point the project planned periodic major bumps. The plan was abandoned: the ecosystem (Envoy, gRPC, all the control planes) is too large. v3 is the permanent major version. Deprecations still happen — they signal a preferred configuration path — but the deprecated field's implementation is never removed from Envoy.

Client implementations may output additional deprecation warnings or refuse to support a field if continued use becomes a security risk. But Envoy itself, as an xDS client, commits to never removing support.

This is a major contract — it lets management servers count on every field they ever deployed continuing to work.

How to add a new field

1. Add the field to the current stable major version (v3), not to a new vNalpha.
2. If the field shadows an existing one, document the deprecation and add a runtime guard (a RUNTIME_GUARD that defaults to true). See runtime.
3. Bump the proto in api/envoy/<area>/v3/.
4. Run the API consistency tooling: bazel test //tools/api_proto_breaking_change_detector/....
5. Add a release note in changelogs/current.yaml.

Deprecating a field

The runtime feature envoy.deprecated_features.<feature_name> defaults to false; the deprecated field's use bumps runtime.deprecated_feature_use. The deprecation is announced in changelogs/current.yaml with a "deprecated" entry and a target version for warning escalation. A field is only "soft-removed" — its handling moves behind a runtime gate; the proto definition stays.

Client features

Some new behaviours need a way for the server to know the client supports them. Client features (envoyproxy.io client_features) are a published list of opt-in capabilities the client advertises. The control plane checks the list and adapts.

Versioning of extension protos

Each extension config proto is versioned independently — for example, the Router filter is at envoy.extensions.filters.http.router.v3.Router, but the IpTagging filter has its own v3 in envoy.extensions.filters.http.ip_tagging.v3.IPTagging. Adding a new extension does not require touching root resources.

xDS shared with gRPC

Many of the xDS protos are shared with the gRPC project under the cncf/xds repo (api/xds/). The same versioning rules apply, and changes go through the xDS working group.

See also

• Extension policy — how extension protos are reviewed.
• xDS configuration — the protocol that uses these versions.
• Development workflow — practical PR steps for API changes.