Add more to the README

Signed-off-by: Miek Gieben <miek@miek.nl>

plugin/traffic/HACKING.md

@@ -0,0 +1,11 @@
+Hacking on *traffic*
+
+Repos used:
+
+<https://github.com/envoyproxy/go-control-plane>
+:   implements control plane, has testing stuff in pkg/test/main (iirc).
+
+<https://github.com/grpc/grpc-go/tree/master/xds/internal/client>
+:   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:

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.

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.