Merge branch 'main' into docs-version-histories

Signed-off-by: Ryan Northey <ryan@synca.io>

api/envoy/config/metrics/v3/metrics_service.proto

@@ -38,4 +38,9 @@ message MetricsServiceConfig {
   // Eventually (https://github.com/envoyproxy/envoy/issues/10968) if this value is not set, the
   // sink will take updates from the :ref:`MetricsResponse <envoy_api_msg_service.metrics.v3.StreamMetricsResponse>`.
   google.protobuf.BoolValue report_counters_as_deltas = 2;
+
+  // If true, metrics will have their tags emitted as labels on the metrics objects sent to the MetricsService,
+  // and the tag extracted name will be used instead of the full name, which may contain values used by the tag
+  // extractor or additional tags added during stats creation.
+  bool emit_tags_as_labels = 4;
 }

docs/requirements.txt

@@ -219,7 +219,9 @@ typing-extensions==3.7.4.3 \
     --hash=sha256:7cb407020f00f7bfc3cb3e7881628838e69d8f3fcab2f64742a5e76b2f841918 \
     --hash=sha256:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c \
     --hash=sha256:dafc7639cde7f1b6e1acc0f457842a83e722ccca8eef5270af2d74792619a89f
-    # via gitpython
+    # via
+    #   -r docs/requirements.txt
+    #   gitpython
 urllib3==1.26.4 \
     --hash=sha256:2f4da4594db7e1e110a944bb1b551fdf4e6c136ad42e4234131391e21eb5b0df \
     --hash=sha256:e7b021f7241115872f92f43c6508082facffbd1c048e3c6e2bb9c2a157e28937

docs/root/api/client_features.rst

@@ -4,8 +4,8 @@ Well Known Client Features
 ==========================
 
 Authoritative list of features that an xDS client may support. An xDS client supplies the list of
-features it supports in the :ref:`client_features <envoy_api_field_core.Node.client_features>` field.
-Client features use reverse DNS naming scheme, for example `com.acme.feature`.
+features it supports in the :ref:`client_features <envoy_v3_api_field_config.core.v3.node.client_features>` field.
+Client features use reverse DNS naming scheme, for example ``com.acme.feature``.
 
 Currently Defined Client Features
 ---------------------------------
@@ -17,7 +17,7 @@ Currently Defined Client Features
   *udpa.type.v1.TypedStruct* only.
 - **envoy.lb.does_not_support_overprovisioning**: This feature indicates that the client does not
   support overprovisioning for priority failover and locality weighting as configured by the
-  :ref:`overprovisioning_factor<envoy_api_field_ClusterLoadAssignment.Policy.overprovisioning_factor>`
+  :ref:`overprovisioning_factor <envoy_v3_api_field_config.endpoint.v3.clusterloadassignment.policy.overprovisioning_factor>`
   field. If graceful failover functionality is required, it must be supplied by the management
   server.
 - **envoy.lrs.supports_send_all_clusters**: This feature indicates that the client supports

docs/root/configuration/http/http_conn_man/stats.rst

@@ -142,7 +142,7 @@ On the upstream side all http2 statistics are rooted at *cluster.<name>.http2.*
    rx_messaging_error, Counter, Total number of invalid received frames that violated `section 8 <https://tools.ietf.org/html/rfc7540#section-8>`_ of the HTTP/2 spec. This will result in a *tx_reset*
    rx_reset, Counter, Total number of reset stream frames received by Envoy
    trailers, Counter, Total number of trailers seen on requests coming from downstream
-   tx_flush_timeout, Counter, Total number of :ref:`stream idle timeouts <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.stream_idle_timeout>` waiting for open stream window to flush the remainder of a stream
+   tx_flush_timeout, Counter, Total number of :ref:`stream idle timeouts <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stream_idle_timeout>` waiting for open stream window to flush the remainder of a stream
    tx_reset, Counter, Total number of reset stream frames transmitted by Envoy
    keepalive_timeout, Counter, Total number of connections closed due to :ref:`keepalive timeout <envoy_v3_api_field_config.core.v3.KeepaliveSettings.timeout>`
    streams_active, Gauge, Active streams as observed by the codec

docs/root/configuration/http/http_filters/aws_lambda_filter.rst

@@ -187,13 +187,12 @@ Statistics
 ----------
 
 The AWS Lambda filter outputs statistics in the *http.<stat_prefix>.aws_lambda.* namespace. The
-:ref:`stat prefix <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.stat_prefix>`
+| :ref:`stat prefix <envoy_v3_api_field_extensions.filters.network.http_connection_manager.v3.HttpConnectionManager.stat_prefix>`
 comes from the owning HTTP connection manager.
 
 .. csv-table::
   :header: Name, Type, Description
   :widths: 1, 1, 2
 
