diff --git a/envoy/admin/v3/config_dump.proto b/envoy/admin/v3/config_dump.proto index b3e5510a..49c20853 100644 --- a/envoy/admin/v3/config_dump.proto +++ b/envoy/admin/v3/config_dump.proto @@ -17,6 +17,31 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // [#protodoc-title: ConfigDump] +// Resource status from the view of a xDS client, which tells the synchronization +// status between the xDS client and the xDS server. +enum ClientResourceStatus { + // Resource status is not available/unknown. + UNKNOWN = 0; + + // Client requested this resource but hasn't received any update from management + // server. The client will not fail requests, but will queue them until update + // arrives or the client times out waiting for the resource. + REQUESTED = 1; + + // This resource has been requested by the client but has either not been + // delivered by the server or was previously delivered by the server and then + // subsequently removed from resources provided by the server. For more + // information, please refer to the :ref:`"Knowing When a Requested Resource + // Does Not Exist" ` section. + DOES_NOT_EXIST = 2; + + // Client received this resource and replied with ACK. + ACKED = 3; + + // Client received this resource and replied with NACK. + NACKED = 4; +} + // The :ref:`/config_dump ` admin endpoint uses this wrapper // message to maintain and serve arbitrary configuration information from any component in Envoy. message ConfigDump { @@ -114,7 +139,7 @@ message ListenersConfigDump { } // Describes a dynamically loaded listener via the LDS API. - // [#next-free-field: 6] + // [#next-free-field: 7] message DynamicListener { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v2alpha.ListenersConfigDump.DynamicListener"; @@ -143,6 +168,10 @@ message ListenersConfigDump { // resource along with the reason and timestamp. For successfully updated or // acknowledged resource, this field should be empty. UpdateFailureState error_state = 5; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 6; } // This is the :ref:`version_info ` in the @@ -177,6 +206,7 @@ message ClustersConfigDump { } // Describes a dynamically loaded cluster via the CDS API. + // [#next-free-field: 6] message DynamicCluster { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v2alpha.ClustersConfigDump.DynamicCluster"; @@ -199,6 +229,10 @@ message ClustersConfigDump { // acknowledged resource, this field should be empty. // [#not-implemented-hide:] UpdateFailureState error_state = 4; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 5; } // This is the :ref:`version_info ` in the @@ -240,6 +274,7 @@ message RoutesConfigDump { google.protobuf.Timestamp last_updated = 2; } + // [#next-free-field: 6] message DynamicRouteConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v2alpha.RoutesConfigDump.DynamicRouteConfig"; @@ -261,6 +296,10 @@ message RoutesConfigDump { // acknowledged resource, this field should be empty. // [#not-implemented-hide:] UpdateFailureState error_state = 4; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 5; } // The statically loaded route configs. @@ -292,7 +331,7 @@ message ScopedRoutesConfigDump { google.protobuf.Timestamp last_updated = 3; } - // [#next-free-field: 6] + // [#next-free-field: 7] message DynamicScopedRouteConfigs { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v2alpha.ScopedRoutesConfigDump.DynamicScopedRouteConfigs"; @@ -317,6 +356,10 @@ message ScopedRoutesConfigDump { // acknowledged resource, this field should be empty. // [#not-implemented-hide:] UpdateFailureState error_state = 5; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 6; } // The statically loaded scoped route configs. @@ -332,7 +375,7 @@ message SecretsConfigDump { "envoy.admin.v2alpha.SecretsConfigDump"; // DynamicSecret contains secret information fetched via SDS. - // [#next-free-field: 6] + // [#next-free-field: 7] message DynamicSecret { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v2alpha.SecretsConfigDump.DynamicSecret"; @@ -357,6 +400,10 @@ message SecretsConfigDump { // acknowledged resource, this field should be empty. // [#not-implemented-hide:] UpdateFailureState error_state = 5; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 6; } // StaticSecret specifies statically loaded secret in bootstrap. @@ -400,6 +447,7 @@ message EndpointsConfigDump { google.protobuf.Timestamp last_updated = 2; } + // [#next-free-field: 6] message DynamicEndpointConfig { // [#not-implemented-hide:] This is the per-resource version information. This version is currently taken from the // :ref:`version_info ` field at the time that @@ -418,6 +466,10 @@ message EndpointsConfigDump { // acknowledged resource, this field should be empty. // [#not-implemented-hide:] UpdateFailureState error_state = 4; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 5; } // The statically loaded endpoint configs. diff --git a/envoy/admin/v4alpha/config_dump.proto b/envoy/admin/v4alpha/config_dump.proto index 3f5610be..2eb1e73c 100644 --- a/envoy/admin/v4alpha/config_dump.proto +++ b/envoy/admin/v4alpha/config_dump.proto @@ -17,6 +17,31 @@ option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSIO // [#protodoc-title: ConfigDump] +// Resource status from the view of a xDS client, which tells the synchronization +// status between the xDS client and the xDS server. +enum ClientResourceStatus { + // Resource status is not available/unknown. + UNKNOWN = 0; + + // Client requested this resource but hasn't received any update from management + // server. The client will not fail requests, but will queue them until update + // arrives or the client times out waiting for the resource. + REQUESTED = 1; + + // This resource has been requested by the client but has either not been + // delivered by the server or was previously delivered by the server and then + // subsequently removed from resources provided by the server. For more + // information, please refer to the :ref:`"Knowing When a Requested Resource + // Does Not Exist" ` section. + DOES_NOT_EXIST = 2; + + // Client received this resource and replied with ACK. + ACKED = 3; + + // Client received this resource and replied with NACK. + NACKED = 4; +} + // The :ref:`/config_dump ` admin endpoint uses this wrapper // message to maintain and serve arbitrary configuration information from any component in Envoy. message ConfigDump { @@ -111,7 +136,7 @@ message ListenersConfigDump { } // Describes a dynamically loaded listener via the LDS API. - // [#next-free-field: 6] + // [#next-free-field: 7] message DynamicListener { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v3.ListenersConfigDump.DynamicListener"; @@ -140,6 +165,10 @@ message ListenersConfigDump { // resource along with the reason and timestamp. For successfully updated or // acknowledged resource, this field should be empty. UpdateFailureState error_state = 5; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 6; } // This is the :ref:`version_info ` in the @@ -173,6 +202,7 @@ message ClustersConfigDump { } // Describes a dynamically loaded cluster via the CDS API. + // [#next-free-field: 6] message DynamicCluster { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v3.ClustersConfigDump.DynamicCluster"; @@ -195,6 +225,10 @@ message ClustersConfigDump { // acknowledged resource, this field should be empty. // [#not-implemented-hide:] UpdateFailureState error_state = 4; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 5; } // This is the :ref:`version_info ` in the @@ -235,6 +269,7 @@ message RoutesConfigDump { google.protobuf.Timestamp last_updated = 2; } + // [#next-free-field: 6] message DynamicRouteConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v3.RoutesConfigDump.DynamicRouteConfig"; @@ -256,6 +291,10 @@ message RoutesConfigDump { // acknowledged resource, this field should be empty. // [#not-implemented-hide:] UpdateFailureState error_state = 4; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 5; } // The statically loaded route configs. @@ -287,7 +326,7 @@ message ScopedRoutesConfigDump { google.protobuf.Timestamp last_updated = 3; } - // [#next-free-field: 6] + // [#next-free-field: 7] message DynamicScopedRouteConfigs { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v3.ScopedRoutesConfigDump.DynamicScopedRouteConfigs"; @@ -312,6 +351,10 @@ message ScopedRoutesConfigDump { // acknowledged resource, this field should be empty. // [#not-implemented-hide:] UpdateFailureState error_state = 5; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 6; } // The statically loaded scoped route configs. @@ -326,7 +369,7 @@ message SecretsConfigDump { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v3.SecretsConfigDump"; // DynamicSecret contains secret information fetched via SDS. - // [#next-free-field: 6] + // [#next-free-field: 7] message DynamicSecret { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v3.SecretsConfigDump.DynamicSecret"; @@ -351,6 +394,10 @@ message SecretsConfigDump { // acknowledged resource, this field should be empty. // [#not-implemented-hide:] UpdateFailureState error_state = 5; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 6; } // StaticSecret specifies statically loaded secret in bootstrap. @@ -399,6 +446,7 @@ message EndpointsConfigDump { google.protobuf.Timestamp last_updated = 2; } + // [#next-free-field: 6] message DynamicEndpointConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v3.EndpointsConfigDump.DynamicEndpointConfig"; @@ -420,6 +468,10 @@ message EndpointsConfigDump { // acknowledged resource, this field should be empty. // [#not-implemented-hide:] UpdateFailureState error_state = 4; + + // The client status of this resource. + // [#not-implemented-hide:] + ClientResourceStatus client_status = 5; } // The statically loaded endpoint configs. diff --git a/envoy/service/status/v3/csds.proto b/envoy/service/status/v3/csds.proto index 63414971..7d2a59ae 100644 --- a/envoy/service/status/v3/csds.proto +++ b/envoy/service/status/v3/csds.proto @@ -93,13 +93,17 @@ message PerXdsConfig { // Config status generated by management servers. Will not be present if the // CSDS server is an xDS client. - ConfigStatus status = 1 [(udpa.annotations.field_migrate).oneof_promotion = "status_config"]; + ConfigStatus status = 1; // Client config status is populated by xDS clients. Will not be present if // the CSDS server is an xDS server. No matter what the client config status // is, xDS clients should always dump the most recent accepted xDS config. - ClientConfigStatus client_status = 7 - [(udpa.annotations.field_migrate).oneof_promotion = "status_config"]; + // + // .. attention:: + // This field is deprecated. Use :ref:`ClientResourceStatus + // ` for per-resource + // config status instead. + ClientConfigStatus client_status = 7 [deprecated = true]; oneof per_xds_config { admin.v3.ListenersConfigDump listener_config = 2; diff --git a/envoy/service/status/v4alpha/csds.proto b/envoy/service/status/v4alpha/csds.proto index 3e2a5f40..b8720330 100644 --- a/envoy/service/status/v4alpha/csds.proto +++ b/envoy/service/status/v4alpha/csds.proto @@ -90,16 +90,13 @@ message PerXdsConfig { option (udpa.annotations.versioning).previous_message_type = "envoy.service.status.v3.PerXdsConfig"; - oneof status_config { - // Config status generated by management servers. Will not be present if the - // CSDS server is an xDS client. - ConfigStatus status = 1; - - // Client config status is populated by xDS clients. Will not be present if - // the CSDS server is an xDS server. No matter what the client config status - // is, xDS clients should always dump the most recent accepted xDS config. - ClientConfigStatus client_status = 7; - } + reserved 7; + + reserved "client_status"; + + // Config status generated by management servers. Will not be present if the + // CSDS server is an xDS client. + ConfigStatus status = 1; oneof per_xds_config { admin.v4alpha.ListenersConfigDump listener_config = 2; diff --git a/xds_protocol.rst b/xds_protocol.rst index 39c45e3c..2b9e127a 100644 --- a/xds_protocol.rst +++ b/xds_protocol.rst @@ -507,6 +507,8 @@ if no other :ref:`Listener ` is pointing to :ref:`RouteC an empty :ref:`DiscoveryResponse ` is effectively a no-op from the client's perspective. +.. _xds_protocol_resource_not_existed: + Knowing When a Requested Resource Does Not Exist ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^