docs: add retry plugin arch docs and remove not-implemented-hide

api/envoy/api/v2/route/route.proto

@@ -505,7 +505,6 @@ message RouteAction {
       google.protobuf.Struct config = 2;
     }
 
-    // [#not-implemented-hide:]
     // Specifies an implementation of a RetryPriority which is used to determine the
     // distribution of load across priorities used for retries.
     RetryPriority retry_priority = 4;
@@ -515,12 +514,10 @@ message RouteAction {
       google.protobuf.Struct config = 2;
     }
 
-    // [#not-implemented-hide:]
     // Specifies a collection of RetryHostPredicates that will be consulted when selecting a host
     // for retries. If any of the predicates reject the host, host selection will be reattempted.
     repeated RetryHostPredicate retry_host_predicate = 5;
 
-    // [#not-implemented-hide:]
     // The maximum number of times host selection will be reattempted before giving up, at which
     // point the host that was last selected will be routed to. If unspecified, this will default to
     // retrying once.

docs/root/intro/arch_overview/http_connection_management.rst

@@ -43,6 +43,72 @@ table <arch_overview_http_routing>`. The route table can be specified in one of
 * Statically.
 * Dynamically via the :ref:`RDS API <config_http_conn_man_rds>`.
 
+Retry plugin configuration
+--------------------------
+
+Normally during retries, hosts selected for retry attempts will be selected the same way the
+initial request is selected. To modify this behavior retry plugins can be used, which fall into
+two categories:
+
+* :ref:`**Retry host predicate** <envoy_api_field_route.RouteAction.RetryPolicy.retry_host_predicate>`.
+  These can be used to "reject" a host, which will cause host selection to be reattempted. If one or
+  more predicates have been configured, host selection will continue until either the host predicates
+  accept the host or a configurable
+  :ref:`max attempts <envoy_api_field_route.RouteAction.RetryPolicy.host_selection_retry_max_attempts>`
+  has been reached. Any number of these predicates can be specified, and the host will be rejected if
+  any of the predicates reject the host.
+* :ref:`**Retry priority** <envoy_api_field_route.RouteAction.RetryPolicy.retry_priority>`. These can
+  be used to adjust the priority load used when selecting a priority for a retry attempt. Only one such
+  plugin may be specified.
+
+These plugins can be combined to affect both host selection and priority load.
+
+For example, to configure retries to prefer hosts that haven't been attempted already, the builtin
+`envoy.retry_host_predicates.other_hosts` predicate can be used:
+
+.. code-block:: yaml
+
+  retry_policy:
+    retry_host_predicate:
+    - name: envoy.retry_host_predicates.previous_hosts
+    host_selection_retry_max_attempts: 3
+
+This will reject hosts previously attempted, retrying host selection a maximum of 3 times. The bound
+on attempts is necessary in order to deal with scenarios in which finding an acceptable host is either
+impossible (no hosts satisfy the predicate) or very unlikely (the only suitable host has a very low
+relative weight).
+
+To configure retries to attempt other priorities during retries, the built in
+`envoy.retry_priority.other_priorities` can be used.
+
+.. code-block:: yaml
+
+  retry_policy:
+    retry_priority:
+      name: envoy.retry_priorities.previous_priorities
+      config:
+        update_frequency: 2
+
+This will keep track of previously attempted priorities, and adjust the priority load such that other
+priorites will be targeted in subsequent retry attempts. The `update_frequency` parameter decides how
+often the priority load should be recalculated.
+
+These plugins can be combined, which will exclude both previously attempted hosts as well as
+previously attempted priorities.
+
+.. code-block:: yaml
+
+  retry_policy:
+    retry_host_predicate:
+    - name: envoy.retry_host_predicates.previous_hosts
+    host_selection_retry_max_attempts: 3
+    retry_priority:
+      name: envoy.retry_priorities.previous_priorities
+      config:
+        update_frequency: 2
+
+Envoy can be extended with custom retry plugins similar to how custom filters can be added.
+
 Timeouts
 --------
 

docs/root/intro/arch_overview/http_routing.rst

@@ -77,6 +77,13 @@ 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.
+  **Host selection retry plugins**: Envoy can be configured to apply additional logic to the host
+  selection logic when selecting hosts for retries. Specifying a
+  :ref:`retry host predicate <envoy_api_field_route.RouteAction.RetryPolicy.retry_host_predicate>`
+  allows for reattempting host selection when certain hosts are selected (e.g. when an already
+  attempted host is selected), while a
+  :ref:`retry prioririty <envoy_api_field_route.RouteAction.RetryPolicy.retry_priority>` can be
+  configured to adjust the priority load used when selecting a priority for retries.
 
 Note that retries may be disabled depending on the contents of the :ref:`x-envoy-overloaded
 <config_http_filters_router_x-envoy-overloaded_consumed>`.