-  server_error, Counter, Total requests that returned invalid JSON response (see :ref:`payload_passthrough <envoy_api_msg_config.filter.http.aws_lambda.v2alpha.config>`)
+  server_error, Counter, Total requests that returned invalid JSON response (see :ref:`payload_passthrough <envoy_v3_api_msg_extensions.filters.http.aws_lambda.v3.Config>`)
   upstream_rq_payload_size, Histogram, Size in bytes of the request after JSON-tranformation (if any).
-

docs/root/configuration/http/http_filters/fault_filter.rst

@@ -47,7 +47,7 @@ x-envoy-fault-abort-grpc-request
   the gRPC status code to return in response to a request. Its value range is [0, UInt32.Max] instead of [0, 16]
   to allow testing even not well-defined gRPC status codes. When this header is set, the HTTP response status code
   will be set to 200. In order for the header to work, :ref:`header_abort
-  <envoy_api_field_config.filter.http.fault.v2.FaultAbort.header_abort>` needs to be set. If both
+  <envoy_v3_api_field_extensions.filters.http.fault.v3.FaultAbort.header_abort>` needs to be set. If both
   *x-envoy-fault-abort-request* and *x-envoy-fault-abort-grpc-request* headers are set then
   *x-envoy-fault-abort-grpc-request* header will be **ignored** and fault response http status code will be
   set to *x-envoy-fault-abort-request* header value.
@@ -163,7 +163,7 @@ fault.http.abort.grpc_status
   aborted if the headers match. Defaults to the gRPC status code specified in the config.
   If this field is missing from both the runtime and the config, gRPC status code in the response
   will be derived from *fault.http.abort.http_status* field. This runtime key is only available when
-  the filter is :ref:`configured for abort <envoy_api_field_config.filter.http.fault.v2.HTTPFault.abort>`.
+  the filter is :ref:`configured for abort <envoy_v3_api_field_extensions.filters.http.fault.v3.HTTPFault.abort>`.
 
 fault.http.delay.fixed_delay_percent
   % of requests that will be delayed if the headers match. Defaults to the

docs/root/configuration/listeners/network_filters/sni_dynamic_forward_proxy_filter.rst

@@ -9,14 +9,14 @@ SNI dynamic forward proxy
 
 Through the combination of :ref:`TLS inspector <config_listener_filters_tls_inspector>` listener filter,
 this network filter and the
-:ref:`dynamic forward proxy cluster <envoy_api_msg_config.cluster.dynamic_forward_proxy.v2alpha.ClusterConfig>`,
+:ref:`dynamic forward proxy cluster <envoy_v3_api_msg_extensions.clusters.dynamic_forward_proxy.v3.ClusterConfig>`,
 Envoy supports SNI based dynamic forward proxy. The implementation works just like the
 :ref:`HTTP dynamic forward proxy <arch_overview_http_dynamic_forward_proxy>`, but using the value in
 SNI as target host instead.
 
 The following is a complete configuration that configures both this filter
 as well as the :ref:`dynamic forward proxy cluster
-<envoy_api_msg_config.cluster.dynamic_forward_proxy.v2alpha.ClusterConfig>`. Both filter and cluster
+<envoy_v3_api_msg_extensions.clusters.dynamic_forward_proxy.v3.ClusterConfig>`. Both filter and cluster
 must be configured together and point to the same DNS cache parameters for Envoy to operate as an
 SNI dynamic forward proxy.
 

docs/root/configuration/listeners/udp_filters/dns_filter.rst

@@ -123,7 +123,7 @@ adhere to the convention outlined in the RFC.
 
 The filter can also consume its domain configuration from an external DNS table. The same entities
 appearing in the static configuration can be stored as JSON or YAML in a separate file and referenced
-using the :ref:`external_dns_table DataSource <envoy_api_msg_core.DataSource>` directive:
+using the :ref:`external_dns_table DataSource <envoy_v3_api_msg_config.core.v3.datasource>` directive:
 
 Example External DnsTable Configuration
 ---------------------------------------

docs/root/configuration/observability/access_log/overview.rst

@@ -3,4 +3,4 @@ Overview
 
 * Access logging :ref:`architecture overview <arch_overview_access_logs>`
 * :ref:`Configuration overview <config_access_log>`
-* :ref:`v2 API reference <envoy_api_msg_config.filter.accesslog.v2.AccessLog>`
+* :ref:`v3 API reference <envoy_v3_api_msg_config.accesslog.v3.AccessLog>`

docs/root/configuration/operations/tools/router_check.rst

@@ -168,7 +168,7 @@ validate
     and "date" fields, as well as custom headers set in the input or by the route. The header fields are checked
     after all other test cases. Thus, the header fields checked will be those of the redirected or rewritten
     routes when applicable.
