Mirrors/coredns
1
0
Fork 0
mirror of https://github.com/coredns/coredns.git synced 2025-10-28 08:44:17 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs

Browse Source 
Signed-off-by: Miek Gieben <miek@miek.nl>
This commit is contained in:
Miek Gieben
2020-01-18 08:04:01 +01:00
parent 4e38000ec2
commit d988e2baaf
1 changed files with 22 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
plugin/traffic/README.md
View File

@@ -8,46 +8,52 @@
The *traffic* plugin is a balancer that allows traffic steering, weighted responses The *traffic* plugin is a balancer that allows traffic steering, weighted responses
and draining of clusters. The cluster information is retrieved from a service and draining of clusters. The cluster information is retrieved from a service
discovery manager that implements the service discovery protocols that Envoy discovery manager that implements the service discovery protocols from Envoy
[implements](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol). [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 A Cluster in Envoy is defined as: "A group of logically similar endpoints that Envoy connects to."
cluster has a name, which *traffic* extends to be a domain name. See "Naming Clusters" below. 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?) 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 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* 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. endpoints need to be drained from it.
*Traffic* discovers the endpoints via Envoy's xDS protocol. Endpoints and clusters are discovered *Traffic* discovers the endpoints via Envoy's xDS protocol (using ADS). Endpoints and clusters are
every 10 seconds. The plugin hands out responses that adhere to these assignments. Only endpoints discovered every 10 seconds. The plugin hands out responses that adhere to these assignments. Only
that are *healthy* are handed out. endpoints that are *healthy* are handed out.
Each DNS response contains a single IP address that's considered the best one. *Traffic* will load 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 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 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 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 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. 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 ## Syntax
~~~ ~~~
traffic TO... 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 * **TO...** are the control plane endpoints to connect to. These must start with `grpc://`. The
port number defaults to 443. 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... { traffic TO... {
server SERVER [SERVER]...
node ID node ID
tls CERT KEY CA tls CERT KEY CA
tls_servername NAME tls_servername NAME
@@ -83,7 +89,7 @@ What metrics should we do? If any? Number of clusters? Number of endpoints and h
## Ready ## Ready
This plugin report readiness to the ready plugin. This will happen after a gRPC stream has been 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 ## Examples
@@ -112,15 +118,8 @@ The following documents provide some background on Envoy's control plane.
## Bugs ## Bugs
Priority and locality information from ClusterLoadAssignments is not used. Priority and locality information from ClusterLoadAssignments is not used. Multiple **TO** addresses
is not implemented.
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.
## TODO ## TODO