docs: Add info about xDS cluster ordering in the Bootstrap (envoyprox…

…y#27706) Clarification for a workaround to envoyproxy#27702. Signed-off-by: Ali Beyad <[email protected]> Signed-off-by: Ryan Eskin <[email protected]>
reskin89 · Jul 11, 2023 · ed8dc75 · ed8dc75
1 parent 26e71ec
commit ed8dc75
Showing 1 changed file with 8 additions and 0 deletions.
diff --git a/docs/root/api-docs/xds_protocol.rst b/docs/root/api-docs/xds_protocol.rst
@@ -252,6 +252,14 @@ how to contact the ADS server, which will be used whenever a :ref:`ConfigSource
 management server) contains an :ref:`AggregatedConfigSource
 <envoy_v3_api_msg_config.core.v3.AggregatedConfigSource>` message.
 
+A current limitation in Envoy is that any xDS :ref:`Cluster <envoy_v3_api_msg_config.cluster.v3.Cluster>` resources
+should be specified first in the `static_resources` field of the Bootstrap configuration prior to any static
+:ref:`Cluster <envoy_v3_api_msg_config.cluster.v3.Cluster>` resources that depend on the xDS cluster. Failure to do
+so will result in slower Envoy initialization (see the `GitHub issue <https://github.com/envoyproxy/envoy/issues/27702>`_
+for details). As an example, if a cluster depends on an xDS :ref:`Cluster <envoy_v3_api_msg_config.cluster.v3.Cluster>`
+for SDS to configure the secrets on a transport socket, the xDS :ref:`Cluster <envoy_v3_api_msg_config.cluster.v3.Cluster>`
+should be specified first in the `static_resources` field, before the cluster with the transport socket secret is specified.
+
 In a gRPC client that uses xDS, only ADS is supported, and the bootstrap file contains the name of
 the ADS server, which will be used for all resources. The :ref:`ConfigSource
 <envoy_v3_api_msg_config.core.v3.ConfigSource>` messages in the :ref:`Listener <envoy_v3_api_msg_config.listener.v3.Listener>` and