-    - Matchers are specified as :ref:`HeaderMatchers <envoy_api_msg_route.HeaderMatcher>`, and behave the same way.
+    - Matchers are specified as :ref:`HeaderMatchers <envoy_v3_api_msg_config.route.v3.headermatcher>`, and behave the same way.
 
 Coverage
 --------

docs/root/configuration/overview/versioning.rst

@@ -1,25 +1,11 @@
 Versioning
 ----------
 
-The Envoy xDS APIs follow a well defined :repo:`versioning scheme <api/API_VERSIONING.md>`. Envoy
-supports :ref:`multiple major versions <api_supported_versions>` at any point in time. The examples
-in this section are taken from the v2 xDS API.
+The Envoy xDS APIs follow a well defined :repo:`versioning scheme <api/API_VERSIONING.md>`.
 
 Envoy has API versions for both the xDS transport, i.e. the wire protocol for moving resources
 between a management server and Envoy, and for resources. These are known as the transport and
 resource API version respectively.
 
-The transport and resource version may be mixed. For example, v3 resources may be transferred over
-the v2 transport protocol. In addition, an Envoy may consume mixed resource versions for distinct
-resource types. For example, :ref:`v3 Clusters <envoy_v3_api_msg_config.cluster.v3.Cluster>` may be
-used alongside :ref:`v2 Listeners <envoy_api_msg_Listener>`.
-
 Both the transport and resource API versions follow the API versioning support and deprecation
 :repo:`policy <api/API_VERSIONING.md>`.
-
-.. note::
-
-    Envoy will internally operate at the latest xDS resource version and all supported versioned
-    resources will be transparently upgrading to this latest version on configuration ingestion. For
-    example, v2 and v3 resources, delivered over either a v2 or v3 transport, or any mix thereof,
-    will be internally converted into v3 resources.

docs/root/configuration/overview/xds_api.rst

@@ -260,7 +260,7 @@ is set in the :ref:`rds
 
 .. note::
 
-    The management server responding to these endpoints must respond with a :ref:`DiscoveryResponse <envoy_api_msg_DiscoveryResponse>`
+    The management server responding to these endpoints must respond with a :ref:`DiscoveryResponse <envoy_v3_api_msg_service.discovery.v3.discoveryresponse>`
     along with a HTTP status of 200. Additionally, if the configuration that would be supplied has not changed (as indicated by the version
     supplied by the Envoy client) then the management server can respond with an empty body and a HTTP status of 304.
 
@@ -377,9 +377,9 @@ Currently the behavior when a TTL expires is that the resource is *removed* (as
 previous version). As such, this feature should primarily be used for use cases where the absence of the resource
 is preferred instead of the temporary version, e.g. when using RTDS to apply a temporary runtime override.
 
-The TTL is specified on the :ref:`Resource <envoy_api_msg_Resource>` proto: for Delta xDS this is specified directly
+The TTL is specified on the :ref:`Resource <envoy_v3_api_msg_service.discovery.v3.resource>` proto: for Delta xDS this is specified directly
 within the response, while for SotW xDS the server may wrap individual resources listed in the response within a
-:ref:`Resource <envoy_api_msg_Resource>` in order to specify a TTL value.
+:ref:`Resource <envoy_v3_api_msg_service.discovery.v3.resource>` in order to specify a TTL value.
 
 The server can refresh or modify the TTL by issuing another response for the same version. In this case the resource
 itself does not have to be included.

docs/root/intro/arch_overview/advanced/attributes.rst

@@ -153,7 +153,7 @@ Data exchanged between filters is available as the following attributes:
    :header: Attribute, Type, Description
    :widths: 1, 1, 4
 
-   metadata, :ref:`Metadata<envoy_api_msg_core.Metadata>`, Dynamic request metadata
+   metadata, :ref:`Metadata<envoy_v3_api_msg_config.core.v3.metadata>`, Dynamic request metadata
    filter_state, "map<string, bytes>", Mapping from a filter state name to its serialized string value
 
 Note that these attributes may change during the life of a request as the data can be
@@ -171,14 +171,14 @@ In addition to all above, the following extra attributes are available to Wasm e
    plugin_name, string, Plugin name
    plugin_root_id, string, Plugin root ID
    plugin_vm_id, string, Plugin VM ID
-   node, :ref:`Node<envoy_api_msg_core.Node>`, Local node description
+   node, :ref:`Node<envoy_v3_api_msg_config.core.v3.node>`, Local node description
    cluster_name, string, Upstream cluster name
-   cluster_metadata, :ref:`Metadata<envoy_api_msg_core.Metadata>`, Upstream cluster metadata
+   cluster_metadata, :ref:`Metadata<envoy_v3_api_msg_config.core.v3.metadata>`, Upstream cluster metadata
    listener_direction, int, Enumeration value of the :ref:`listener traffic direction<envoy_v3_api_field_config.listener.v3.Listener.traffic_direction>`
-   listener_metadata, :ref:`Metadata<envoy_api_msg_core.Metadata>`, Listener metadata
+   listener_metadata, :ref:`Metadata<envoy_v3_api_msg_config.core.v3.metadata>`, Listener metadata
    route_name, string, Route name
-   route_metadata, :ref:`Metadata<envoy_api_msg_core.Metadata>`, Route metadata
-   upstream_host_metadata, :ref:`Metadata<envoy_api_msg_core.Metadata>`, Upstream host metadata
+   route_metadata, :ref:`Metadata<envoy_v3_api_msg_config.core.v3.metadata>`, Route metadata
+   upstream_host_metadata, :ref:`Metadata<envoy_v3_api_msg_config.core.v3.metadata>`, Upstream host metadata
 
 Path expressions
 ----------------

docs/root/intro/arch_overview/http/http_routing.rst

@@ -53,8 +53,8 @@ Route Scope
 -----------
 
 Scoped routing enables Envoy to put constraints on search space of domains and route rules.
-A :ref:`Route Scope<envoy_api_msg_ScopedRouteConfiguration>` associates a key with a :ref:`route table <arch_overview_http_routing_route_table>`.
-For each request, a scope key is computed dynamically by the HTTP connection manager to pick the :ref:`route table<envoy_api_msg_RouteConfiguration>`.
+A :ref:`Route Scope <envoy_v3_api_msg_config.route.v3.scopedrouteconfiguration>` associates a key with a :ref:`route table <arch_overview_http_routing_route_table>`.
+For each request, a scope key is computed dynamically by the HTTP connection manager to pick the :ref:`route table <envoy_v3_api_msg_config.route.v3.routeconfiguration>`.
 RouteConfiguration associated with scope can be loaded on demand with :ref:`v3 API reference <envoy_v3_api_msg_extensions.filters.http.on_demand.v3.OnDemand>` configured and on demand filed in protobuf set to true.
 
 The Scoped RDS (SRDS) API contains a set of :ref:`Scopes <envoy_v3_api_msg_config.route.v3.ScopedRouteConfiguration>` resources, each defining independent routing configuration,
@@ -110,7 +110,7 @@ headers <config_http_filters_router_headers_consumed>`. The following configurat
 * **Retry conditions**: Envoy can retry on different types of conditions depending on application
   requirements. For example, network failure, all 5xx response codes, idempotent 4xx response codes,
   etc.
