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,54 @@ 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 priorirty 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:: none
+
+  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:: none
+
+  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 comined, which will exclude both previously attempted hosts as well as previously attempted priorities.
+
+.. code-block:: none
+
+  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,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.
+  **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>`.