data-plane-api: Envoy's API definitions without the Envoy implementation

A mirror, and that changes what you can do with it

The repository description is the first thing to read: a read only mirror of the Envoy REST and proto API definitions and documentation. Everything else follows from that label.

The APIs themselves live in the Envoy repository, in the api directory. This tree exists so that the definitions can be consumed without the Envoy implementation. The readme puts it plainly: the APIs are also in some cases used by other proxy solutions that aim to interoperate with management systems, and by configuration generators that are built against this standard, which is why the project considers them a set of universal data plane APIs.

For a reader deciding what this is for, the distinction matters in practical terms. If you want to change the schema, add an extension or fix a comment in an API definition, this is not the place. The canonical read and write home is the api tree in the Envoy repository, and the contributing guide linked from here points at the Envoy project. If you want to compile the protos, generate clients, or build a tool that has to interoperate with Envoy's management surface, this mirror is exactly the artefact you want, and it saves you from taking a dependency on the whole proxy tree.

The concept behind it is described in a blog post on the universal data plane, linked from the readme, which is worth reading before you adopt the mirror, because the arguments about interoperability and about standardising on one API shape are what justify the split.

The universal data plane idea in one paragraph

The readme frames the problem in a way that is worth repeating, because it explains why an API definition tree is published separately from the implementation at all.

The tree hosts the configuration and APIs that drive Envoy. Those APIs are in some cases also used by other proxy solutions whose goal is to interoperate with management systems and with configuration generators built against the standard. If the only copy of those definitions were inside the Envoy implementation, then every other proxy, every control plane and every generator would either vendor the whole Envoy tree or reimplement the definitions and drift.

Publishing them separately turns a set of internal definitions into a standard that other implementations can target. The consequence for an adopter is that the definitions become a compatibility surface in their own right, so the style guide and the versioning guide in this tree are not housekeeping, they are the contract.

That also explains the presence of the versioning directory and the API_VERSIONING.md document in the repository, and it is the reason a team that generates code from these protos should treat the version it compiles against as a decision rather than an accident.

The same API tree, at two locations

The readme documents the two locations explicitly, and the wording is precise about the difference between them.

* https://github.com/envoyproxy/envoy/tree/main/api - canonical read/write home for the APIs.
* https://github.com/envoyproxy/data-plane-api - read-only mirror of
  https://github.com/envoyproxy/envoy/tree/main/api, providing the ability to consume the data
  plane APIs without the Envoy implementation.

So there is one API tree and two repositories that hold it. The Envoy copy is where changes are made, and this one is regenerated from it. The benefit for a consumer is isolation: a configuration generator can vendor the definitions, compile them and depend on them without inheriting the Envoy build, its dependencies or its release cadence.

The practical consequence is that you should not expect this mirror to be a place where you can send a pull request, and you should not expect it to lag or lead in a meaningful way. It is a copy of the canonical tree, and the value of it is that it is a copy with a small, stable dependency footprint.

For a team generating code from it, the question of how the copy is refreshed is the one to raise with the project rather than assume, since the readme does not describe the mirroring mechanism. What it does say is that the mirror provides the ability to consume the data plane APIs without the Envoy implementation, and that is the guarantee you are relying on.

The documents that tell you how to read the API

Five documents are linked for further reading, and between them they cover the two things a schema consumer needs: how the definitions are written and how they change.

* [API style guide](STYLE.md)
* [API versioning guide](API_VERSIONING.md)
* [API overview for users](https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/overview)
* [xDS protocol overview](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol)
* [Contributing guide](CONTRIBUTING.md)

The style guide is about the definitions themselves, so it is the one to read before you write a new field or argue about naming. The versioning guide is the one to read before you pin a version, because it is where the compatibility rules for the API live, and a consumer generating code from these protos is making a long lived dependency decision.

The other two links are the bridge to the runtime. The API overview is written for users configuring Envoy rather than for schema consumers, and the xDS protocol overview is the piece that explains how a management system actually delivers configuration to a proxy over the wire. If your project is a control plane rather than a code generator, that document is the one that matters most, because the protos on their own say nothing about the sequence of requests a client is expected to make.

