From 1fb52ed53b4bf1d29e294a7972c68dd447dbcd39 Mon Sep 17 00:00:00 2001 From: "data-plane-api(CircleCI)" Date: Wed, 12 Aug 2020 01:20:53 +0000 Subject: [PATCH] docs: clarify xDS resource instance version semantics (#12580) Clarify that resource instance version can be reused across stream restarts. Also a few other small fixes and improvements. Risk Level: Low Testing: N/A Docs Changes: Included in PR Release Notes: N/A Signed-off-by: Mark D. Roth Mirrored from https://github.com/envoyproxy/envoy @ 2a4f7dae855ef81376a8aee6201ea19ea36ef8e2 --- xds_protocol.rst | 86 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 59 insertions(+), 27 deletions(-) diff --git a/xds_protocol.rst b/xds_protocol.rst index 1b254ad7..725c5cb0 100644 --- a/xds_protocol.rst +++ b/xds_protocol.rst @@ -226,20 +226,67 @@ Transport API version In addition the resource type version described above, the xDS wire protocol has a transport version associated with it. This provides type versioning for messages such as :ref:`DiscoveryRequest ` and :ref:`DiscoveryResponse -`. +`. It is also encoded in the gRPC method name, so a server +can determine which version a client is speaking based on which method it calls. -ACK/NACK and resource instance versioning -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Basic Protocol Overview +^^^^^^^^^^^^^^^^^^^^^^^ + +Each xDS stream begins with a :ref:`DiscoveryRequest ` from the +client, which specifies the list of resources to subscribe to, the type URL corresponding to the +subscribed resources, the node identifier, and an optional resource type instance version +indicating the most recent version of the resource type that the client has already seen (see +:ref:`ACK/NACK and resource type instance version ` for details). + +The server will then send a :ref:`DiscoveryResponse ` containing +any resources that the client has subscribed to that have changed since the last resource type +instance version that the client indicated it has seen. The server may send additional responses +at any time when the subscribed resources change. + +Whenever the client receives a new response, it will send another request indicating whether or +not the resources in the response were valid (see +:ref:`ACK/NACK and resource type instance version ` for details). + +Only the first request on a stream is guaranteed to carry the node identifier. +The subsequent discovery requests on the same stream may carry an empty node +identifier. This holds true regardless of the acceptance of the discovery +responses on the same stream. The node identifier should always be identical if +present more than once on the stream. It is sufficient to only check the first +message for the node identifier as a result. + +.. _xds_ack_nack: + +ACK/NACK and resource type instance version +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Each xDS stream begins with a -:ref:`DiscoveryRequest ` from the client, specifying -the list of resources to subscribe to, the type URL corresponding to the -subscribed resources, the node identifier and an empty :ref:`version_info `. +Every xDS resource type has a version string that indicates the version for that resource type. +Whenever one resource of that type changes, the version is changed. -In addition to resource and transport type versioning schemes above, which operate at the type -level, Envoy has a resource instance version. Unlike the resource/transport types, this is not a -property of the API but is instead a reflection of the specific revision of a named resource -delivered over xDS. +In a responses sent by the xDS server, the +:ref:`version_info` field indicates the current +version for that resource type. The client then sends another request to the server with the +:ref:`version_info` field indicating the most +recent valid version seen by the client. This provides a way for the server to determine when +it sends a version that the client considers invalid. + +(In the :ref:`incremental protocol variants `, the resource type instance +version is sent by the server in the +:ref:`system_version_info` field. +However, this information is not actually used by the client to communicate which resources are +valid, because the incremental API variants have a separate mechanism for that.) + +The resource type instance version is separate for each resource type. When using the aggregated +protocol variants, each resource type has its own version even though all resource types are being +sent on the same stream. + +The resource type is also separate for each xDS server (where an xDS server is identified by a +unique :ref:`ConfigSource `). When obtaining resources of a +given type from multiple xDS servers, each xDS server will have a different notion of version. + +Note that the version for a resource type is not a property of an individual xDS stream but rather +a property of the resources themselves. If the stream becomes broken and the client creates a new +stream, the client's initial request on the new stream should indicate the most recent version +seen by the client on the previous stream. An example EDS request might be: @@ -275,7 +322,7 @@ ACK ^^^ If the update was successfully applied, the -:ref:`version_info ` will be **X**, as indicated +:ref:`version_info ` will be **X**, as indicated in the sequence diagram: .. figure:: diagrams/simple-ack.svg @@ -320,21 +367,6 @@ ACK and NACK semantics summary :ref:`version_info `. - Only the NACK should populate the :ref:`error_detail `. -Versioning and Node Identifier -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Each stream has its own notion of versioning, there is no shared -versioning across resource types. When ADS is not used, even each -resource of a given resource type may have a distinct version, since the -Envoy API allows distinct EDS/RDS resources to point at different :ref:`ConfigSources `. - -Only the first request on a stream is guaranteed to carry the node identifier. -The subsequent discovery requests on the same stream may carry an empty node -identifier. This holds true regardless of the acceptance of the discovery -responses on the same stream. The node identifier should always be identical if -present more than once on the stream. It is sufficient to only check the first -message for the node identifier as a result. - .. _xds_protocol_resource_update: When to send an update