Incremental XDS proposal. (envoyproxy#3470)

Signed-off-by: Nicolas Thiebaud <nicothieb@google.com>
BTMa-ucas · Jul 2, 2018 · e341004 · e341004
1 parent b686053
commit e341004
Show file tree

Hide file tree

Showing 7 changed files with 159 additions and 0 deletions.
diff --git a/api/XDS_PROTOCOL.md b/api/XDS_PROTOCOL.md
@@ -285,6 +285,51 @@ admin:
 
 ```
 
+### Incremental xDS
+
+Incremental xDS is separate xDS endpoint available for ADS, CDS and RDS that
+allows:
+
+  * Incremental updates of the list of tracked resources by the xDS client.
+    This supports Envoy on-demand / lazily requesting additional resources. For
+    example, this may occur when a request corresponding to an unknown cluster
+    arrives.
+  * The xDS server can incremetally update the resources on the client.
+    This support the goal of scalability of xDS resources. Rather than deliver
+    all 100k clusters when a single cluster is modified, the management server
+    only needs to deliver the single cluster that changed.
+
+An xDS incremental session is always in the context of a gRPC bidirectional
+stream. This allows the xDS server to keep track of the state of xDS clients
+connected to it. There is no REST version of Incremental xDS.
+
+In incremental xDS the nonce field is required and used to pair a
+[`IncrementalDiscoveryResponse`](https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/discovery.proto#discoveryrequest)
+to a [`IncrementalDiscoveryRequest`](https://www.envoyproxy.io/docs/envoy/latest/api-v2/api/v2/discovery.proto#discoveryrequest)
+ACK or NACK.
+Optionally, a response message level system_version_info is present for
+debugging purposes only.
+
+`IncrementalDiscoveryRequest` can be sent in 3 situations:
+  1. Initial message in a xDS bidirectional gRPC stream.
+  2. As an ACK or NACK response to a previous `IncrementalDiscoveryResponse`.
+     In this case the `response_nonce` is set to the nonce value in the Response.
+     ACK or NACK is determined by the absence or presence of `error_detail`.
+  3. Spontaneous `IncrementalDiscoveryRequest` from the client.
+     This can be done to dynamically add or remove elements from the tracked
+     `resource_names` set. In this case `response_nonce` must be omitted.
+
+In this first example the client connects and receive a first update that it
+ACKs. The second update fails and the client NACKs the update. Later the xDS
+client spontaneously requests the "wc" resource.
+
+![Incremental session example](diagrams/incremental.svg)
+
+On reconnect the xDS Incremental client may tell the server of its known resources
+to avoid resending them over the network.
+
+![Incremental reconnect example](diagrams/incremental-reconnect.svg)
+
 ## REST-JSON polling subscriptions
 
 Synchronous (long) polling via REST endpoints is also available for the xDS

diff --git a/api/diagrams/incremental-reconnect.svg b/api/diagrams/incremental-reconnect.svg