The contributing guide is linked for completeness, and it is where the read only nature of this tree becomes explicit rather than implicit.

What the tree is made of: Bazel, buf and a versioning directory

The repository layout describes how the definitions are built and checked, and it is recognisable to anyone who has worked in a protobuf codebase.

The build system is Bazel. There is a .bazelrc, a pinned .bazelversion, a MODULE.bazel with its lock file, a BUILD file at the root, a bazel directory and a tools directory. The top level BUILD file, together with the Starlark being the repository's primary language, tells you the definitions are compiled and tested through Bazel targets rather than by a script.

The protobuf tooling is buf, with a buf.yaml and a buf.lock for linting and dependency management across the protos, and the API tree itself sits under an envoy directory, with a separate versioning directory that holds the version related material referenced by the versioning guide.

Around that there is the usual infrastructure for a project of this kind: a .github directory, a .circleci directory for continuous integration, a ci directory, a contrib directory, a test directory, a .clang-format file for the C++ adjacent code, a review_checklist.md used for reviewing changes to the API, and an examples directory whose service_envoy subdirectory shows how the definitions are meant to be used.

Two things this layout implies are worth stating plainly. The example directory is the fastest way to understand the intended consumption pattern, and the review checklist is a hint that changes to these definitions are treated as changes to a published contract rather than as ordinary edits.

Where this repository is the wrong tool

Three situations should send you elsewhere.

The first is proposing a change. If you want to add a field, change a type or fix a description, the work belongs in the Envoy api tree, and the contribution process is the one described in the contributing guide. A pull request against this mirror will not be the way to get an API change, and the time spent working out the right repository is time well spent.

The second is when you need a client. The definitions here are schemas. If what you actually want is a typed client that talks to xDS, a control plane implementation or a language specific SDK, then these protos are the input to that work rather than the work itself, and you will be writing the client.

The third is when you need Envoy's behaviour. The API describes configuration, it does not implement a proxy. A team that wants to understand how a feature behaves under load, or wants to run a proxy in a test, needs the Envoy project itself, and this tree is only the vocabulary.

There is also a version question that the readme leaves open, and it is the one to ask before committing. The repository publishes no GitHub releases, so there is no tagged version of the definitions to pin, and a consumer that wants a reproducible build has to decide how it tracks the mirror. The API versioning guide is where the answer lives, and reading it is the first concrete step for anyone evaluating this dependency.

Licence, cadence and what to verify first

The licence is Apache 2.0, with a LICENSE file at the root of the repository, so the definitions can be vendored, compiled and redistributed inside a product, including a commercial one, provided the notice is kept. This is not legal advice, and the same obligations attach to the Envoy project whose tree this mirrors.

On maintenance, the repository is not archived and the last push was on 2026-10-22, so the mirror is being refreshed. It publishes no GitHub releases, so there is no changelog of API versions to read in the usual way, and the versioning information lives in the API_VERSIONING.md guide and the versioning directory instead.

The result is a dependency with an unusual shape. It is stable in the sense that the API tree changes slowly and deliberately, it moves in the sense that it tracks the Envoy main branch, and it is useful precisely because it is small and separated from the implementation.

For a team about to depend on it, the verification order is short. Read API_VERSIONING.md to learn what the compatibility promises are and how versions are expressed. Read STYLE.md if you are going to contribute a change, because that is where the conventions are, and remember that such a change has to be made in the Envoy repository. Then compile the protos in the language you need and check that the generated code is what you expect, because the value of this repository is that it lets you do that without the Envoy implementation in your dependency tree.

Editorial conclusion

data-plane-api is the right dependency for a control plane, a configuration generator or a management system that needs to speak to Envoy's xDS surface without vendoring the proxy, and for a team that wants to compile the same protos in several languages. It is the wrong repository to propose changes to, since it is a mirror and the canonical tree lives in the Envoy repository, and it is the wrong dependency for an application that only needs a client library. Before adopting, take the API definitions from the mirror and send any schema question or change request to the Envoy repository, and read API_VERSIONING.md before you generate code from a version, because that is where the compatibility contract is written down.

Frequently asked questions

Official sources

1. envoyproxy/data-plane-api on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README