README.md
1# control-plane
2
3[](https://circleci.com/gh/envoyproxy/go-control-plane)
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.12+
43
44## Quick start
45
46It's recommended to run the command with script `./build/run_docker.sh` as it executes the command
47in the same environment as the circle ci. This makes sure to produce a consistent set of generated files.
48
491. Setup existing build:
50
51 ```sh
52 ./build/run_docker.sh make build test
53 ```
54
551. Run [integration test](pkg/test/main/README.md) against the latest Envoy binary:
56
57 ```sh
58 ./build/run_docker.sh make integration
59 ```
60
61## Xds Api versioning
62
63The Envoy xDS APIs follow a well defined [versioning scheme](https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/versioning).
64Due to lack of generics and function overloading in golang, creating a new version unfortunately involves code duplication.
65Based on the discussion [here](https://docs.google.com/document/d/1ZkHpz6DwEUmAlG0kb2Mgu4iaeQC2Bbb0egMbECoNNKY/edit?ts=5e602993#heading=h.15nsmgmjaaml) and [here](https://envoyproxy.slack.com/archives/C7LDJTM6Z/p1582925082005300), go-control-plane is adopting a mechanism to create a new version from an existing version by running a script.
66In order to handle deprecated/new fields between versions, make sure to create a shim such that duplication remains minimal. One such example today is how different [resource urls](https://github.com/envoyproxy/go-control-plane/tree/master/pkg/resource) are handled.
67
68For authoring changes, make changes to v2 and at the end, use `make create_version` to create the v3 specific files.
69Make sure to run `make build` and `make test` to identify and fix failures.
70
71When v2 version is frozen in the future, we will change the experience such that changes will need to happen to v3 and autogen will create the v2 version instead.
72
73## Usage
74
75Register services on the gRPC server as follows.
76
77```go
78import (
79 "context"
80 "google.golang.org/grpc"
81 "net"
82
83 api "github.com/envoyproxy/go-control-plane/envoy/api/v2"
84 discovery "github.com/envoyproxy/go-control-plane/envoy/service/discovery/v2"
85 "github.com/envoyproxy/go-control-plane/pkg/cache/v2"
86 xds "github.com/envoyproxy/go-control-plane/pkg/server/v2"
87)
88
89func main() {
90 snapshotCache := cache.NewSnapshotCache(false, cache.IDHash{}, nil)
91 server := xds.NewServer(context.Background(), snapshotCache, nil)
92 grpcServer := grpc.NewServer()
93 lis, _ := net.Listen("tcp", ":8080")
94
95 discovery.RegisterAggregatedDiscoveryServiceServer(grpcServer, server)
96 api.RegisterEndpointDiscoveryServiceServer(grpcServer, server)
97 api.RegisterClusterDiscoveryServiceServer(grpcServer, server)
98 api.RegisterRouteDiscoveryServiceServer(grpcServer, server)
99 api.RegisterListenerDiscoveryServiceServer(grpcServer, server)
100 go func() {
101 if err := grpcServer.Serve(lis); err != nil {
102 // error handling
103 }
104 }()
105}
106```
107
108As mentioned in [Scope](https://github.com/envoyproxy/go-control-plane/blob/master/README.md#scope), you need to cache Envoy configurations.
109Generate the key based on the node information as follows and cache the configurations.
110
111```go
112import "github.com/envoyproxy/go-control-plane/pkg/cache/v2"
113
114var clusters, endpoints, routes, listeners []cache.Resource
115
116snapshotCache := cache.NewSnapshotCache(false, cache.IDHash{}, nil)
117snapshot := cache.NewSnapshot("1.0", endpoints, clusters, routes, listeners)
118_ = snapshotCache.SetSnapshot("node1", snapshot)
119```
120
){kind=link}
){kind=link}