diff --git a/api/envoy/config/endpoint/v3/load_report.proto b/api/envoy/config/endpoint/v3/load_report.proto index 01eb7b12cf1a..3f067737ec25 100644 --- a/api/envoy/config/endpoint/v3/load_report.proto +++ b/api/envoy/config/endpoint/v3/load_report.proto @@ -17,11 +17,11 @@ option java_outer_classname = "LoadReportProto"; option java_multiple_files = true; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// These are stats Envoy reports to GLB every so often. Report frequency is -// defined by +// [#protodoc-title: Load Report] + +// These are stats Envoy reports to the management server at a frequency defined by // :ref:`LoadStatsResponse.load_reporting_interval`. // Stats per upstream region/zone and optionally per subzone. -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. // [#next-free-field: 9] message UpstreamLocalityStats { option (udpa.annotations.versioning).previous_message_type = @@ -60,7 +60,6 @@ message UpstreamLocalityStats { uint32 priority = 6; } -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. // [#next-free-field: 8] message UpstreamEndpointStats { option (udpa.annotations.versioning).previous_message_type = @@ -103,7 +102,6 @@ message UpstreamEndpointStats { repeated EndpointLoadMetricStats load_metric_stats = 5; } -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. message EndpointLoadMetricStats { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.endpoint.EndpointLoadMetricStats"; @@ -121,7 +119,6 @@ message EndpointLoadMetricStats { // Per cluster load stats. Envoy reports these stats a management server in a // :ref:`LoadStatsRequest` -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. // Next ID: 7 // [#next-free-field: 7] message ClusterStats { diff --git a/api/envoy/service/load_stats/v3/lrs.proto b/api/envoy/service/load_stats/v3/lrs.proto index d76356884a7a..76705ba77771 100644 --- a/api/envoy/service/load_stats/v3/lrs.proto +++ b/api/envoy/service/load_stats/v3/lrs.proto @@ -17,7 +17,15 @@ option java_multiple_files = true; option java_generic_services = true; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: Load reporting service] +// [#protodoc-title: Load Reporting service (LRS)] + +// Load Reporting Service is an Envoy API to emit load reports. Envoy will initiate a bi-directional +// stream with a management server. Upon connecting, the management server can send a +// :ref:`LoadStatsResponse ` to a node it is +// interested in getting the load reports for. Envoy in this node will start sending +// :ref:`LoadStatsRequest `. This is done periodically +// based on the :ref:`load reporting interval ` +// For details, take a look at the :ref:`Load Reporting Service sandbox example `. service LoadReportingService { // Advanced API to allow for multi-dimensional load balancing by remote @@ -53,7 +61,6 @@ service LoadReportingService { } // A load report Envoy sends to the management server. -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. message LoadStatsRequest { option (udpa.annotations.versioning).previous_message_type = "envoy.service.load_stats.v2.LoadStatsRequest"; @@ -67,7 +74,6 @@ message LoadStatsRequest { // The management server sends envoy a LoadStatsResponse with all clusters it // is interested in learning load stats about. -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. message LoadStatsResponse { option (udpa.annotations.versioning).previous_message_type = "envoy.service.load_stats.v2.LoadStatsResponse"; @@ -82,6 +88,7 @@ message LoadStatsResponse { bool send_all_clusters = 4; // The minimum interval of time to collect stats over. This is only a minimum for two reasons: + // // 1. There may be some delay from when the timer fires until stats sampling occurs. // 2. For clusters that were already feature in the previous *LoadStatsResponse*, any traffic // that is observed in between the corresponding previous *LoadStatsRequest* and this diff --git a/docs/root/api-v3/config/config.rst b/docs/root/api-v3/config/config.rst index ba7ca7e70f76..e1ccac77719d 100644 --- a/docs/root/api-v3/config/config.rst +++ b/docs/root/api-v3/config/config.rst @@ -18,3 +18,4 @@ Extensions retry/retry trace/trace internal_redirect/internal_redirect + endpoint/endpoint diff --git a/docs/root/api-v3/config/endpoint/endpoint.rst b/docs/root/api-v3/config/endpoint/endpoint.rst new file mode 100644 index 000000000000..c1b64b1e4651 --- /dev/null +++ b/docs/root/api-v3/config/endpoint/endpoint.rst @@ -0,0 +1,8 @@ +Endpoint +======== + +.. toctree:: + :glob: + :maxdepth: 2 + + v3/* \ No newline at end of file diff --git a/docs/root/api-v3/service/service.rst b/docs/root/api-v3/service/service.rst index 6ad5674d4bde..de8110cf5fbd 100644 --- a/docs/root/api-v3/service/service.rst +++ b/docs/root/api-v3/service/service.rst @@ -6,6 +6,7 @@ Services :maxdepth: 2 accesslog/v3/* + load_stats/v3/* auth/v3/* health/v3/* metrics/v3/* diff --git a/docs/root/intro/arch_overview/upstream/load_reporting_service.rst b/docs/root/intro/arch_overview/upstream/load_reporting_service.rst new file mode 100644 index 000000000000..669bce160592 --- /dev/null +++ b/docs/root/intro/arch_overview/upstream/load_reporting_service.rst @@ -0,0 +1,15 @@ +.. _arch_overview_load_reporting_service: + +Load Reporting Service (LRS) +============================ + +The Load Reporting Service provides a mechanism by which Envoy can emit Load Reports to a management +server at a regular cadence. + +This will initiate a bi-directional stream with a management server. Upon connecting, the management +server can send a :ref:`LoadStatsResponse ` +to a node it is interested in getting the load reports for. Envoy in this node will start sending +:ref:`LoadStatsRequest `. This is done periodically +based on the :ref:`load reporting interval ` + +Envoy config with LRS can be found at :repo:`/examples/load-reporting-service/service-envoy-w-lrs.yaml`. diff --git a/docs/root/intro/arch_overview/upstream/upstream.rst b/docs/root/intro/arch_overview/upstream/upstream.rst index 112dc7885446..3c976f0212c3 100644 --- a/docs/root/intro/arch_overview/upstream/upstream.rst +++ b/docs/root/intro/arch_overview/upstream/upstream.rst @@ -13,3 +13,4 @@ Upstream clusters outlier circuit_breaking upstream_filters + load_reporting_service diff --git a/generated_api_shadow/envoy/config/endpoint/v3/load_report.proto b/generated_api_shadow/envoy/config/endpoint/v3/load_report.proto index 01eb7b12cf1a..3f067737ec25 100644 --- a/generated_api_shadow/envoy/config/endpoint/v3/load_report.proto +++ b/generated_api_shadow/envoy/config/endpoint/v3/load_report.proto @@ -17,11 +17,11 @@ option java_outer_classname = "LoadReportProto"; option java_multiple_files = true; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// These are stats Envoy reports to GLB every so often. Report frequency is -// defined by +// [#protodoc-title: Load Report] + +// These are stats Envoy reports to the management server at a frequency defined by // :ref:`LoadStatsResponse.load_reporting_interval`. // Stats per upstream region/zone and optionally per subzone. -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. // [#next-free-field: 9] message UpstreamLocalityStats { option (udpa.annotations.versioning).previous_message_type = @@ -60,7 +60,6 @@ message UpstreamLocalityStats { uint32 priority = 6; } -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. // [#next-free-field: 8] message UpstreamEndpointStats { option (udpa.annotations.versioning).previous_message_type = @@ -103,7 +102,6 @@ message UpstreamEndpointStats { repeated EndpointLoadMetricStats load_metric_stats = 5; } -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. message EndpointLoadMetricStats { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.endpoint.EndpointLoadMetricStats"; @@ -121,7 +119,6 @@ message EndpointLoadMetricStats { // Per cluster load stats. Envoy reports these stats a management server in a // :ref:`LoadStatsRequest` -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. // Next ID: 7 // [#next-free-field: 7] message ClusterStats { diff --git a/generated_api_shadow/envoy/service/load_stats/v3/lrs.proto b/generated_api_shadow/envoy/service/load_stats/v3/lrs.proto index d76356884a7a..76705ba77771 100644 --- a/generated_api_shadow/envoy/service/load_stats/v3/lrs.proto +++ b/generated_api_shadow/envoy/service/load_stats/v3/lrs.proto @@ -17,7 +17,15 @@ option java_multiple_files = true; option java_generic_services = true; option (udpa.annotations.file_status).package_version_status = ACTIVE; -// [#protodoc-title: Load reporting service] +// [#protodoc-title: Load Reporting service (LRS)] + +// Load Reporting Service is an Envoy API to emit load reports. Envoy will initiate a bi-directional +// stream with a management server. Upon connecting, the management server can send a +// :ref:`LoadStatsResponse ` to a node it is +// interested in getting the load reports for. Envoy in this node will start sending +// :ref:`LoadStatsRequest `. This is done periodically +// based on the :ref:`load reporting interval ` +// For details, take a look at the :ref:`Load Reporting Service sandbox example `. service LoadReportingService { // Advanced API to allow for multi-dimensional load balancing by remote @@ -53,7 +61,6 @@ service LoadReportingService { } // A load report Envoy sends to the management server. -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. message LoadStatsRequest { option (udpa.annotations.versioning).previous_message_type = "envoy.service.load_stats.v2.LoadStatsRequest"; @@ -67,7 +74,6 @@ message LoadStatsRequest { // The management server sends envoy a LoadStatsResponse with all clusters it // is interested in learning load stats about. -// [#not-implemented-hide:] Not configuration. TBD how to doc proto APIs. message LoadStatsResponse { option (udpa.annotations.versioning).previous_message_type = "envoy.service.load_stats.v2.LoadStatsResponse"; @@ -82,6 +88,7 @@ message LoadStatsResponse { bool send_all_clusters = 4; // The minimum interval of time to collect stats over. This is only a minimum for two reasons: + // // 1. There may be some delay from when the timer fires until stats sampling occurs. // 2. For clusters that were already feature in the previous *LoadStatsResponse*, any traffic // that is observed in between the corresponding previous *LoadStatsRequest* and this