From d988e2baaf3a1b27d344c4b60ccd0873af1dba49 Mon Sep 17 00:00:00 2001 From: Miek Gieben Date: Sat, 18 Jan 2020 08:04:01 +0100 Subject: [PATCH] docs Signed-off-by: Miek Gieben --- plugin/traffic/README.md | 45 ++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/plugin/traffic/README.md b/plugin/traffic/README.md index 4d9af7bf4..e973a7968 100644 --- a/plugin/traffic/README.md +++ b/plugin/traffic/README.md @@ -8,46 +8,52 @@ The *traffic* plugin is a balancer that allows traffic steering, weighted responses and draining of clusters. The cluster information is retrieved from a service -discovery manager that implements the service discovery protocols that Envoy -[implements](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol). +discovery manager that implements the service discovery protocols from Envoy +[implements](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol). It connect to the +manager using the Aggregated Discovery Service (ADS) protocol. -A Cluster is defined as: "A group of logically similar endpoints that Envoy connects to." Each -cluster has a name, which *traffic* extends to be a domain name. See "Naming Clusters" below. +A Cluster in Envoy is defined as: "A group of logically similar endpoints that Envoy connects to." +Each cluster has a name, which *traffic* extends to be a domain name. See "Naming Clusters" below. The use case for this plugin is when a cluster has endpoints running in multiple (Kubernetes?) clusters and you need to steer traffic to (or away) from these endpoints, i.e. endpoint A needs to be upgraded, so all traffic to it is drained. Or the entire Kubernetes needs to upgraded, and *all* endpoints need to be drained from it. -*Traffic* discovers the endpoints via Envoy's xDS protocol. Endpoints and clusters are discovered -every 10 seconds. The plugin hands out responses that adhere to these assignments. Only endpoints -that are *healthy* are handed out. +*Traffic* discovers the endpoints via Envoy's xDS protocol (using ADS). Endpoints and clusters are +discovered every 10 seconds. The plugin hands out responses that adhere to these assignments. Only +endpoints that are *healthy* are handed out. Each DNS response contains a single IP address that's considered the best one. *Traffic* will load balance A and AAAA queries. The TTL on these answer is set to 5s. It will only return successful responses either with an answer or otherwise a NODATA response. Queries for non-existent clusters -get a NXDOMAIN. +get a NXDOMAIN, where the minimal TTL is also set to 5s. The *traffic* plugin has no notion of draining, drop overload and anything that advanced, *it just 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. +Load reporting is not supported for the following reason. A DNS query is done by a resolver. +Behind this resolver (which can also cache) there may be many clients that will use this reply. The +responding server (CoreDNS) has no idea how many clients use this resolver. So reporting a load of ++1 on the CoreDNS side can results in anything from 1 to 1000+ of queries on the endpoint, making +the load reporting from *trafifc* highly inaccurate. + ## Syntax ~~~ traffic TO... ~~~ -This enabled the *traffic* plugin, with a default node id of `coredns` and no TLS. +This enabled the *traffic* plugin, with a default node ID of `coredns` and no TLS. -* **TO...** are the Envoy control plane endpoint to connect to. This must start with `grpc://`. The - port number defaults to 443. +* **TO...** are the control plane endpoints to connect to. These must start with `grpc://`. The + port number defaults to 443, if not specified. -The extended syntax is available is you want more control. +The extended syntax is available if you want more control. ~~~ traffic TO... { - server SERVER [SERVER]... node ID tls CERT KEY CA tls_servername NAME @@ -83,7 +89,7 @@ What metrics should we do? If any? Number of clusters? Number of endpoints and h ## Ready This plugin report readiness to the ready plugin. This will happen after a gRPC stream has been -established to an upstream. +established to the control plane. ## Examples @@ -112,15 +118,8 @@ The following documents provide some background on Envoy's control plane. ## Bugs -Priority and locality information from ClusterLoadAssignments is not used. - -Load reporting 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 reply, the responding server (CoreDNS) has no idea how many clients -use this resolver. So reporting a load of +1 on the CoreDNS side can be anything from 1 to 1000+, -making the load reporting highly inaccurate. - -Multiple **TO** addresses is not implemented. +Priority and locality information from ClusterLoadAssignments is not used. Multiple **TO** addresses +is not implemented. ## TODO