-* **Retry budgets**: Envoy can limit the proportion of active requests via :ref:`retry budgets <envoy_v3_api_field_config.cluster.v3.CircuitBreakers.Thresholds.retry_budget>` that can be retries to
+* **Retry budgets**: Envoy can limit the proportion of active requests via :ref:`retry budgets <envoy_v3_api_field_config.cluster.v3.circuitbreakers.thresholds.retry_budget>` that can be retries to
   prevent their contribution to large increases in traffic volume.
 * **Host selection retry plugins**: Envoy can be configured to apply additional logic to the host
   selection logic when selecting hosts for retries. Specifying a
@@ -122,7 +122,7 @@ headers <config_http_filters_router_headers_consumed>`. The following configurat
 
 Note that Envoy retries requests when :ref:`x-envoy-overloaded
 <config_http_filters_router_x-envoy-overloaded_set>` is present. It is recommended to either configure
-:ref:`retry budgets (preferred) <envoy_api_field_cluster.CircuitBreakers.Thresholds.retry_budget>` or set
+:ref:`retry budgets (preferred) <envoy_v3_api_field_config.cluster.v3.circuitbreakers.thresholds.retry_budget>` or set
 :ref:`maximum active retries circuit breaker <arch_overview_circuit_break>` to an appropriate value to avoid retry storms.
 
 .. _arch_overview_http_routing_hedging:

docs/root/intro/arch_overview/upstream/load_balancing/excluded.rst

@@ -22,7 +22,7 @@ Currently, the following two conditions can lead to a host being excluded when u
 health checking:
 
 * Using the :ref:`ignore_new_hosts_until_first_hc
-  <envoy_api_field_Cluster.CommonLbConfig.ignore_new_hosts_until_first_hc>` cluster option.
+  <envoy_v3_api_field_config.cluster.v3.cluster.commonlbconfig.ignore_new_hosts_until_first_hc>` cluster option.
 * Receiving the :ref:`x-envoy-immediate-health-check-fail
   <config_http_filters_router_x-envoy-immediate-health-check-fail>` header in a normal routed
   response or in response to an :ref:`HTTP active health check