go-control-plane: the xDS infrastructure layer for Envoy control planes
Go implementation of data-plane-api. Instead, it provides infrastructure that is shared by multiple different control plane implementations.
At a glance
- What is it?
- go-control-plane is a Go library that provides the API server, configuration caches, and generated protos for building Envoy control planes. It is not a complete control plane, but the shared infrastructure underneath one.
- Who is it for?
- Adopt go-control-plane if you are building a custom Envoy control plane and need a maintained xDS API server, generated protos, and caching primitives without writing the gRPC layer yourself. Do not adopt it if you expect a turnkey control plane that translates your service registry into Envoy configuration, because the README explicitly states that translation is out of scope.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 14, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What this library actually is
The README is explicit about scope: go-control-plane is not a full control plane for a fleet of Envoy proxies. It is a Go implementation of the discovery service APIs defined in data-plane-api, providing infrastructure that multiple control plane implementations can share. The two main components are a generic gRPC API server that implements the xDS APIs, and a configuration cache that stores Envoy configurations in memory. The cache is keyed by a hash based on Node information from the Envoy API. This means you bring your own configuration source, your own translation logic, and your own invalidation policy. The library gives you the transport and the state storage, not the business logic.
The API server and its role
The API server is a generic gRPC server that implements the xDS discovery services as defined in data-plane-api. It pushes configuration updates to Envoys. The README claims consumers should be able to import this Go library and use the API server as is, in production deployments. That is a strong claim, but the caveat is that you must populate the cache yourself. The server handles the protocol details: subscriptions, responses, and the various xDS resource types. It does not know what a service is, or how to translate a Kubernetes Service into a Cluster. That translation layer is explicitly out of scope. The README notes that the repository will not tackle translating platform-specific representations of resources into Envoy-style configuration, at least for now.
Three caches for different consistency models
The cache is not a single thing. The repository offers three caches with different semantics. The Simple cache is snapshot-based. It maintains a consistent view of configuration for each group of proxies, and it can run as an ADS server or as regular disaggregated xDS servers. In ADS mode, the Simple cache can hold responses until the complete set of referenced resources is requested, for example the entire set of RDS as referenced by LDS. This enables atomic updates of xDS collections. The Linear cache is eventually consistent and works for a single type URL collection. It keeps a single linear version history and a version vector for resources. For each request, it compares the request version against the latest versions and responds with updated resources. It assumes resources are entirely opaque, which makes it simpler but less aware of dependencies. The Mux cache is a combinator that lets you mix different caches for different type URLs, like using Simple for LDS/RDS/CDS and Linear for EDS.
Getting it running: commands and requirements
The README lists Go 1.26 or newer as a requirement. For development, it recommends running tests with `make docker_tests`, which executes tests in the same environment as CI to ensure a consistent set of generated files. The quick start is two steps: run `make docker_tests`, then look at the example server in `internal/example/README.md`. That example server demonstrates how to integrate go-control-plane with your own code. There is no installation command like `go get` in the README, but since it is a Go library, you would import it by module path. The repo contains generated Go proto files that are synced from the upstream Envoy repository on every upstream commit. Synchronization is triggered via the `envoy-sync.yaml` workflow, so you get fresh protos without manual copying.
Versioning and the V2 removal
The xDS APIs follow a versioning scheme documented on the Envoy website. The repository has removed V2 control-plane code entirely. The README states that V2 is no longer supported, and if you still need V2, you should use a previous SHA. This is a hard break. Any existing control plane that relied on V2 will need to migrate to V3 or stay on an old commit. The release history shows recent tags like envoy/v1.39.0, envoy/v1.38.0, and envoy/v1.37.0, which suggests a regular release cadence aligned with Envoy versions. The removal of V2 is a clear signal that the project moves with the upstream Envoy API, not backward compatibility.
A real limitation: no resource translation
The most significant limitation is the one the README states plainly: the library does not translate platform-specific representations of resources into Envoy-style configuration. If you operate a fleet of services in Kubernetes, Consul, or a custom registry, you must write the code that converts your service instances into Envoy Clusters, Endpoints, Listeners, and Routes. The cache is keyed on Node information, so you must also decide how to group proxies. The Simple cache's atomic snapshot behavior is powerful but requires you to assemble consistent snapshots. If you send partial updates, you may get inconsistent state. The Linear cache avoids that by being eventually consistent, but it only handles one type URL at a time and treats resources as opaque, so it cannot reason about cross-resource dependencies. For complex configuration graphs, that is a real constraint.
Alternatives and how they differ
The main alternative in the same space is writing a control plane from scratch using the raw Envoy gRPC service definitions, or using a higher-level control plane like Envoy's own example or a commercial offering. The difference is the level of abstraction. go-control-plane gives you a server and caches, but leaves translation to you. A project like Envoy's own control plane examples or tools like Gloo or Istio provide the translation layer, but they are also opinionated about your platform. If you need to support a niche platform, go-control-plane is the lower-level building block. If you need a ready-made translation from Kubernetes to Envoy, you would look at Istio or a similar project, but you inherit their model of what a service is. The README's scope statement is honest: there is no single control plane that satisfies everyone, so this library provides the shared parts.
Maintenance and license implications
The project is under the Apache-2.0 license, which permits commercial use, modification, and redistribution, provided you preserve copyright notices. The repository is actively maintained, with the last push on 2026-08-17 and a release for envoy/v1.39.0 on the same day. The synchronization workflow with upstream Envoy means you will get new protos as Envoy evolves, but that also means you must track upstream changes. Each new Envoy version may introduce breaking API changes, as the V2 removal demonstrates. The maintenance cost is on you: you must keep your Go version current, regenerate or update your code when the protos change, and test against the latest Envoy. The `make docker_tests` target helps ensure consistency, but it does not remove the need to adapt your control plane logic to new xDS versions.
Editorial conclusion
Adopt go-control-plane if you are building a custom Envoy control plane and need a maintained xDS API server, generated protos, and caching primitives without writing the gRPC layer yourself. Do not adopt it if you expect a turnkey control plane that translates your service registry into Envoy configuration, because the README explicitly states that translation is out of scope. Before adopting, verify the versioning scheme in the xDS docs, confirm your Go version is 1.26 or newer, and check whether the Simple cache's atomic snapshot behavior matches your update semantics. If you need eventual consistency for a single resource type, the Linear cache is the alternative within the same library.
Community notes