envoy-control-plane/

directory
v1.9.0-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2020 License: Apache-2.0, Apache-2.0

README

control-plane

CircleCI Go Report Card GoDoc

This repository contains a Go-based implementation of an API server that implements the discovery service APIs defined in data-plane-api.

Scope

Due to the variety of platforms out there, there is no single control plane implementation that can satisfy everyone's needs. Hence this code base does not attempt to be a full scale control plane for a fleet of Envoy proxies. Instead, it provides infrastructure that is shared by multiple different control plane implementations. The components provided by this library are:

  • API Server: A generic gRPC based API server that implements xDS APIs as defined in the data-plane-api. The API server is responsible for pushing configuration updates to Envoys. Consumers should be able to import this go library and use the API server as is, in production deployments.

  • Configuration Cache: The library will cache Envoy configurations in memory in an attempt to provide fast response to consumer Envoys. It is the responsibility of the consumer of this library to populate the cache as well as invalidate it when necessary. The cache will be keyed based on a pre-defined hash function whose keys are based on the Node information.

At this moment, this repository will not tackle translating platform specific representation of resources (e.g., services, instances of services, etc.) into Envoy-style configuration. Based on usage and feedback, we might decided to revisit this aspect at a later point in time.

Requirements

  1. Go 1.12+

Quick start

It's recommended to run the command with script ./build/run_docker.sh as it executes the command in the same environment as the circle ci. This makes sure to produce a consistent set of generated files.

  1. Setup existing build:

    ./build/run_docker.sh make build test
    
  2. Run integration test against the latest Envoy binary:

    ./build/run_docker.sh make integration
    

Xds Api versioning

The Envoy xDS APIs follow a well defined versioning scheme. Due to lack of generics and function overloading in golang, creating a new version unfortunately involves code duplication. Based on the discussion here and here, go-control-plane is adopting a mechanism to create a new version from an existing version by running a script. In 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 are handled.

For authoring changes, make changes to v2 and at the end, use make create_version to create the v3 specific files. Make sure to run make build and make test to identify and fix failures.

When 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.

Usage

Register services on the gRPC server as follows.

import (
	"context"
	"google.golang.org/grpc"
	"net"

	api "github.com/envoyproxy/go-control-plane/envoy/api/v2"
	discovery "github.com/envoyproxy/go-control-plane/envoy/service/discovery/v2"
	"github.com/envoyproxy/go-control-plane/pkg/cache/v2"
	xds "github.com/envoyproxy/go-control-plane/pkg/server/v2"
)

func main() {
	snapshotCache := cache.NewSnapshotCache(false, cache.IDHash{}, nil)
	server := xds.NewServer(context.Background(), snapshotCache, nil)
	grpcServer := grpc.NewServer()
	lis, _ := net.Listen("tcp", ":8080")

	discovery.RegisterAggregatedDiscoveryServiceServer(grpcServer, server)
	api.RegisterEndpointDiscoveryServiceServer(grpcServer, server)
	api.RegisterClusterDiscoveryServiceServer(grpcServer, server)
	api.RegisterRouteDiscoveryServiceServer(grpcServer, server)
	api.RegisterListenerDiscoveryServiceServer(grpcServer, server)
	go func() {
		if err := grpcServer.Serve(lis); err != nil {
			// error handling
		}
	}()
}

As mentioned in Scope, you need to cache Envoy configurations. Generate the key based on the node information as follows and cache the configurations.

import (
	"github.com/envoyproxy/go-control-plane/pkg/cache/v2"
 	"github.com/envoyproxy/go-control-plane/pkg/cache/types"
)

var clusters, endpoints, routes, listeners, runtimes []types.Resource

snapshotCache := cache.NewSnapshotCache(false, cache.IDHash{}, nil)
snapshot := cache.NewSnapshot("1.0", endpoints, clusters, routes, listeners, runtimes)
_ = snapshotCache.SetSnapshot("node1", snapshot)

Directories

Path Synopsis
cache
v2
Package cache defines a configuration cache for the server.
Package cache defines a configuration cache for the server.
v3
Package cache defines a configuration cache for the server.
Package cache defines a configuration cache for the server.
Package conversion contains shared utility functions for converting xDS resources.
Package conversion contains shared utility functions for converting xDS resources.
Package log provides a logging interface for use in this library.
Package log provides a logging interface for use in this library.
resource
v2
v3
server
v2
Package server provides an implementation of a streaming xDS server.
Package server provides an implementation of a streaming xDS server.
v3
Package server provides an implementation of a streaming xDS server.
Package server provides an implementation of a streaming xDS server.
Package test contains test utilities
Package test contains test utilities
main
Package main contains the test driver for testing xDS manually.
Package main contains the test driver for testing xDS manually.
resource/v2
Package resource creates test xDS resources
Package resource creates test xDS resources
resource/v3
Package resource creates test xDS resources
Package resource creates test xDS resources
v2
Package test contains test utilities
Package test contains test utilities
v3
Code generated by create_version.
Code generated by create_version.
Package wellknown contains common names for filters, listeners, etc.
Package wellknown contains common names for filters, listeners, etc.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL