From 7bbebd4f51de3c7e3621a8e997460dc2dde36d69 Mon Sep 17 00:00:00 2001 From: Rama Chavali Date: Fri, 25 Mar 2022 14:18:23 +0530 Subject: [PATCH 1/7] clarify xds docs on resource deletion Signed-off-by: Rama Chavali --- docs/root/api-docs/xds_protocol.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/root/api-docs/xds_protocol.rst b/docs/root/api-docs/xds_protocol.rst index b95b6ec39ac50..ed7427ef0f32f 100644 --- a/docs/root/api-docs/xds_protocol.rst +++ b/docs/root/api-docs/xds_protocol.rst @@ -500,14 +500,17 @@ Deleting Resources In the incremental protocol variants, the server signals the client that a resource should be deleted via the :ref:`removed_resources ` -field of the response. This tells the client to remove the resource from its local cache. +field of the response for wildcard resource types like +:ref:`Listener ` and :ref:`Cluster `. +This tells the client to remove the resource from its local cache. -In the SotW protocol variants, the criteria for deleting resources is more complex. For -:ref:`Listener ` and :ref:`Cluster ` resource types, +In the SotW protocol variants, the criteria for deleting resources is more complex. For wildcard resource types like +:ref:`Listener ` and :ref:`Cluster ` if a previously seen resource is not present in a new response, that indicates that the resource has been removed, and the client must delete it; a response containing no resources means to delete -all resources of that type. However, for other resource types, the API provides no mechanism for -the server to tell the client that resources have been deleted; instead, deletions are indicated +all resources of that type. + +For other resource types, in both SotW and incremental protocol variants, deletions are indicated implicitly by parent resources being changed to no longer refer to a child resource. For example, when the client receives an LDS update removing a :ref:`Listener ` that was previously pointing to :ref:`RouteConfiguration ` A, From 797401cdaed5f6c47283deb9ce79604106dfc8cf Mon Sep 17 00:00:00 2001 From: Rama Chavali Date: Fri, 25 Mar 2022 14:40:34 +0530 Subject: [PATCH 2/7] lint Signed-off-by: Rama Chavali --- docs/root/api-docs/xds_protocol.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/root/api-docs/xds_protocol.rst b/docs/root/api-docs/xds_protocol.rst index ed7427ef0f32f..a3cb640209261 100644 --- a/docs/root/api-docs/xds_protocol.rst +++ b/docs/root/api-docs/xds_protocol.rst @@ -500,7 +500,7 @@ Deleting Resources In the incremental protocol variants, the server signals the client that a resource should be deleted via the :ref:`removed_resources ` -field of the response for wildcard resource types like +field of the response for wildcard resource types like :ref:`Listener ` and :ref:`Cluster `. This tells the client to remove the resource from its local cache. From 79377aaa9032c2cd9d2d79ee1077bbcfec5941c8 Mon Sep 17 00:00:00 2001 From: Rama Chavali Date: Fri, 25 Mar 2022 16:00:15 +0530 Subject: [PATCH 3/7] lint and paragraph Signed-off-by: Rama Chavali --- docs/root/api-docs/xds_protocol.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/root/api-docs/xds_protocol.rst b/docs/root/api-docs/xds_protocol.rst index a3cb640209261..eb5d42f35f5eb 100644 --- a/docs/root/api-docs/xds_protocol.rst +++ b/docs/root/api-docs/xds_protocol.rst @@ -498,19 +498,20 @@ twice. Clients should NACK responses that contain multiple instances of the same Deleting Resources ^^^^^^^^^^^^^^^^^^ +Wildcard Resource Types +^^^^^^^^^^^^^^^^^^^^^^^ In the incremental protocol variants, the server signals the client that a resource should be deleted via the :ref:`removed_resources ` -field of the response for wildcard resource types like -:ref:`Listener ` and :ref:`Cluster `. -This tells the client to remove the resource from its local cache. +field of the response. This tells the client to remove the resource from its local cache. -In the SotW protocol variants, the criteria for deleting resources is more complex. For wildcard resource types like -:ref:`Listener ` and :ref:`Cluster ` -if a previously seen resource is not present in a new response, that indicates that the resource +In the SotW protocol variants, the criteria for deleting is more complex. If a previously seen resource +is not present in a new response, that indicates that the resource has been removed, and the client must delete it; a response containing no resources means to delete all resources of that type. -For other resource types, in both SotW and incremental protocol variants, deletions are indicated +Other Resource Types +^^^^^^^^^^^^^^^^^^^^ +In both SotW and incremental protocol variants, deletions are indicated implicitly by parent resources being changed to no longer refer to a child resource. For example, when the client receives an LDS update removing a :ref:`Listener ` that was previously pointing to :ref:`RouteConfiguration ` A, From 572fac040cf5a14107743f60f69bd7e2513bd8c1 Mon Sep 17 00:00:00 2001 From: Rama Chavali Date: Fri, 25 Mar 2022 16:33:44 +0530 Subject: [PATCH 4/7] lint Signed-off-by: Rama Chavali --- docs/root/api-docs/xds_protocol.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/root/api-docs/xds_protocol.rst b/docs/root/api-docs/xds_protocol.rst index eb5d42f35f5eb..2d8aae650a613 100644 --- a/docs/root/api-docs/xds_protocol.rst +++ b/docs/root/api-docs/xds_protocol.rst @@ -511,9 +511,8 @@ all resources of that type. Other Resource Types ^^^^^^^^^^^^^^^^^^^^ -In both SotW and incremental protocol variants, deletions are indicated -implicitly by parent resources being changed to no longer refer to a child resource. For example, -when the client receives an LDS update removing a :ref:`Listener ` +In both SotW and incremental protocol variants, deletions are indicated implicitly by parent resources being +changed to no longer refer to a child resource. For example, when the client receives an LDS update removing a :ref:`Listener ` that was previously pointing to :ref:`RouteConfiguration ` A, if no other :ref:`Listener ` is pointing to :ref:`RouteConfiguration ` A, then the client may delete A. For those resource types, From 716d1f1573b0f97c6589c75de6e2a9983465aa36 Mon Sep 17 00:00:00 2001 From: Rama Chavali Date: Fri, 25 Mar 2022 16:48:39 +0530 Subject: [PATCH 5/7] fix space Signed-off-by: Rama Chavali --- docs/root/api-docs/xds_protocol.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/root/api-docs/xds_protocol.rst b/docs/root/api-docs/xds_protocol.rst index 2d8aae650a613..1f40061810c90 100644 --- a/docs/root/api-docs/xds_protocol.rst +++ b/docs/root/api-docs/xds_protocol.rst @@ -505,9 +505,8 @@ deleted via the :ref:`removed_resources Date: Fri, 25 Mar 2022 17:15:22 +0530 Subject: [PATCH 6/7] fix space Signed-off-by: Rama Chavali --- docs/root/api-docs/xds_protocol.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/root/api-docs/xds_protocol.rst b/docs/root/api-docs/xds_protocol.rst index 1f40061810c90..5d702c9bb4fcd 100644 --- a/docs/root/api-docs/xds_protocol.rst +++ b/docs/root/api-docs/xds_protocol.rst @@ -506,7 +506,7 @@ field of the response. This tells the client to remove the resource from its loc In the SotW protocol variants, the criteria for deleting is more complex. If a previously seen resource is not present in a new response, that indicates that the resource has been removed, and the client must -delete it; a response containing no resources means to delete all resources of that type. +delete it; a response containing no resources means to delete all resources of that type. Other Resource Types ^^^^^^^^^^^^^^^^^^^^ From d9a87eeda02e1e966e3bfdba76f00aa042f01931 Mon Sep 17 00:00:00 2001 From: Rama Chavali Date: Fri, 25 Mar 2022 20:02:55 +0530 Subject: [PATCH 7/7] change header type Signed-off-by: Rama Chavali --- docs/root/api-docs/xds_protocol.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/root/api-docs/xds_protocol.rst b/docs/root/api-docs/xds_protocol.rst index 5d702c9bb4fcd..6e9f8ad7af5d4 100644 --- a/docs/root/api-docs/xds_protocol.rst +++ b/docs/root/api-docs/xds_protocol.rst @@ -499,7 +499,7 @@ Deleting Resources ^^^^^^^^^^^^^^^^^^ Wildcard Resource Types -^^^^^^^^^^^^^^^^^^^^^^^ +""""""""""""""""""""""" In the incremental protocol variants, the server signals the client that a resource should be deleted via the :ref:`removed_resources ` field of the response. This tells the client to remove the resource from its local cache. @@ -509,7 +509,7 @@ is not present in a new response, that indicates that the resource has been remo delete it; a response containing no resources means to delete all resources of that type. Other Resource Types -^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""" In both SotW and incremental protocol variants, deletions are indicated implicitly by parent resources being changed to no longer refer to a child resource. For example, when the client receives an LDS update removing a :ref:`Listener ` that was previously pointing to :ref:`RouteConfiguration ` A,