README.md
1# control-plane
2
3
4[](https://goreportcard.com/report/github.com/envoyproxy/go-control-plane)
5[](https://godoc.org/github.com/envoyproxy/go-control-plane)
6
7This repository contains a Go-based implementation of an API server that
8implements the discovery service APIs defined in
9[data-plane-api](https://github.com/envoyproxy/data-plane-api).
10
11
12## Scope
13
14Due to the variety of platforms out there, there is no single
15control plane implementation that can satisfy everyone's needs. Hence this
16code base does not attempt to be a full scale control plane for a fleet of
17Envoy proxies. Instead, it provides infrastructure that is shared by
18multiple different control plane implementations. The components provided
19by this library are:
20
21* _API Server:_ A generic gRPC based API server that implements xDS APIs as defined
22 in the
23 [data-plane-api](https://github.com/envoyproxy/data-plane-api). The API
24 server is responsible for pushing configuration updates to
25 Envoys. Consumers should be able to import this go library and use the
26 API server as is, in production deployments.
27
28* _Configuration Cache:_ The library will cache Envoy configurations in
29memory in an attempt to provide fast response to consumer Envoys. It is the
30responsibility of the consumer of this library to populate the cache as
31well as invalidate it when necessary. The cache will be keyed based on a
32pre-defined hash function whose keys are based on the
33[Node information](https://github.com/envoyproxy/data-plane-api/blob/d4988844024d0bcff4bcd030552eabe3396203fa/api/base.proto#L26-L36).
34
35At this moment, this repository will not tackle translating platform
36specific representation of resources (e.g., services, instances of
37services, etc.) into Envoy-style configuration. Based on usage and
38feedback, we might decided to revisit this aspect at a later point in time.
39
40## Requirements
41
421. Go 1.11+
43
44## Quick start
45
46It's recommended to run the tests with `make docker_tests` as it executes the tests
47in the same environment as CI. This makes sure to produce a consistent set of generated files.
48
491. Build and run tests:
50
51 ```sh
52 make docker_tests
53 ```
54
551. Take a look at the [example server](internal/example/README.md).
56
57
58## XDS API versioning
59
60The Envoy xDS APIs follow a well defined [versioning scheme](https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/versioning).
61
62### Deprecated
63
64`V2` control-plane code has been removed and will no longer be supported. For previous conversations on support for various xDS versions, see here:
65- [here](https://docs.google.com/document/d/1ZkHpz6DwEUmAlG0kb2Mgu4iaeQC2Bbb0egMbECoNNKY/edit?ts=5e602993#heading=h.15nsmgmjaaml)
66- [here](https://envoyproxy.slack.com/archives/C7LDJTM6Z/p1582925082005300)
67
68*Note*: It is recommended to use a previous SHA if there is still a need for `V2`.
69
70## Resource caching
71
72Because Envoy clients are assumed to be ephemeral, and thus, can come and go
73away arbitrarily, the server relies on a configuration cache to minimize the
74client load on the server. There are several caches available in this
75repository:
76
77- `Simple` cache is a snapshot-based cache that maintains a consistent view of
78 the configuration for each group of proxies. It supports running as an ADS
79 server or as regular dis-aggregated xDS servers. In ADS mode, the cache can
80 hold responses until the complete set of referenced resources is requested
81 (e.g. the entire set of RDS as referenced by LDS). Holding the response
82 enables an atomic update of xDS collections.
83
84- `Linear` is an eventually consistent cache for a single type URL collection.
85 The cache maintains a single linear version history and a version vector for
86 the resources in the cache. For each request, it compares the request version
87 against latest versions for the requested resources, and responds with any
88 updated resources. This cache assumes the resources are entirely opaque.
89
90- `Mux` cache is a simple cache combinator. It allows mixing multiple caches
91 for different type URLs, e.g use a simple cache for LDS/RDS/CDS and a linear
92 cache for EDS.
93
94## Usage
95
96The [example server](internal/example/README.md) demonstrates how to integrate the go-control-plane with your code.
97
){kind=link}
){kind=link}