xDS: add docs about backing source restrictions (#371)

envoyproxy/envoy#2256 adds restrictions to the backing sources for xDS resources. This change documents those restrictions.

Signed-off-by: Jose Nino <jnino@lyft.com>

api/base.proto

@@ -175,6 +175,11 @@ message ApiConfigSource {
   ApiType api_type = 1 [(validate.rules).enum.defined_only = true];
   // Multiple cluster names may be provided. If > 1 cluster is defined, clusters
   // will be cycled through if any kind of failure occurs.
+  //
+  // .. note::
+  //
+  //  The cluster with name ``cluster_name`` must be statically defined, or an
+  //  EnvoyException will be thrown.
   repeated string cluster_name = 2 [(validate.rules).repeated .min_items = 1];
   // For REST APIs, the delay between successive polls.
   google.protobuf.Duration refresh_delay = 3 [(gogoproto.stdduration) = true];
@@ -196,6 +201,11 @@ message ConfigSource {
   oneof config_source_specifier {
     option (validate.required) = true;
     // Path on the filesystem to source and watch for configuration updates.
+    //
+    // .. note::
+    //
+    //  The path to the source must exist at config load time, or an
+    //  EnvoyException will be thrown.
     string path = 1;
     // API configuration source.
     ApiConfigSource api_config_source = 2;

docs/root/api-v1/listeners/lds.rst

@@ -13,8 +13,8 @@ Listener discovery service (LDS)
 cluster
   *(required, string)* The name of an upstream :ref:`cluster <config_cluster_manager_cluster>` that
   hosts the listener discovery service. The cluster must run a REST service that implements the
-  :ref:`LDS HTTP API <config_listeners_lds_v1_api>`. NOTE: This is the *name* of a cluster defined
-  in the :ref:`cluster manager <config_cluster_manager>` configuration, not the full definition of
+  :ref:`LDS HTTP API <config_listeners_lds_v1_api>`. NOTE: This is the *name* of a statically defined
+  cluster in the :ref:`cluster manager <config_cluster_manager>` configuration, not the full definition of
   a cluster as in the case of SDS and CDS.
 
 refresh_delay_ms

docs/root/api-v1/route_config/rds.rst

@@ -14,8 +14,8 @@ Route discovery service (RDS)
 cluster
   *(required, string)* The name of an upstream :ref:`cluster <config_cluster_manager_cluster>` that
   hosts the route discovery service. The cluster must run a REST service that implements the
-  :ref:`RDS HTTP API <config_http_conn_man_rds_v1_api>`. NOTE: This is the *name* of a cluster defined
-  in the :ref:`cluster manager <config_cluster_manager>` configuration, not the full definition of
+  :ref:`RDS HTTP API <config_http_conn_man_rds_v1_api>`. NOTE: This is the *name* of a statically defined
+  cluster in the :ref:`cluster manager <config_cluster_manager>` configuration, not the full definition of
   a cluster as in the case of SDS and CDS.
 
 route_config_name