From 3e095ad8475872411f6a33e4e96beb967aead662 Mon Sep 17 00:00:00 2001 From: Miek Gieben Date: Sat, 11 Jan 2020 08:48:30 +0100 Subject: [PATCH] Add more to the README Signed-off-by: Miek Gieben --- plugin/traffic/HACKING.md | 11 +++++++++ plugin/traffic/README.md | 34 +++++++++++++++++++++------- plugin/traffic/xds/README_coredns.md | 10 ++++++++ 3 files changed, 47 insertions(+), 8 deletions(-) create mode 100644 plugin/traffic/HACKING.md create mode 100644 plugin/traffic/xds/README_coredns.md diff --git a/plugin/traffic/HACKING.md b/plugin/traffic/HACKING.md new file mode 100644 index 000000000..0a483fec6 --- /dev/null +++ b/plugin/traffic/HACKING.md @@ -0,0 +1,11 @@ +Hacking on *traffic* + +Repos used: + + +: implements control plane, has testing stuff in pkg/test/main (iirc). + + +: implements client for xDS - can probably list all code out from there. + +To see if things are working start the testing control plane from go-control-plane: diff --git a/plugin/traffic/README.md b/plugin/traffic/README.md index 8b7e84f41..f578c7a39 100644 --- a/plugin/traffic/README.md +++ b/plugin/traffic/README.md @@ -7,17 +7,21 @@ ## Description The *traffic* plugin is a load balancer that allows traffic steering, weighted responses and -draining of endpoints. It discovers the enpoints via the Envoy xDS protocol, specifically messages -of the type "envoy.api.v2.ClusterLoadAssignment", these contain endpoints and an (optional) weight -for each. The `cluster_name` or `service_name` for a service must be a domain name. +draining of endpoints. The use case for this plugin is when a service is running in multiple +(Kubernetes?) clusters and need to steer traffic to (or away) from these, i.e. cluster A needs to be +upgraded, so all traffic to it is drained, while cluster B now takes on all the extra load. After +the maintenance cluster A is simply undrained. -The plugin takes care of handing out responses that adhere to these assignments. +*Traffic* discovers the endpoints via the Envoy xDS protocol, specifically messages of the type +"envoy.api.v2.ClusterLoadAssignment", these contain endpoints and an (optional) weight for each. +The `cluster_name` or `service_name` for a service must be a domain name. (TODO: check is this is +already the case). The plugin hands out responses that adhere to these assignments. Assignments will need to be updated frequently, as discussed the [Envoy xDS -protocol](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol) documentation. Each -response will contain one address record; which *traffic* considers the optimal one. +protocol](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol) documentation. -When there are no assignments for a service name (yet), the responses will also be modified (see -below). +Multiple endpoints for a service may exist; for every query *traffic* will hand out exactly one +address. When there are no assignments for a service name (yet), the responses will also be modified +(see below). *Traffic* will load balance A and AAAA queries. As said, it will return precisely one record in a response. If a service should be load balanced, but no assignment can be found a random record from @@ -30,6 +34,8 @@ The *traffic* plugin has no notion of draining, drop overload and anything that acts upon assignments*. This is means that if a endpoint goes down and *traffic* has not seen a new assignment yet, it will still include this endpoint address in responses. +Findign the xDS endpoint. + ## Syntax ~~~ @@ -74,6 +80,13 @@ Authority section will be removed. If no assignment, randomly pick an address other types then A and AAAA, like SRV - do the same selection. +## Limitations + +Loadreporting via xDS is not supported; this can be implemented, but there are some things that make +this difficult. A single (DNS) query is done by a resolver. Behind this resolver there may be many +clients that will use this assignment. + + ## Bugs This plugin does not play nice with DNSSEC - if the endpoint returns signatures with the answer; they @@ -85,3 +98,8 @@ will be stripped. You can optionally sign responses on the fly by using the *dns * https://blog.christianposta.com/envoy/guidance-for-building-a-control-plane-to-manage-envoy-proxy-based-infrastructure/ * https://github.com/envoyproxy/envoy/blob/442f9fcf21a5f091cec3fe9913ff309e02288659/api/envoy/api/v2/discovery.proto#L63 * This is a [post on weighted random selection](https://medium.com/@peterkellyonline/weighted-random-selection-3ff222917eb6). + +# TODO + +* wording: cluster, endpoints, assignments, service_name are all used and roughly mean the same + thing; unify this. diff --git a/plugin/traffic/xds/README_coredns.md b/plugin/traffic/xds/README_coredns.md new file mode 100644 index 000000000..6c5ece8f8 --- /dev/null +++ b/plugin/traffic/xds/README_coredns.md @@ -0,0 +1,10 @@ +This code is copied from +[https://github.com/grpc/grpc-go/tree/master/xds](https://github.com/grpc/grpc-go/tree/master/xds). +Grpc-go is also a consumer of the Envoy xDS data and acts upon it. + +The *traffic* plugin only cares about clusters and endpoints, the following bits are deleted: + +* lDS; listener discovery is not used here. +* rDS: routes have no use for DNS responses. + +Load reporting is also not implemented, although this can be done on the DNS level.