envoyproxy · mattklein123 · May 22, 2019 · May 19, 2019 · May 21, 2019 · May 21, 2019
diff --git a/api/envoy/api/v2/rds.proto b/api/envoy/api/v2/rds.proto
@@ -53,8 +53,7 @@ service RouteDiscoveryService {
 // be the contents of a *host* or *authority* header used to make an http request. An xDS server
 // will match an alias to a virtual host based on the content of :ref:`domains'
 // <envoy_api_msg_route.VirtualHost.domains>` field. The *resource_names_unsubscribe* field contains
-// a list of virtual host names that have been `unsubscribed
-// <https://github.com/envoyproxy/envoy/blob/master/api/XDS_PROTOCOL.md#unsubscribing-from-resources>`_
+// a list of virtual host names that have been :ref:`unsubscribed <xds_protocol_unsubscribe>`
 // from the routing table associated with the RouteConfiguration.
 service VirtualHostDiscoveryService {
   rpc DeltaVirtualHosts(stream DeltaDiscoveryRequest) returns (stream DeltaDiscoveryResponse) {
@@ -134,4 +133,4 @@ message Vhds {
   // Configuration source specifier for VHDS.
   envoy.api.v2.core.ConfigSource config_source = 1
       [(validate.rules).message.required = true, (gogoproto.nullable) = false];
-}
+}
diff --git a/api/xds_protocol.rst b/api/xds_protocol.rst
@@ -1,3 +1,5 @@
+.. _xds_protocol:
+
 xDS REST and gRPC protocol
 ==========================
 
@@ -29,6 +31,8 @@ updates beyond stats counters and logs. The last valid configuration for
 an xDS API will continue to apply if an configuration update rejection
 occurs.
 
+.. _xds_protocol_streaming_grpc_subscriptions:
+
 Streaming gRPC subscriptions
 ----------------------------
 
@@ -41,8 +45,8 @@ can be specified independently for each xDS API, pointing at an upstream
 cluster corresponding to a management server. This will initiate an
 independent bidirectional gRPC stream for each xDS resource type,
 potentially to distinct management servers. API delivery is eventually
-consistent. See :ref:`Aggregated Discovery Service` below for
-situations in which explicit control of sequencing is required.
+consistent. See <Aggregated Discovery Service>`
+below for situations in which explicit control of sequencing is required.
 
 Type URLs
 ^^^^^^^^^
@@ -130,7 +134,10 @@ versioning across resource types. When ADS is not used, even each
 resource of a given resource type may have a distinct version, since the
 Envoy API allows distinct EDS/RDS resources to point at different :ref:`ConfigSources <envoy_api_msg_core.ConfigSource>`.
 
-.. _Resource Updates:
+.. xds_protocol_resource_update:
+
+Resource Update
+~~~~~~~~~~~~~~~
 
 When to send an update
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -172,7 +179,7 @@ resources. :ref:`resource_names <envoy_api_field_DiscoveryRequest.resource_names
 any superfluous resources. When a requested resource is missing in a RDS
 or EDS update, Envoy will retain the last known value for this resource
 except in the case where the `Cluster` or `Listener` is being
-warmed. See :ref:`Resource warming` section below on
+warmed. See <Resource Warming> section below on
 the expectations during warming. The management server may be able to
 infer all the required EDS/RDS resources from the :ref:`node <envoy_api_msg_Core.Node>`
 identification in the :ref:`DiscoveryRequest <envoy_api_msg_DiscoveryRequest>`, in which case this hint may
@@ -241,7 +248,7 @@ An implication of the above resource update sequencing is that Envoy
 does not expect a :ref:`DiscoveryResponse <envoy_api_msg_DiscoveryResponse>` for every :ref:`DiscoveryRequests <envoy_api_msg_DiscoveryRequest>`
 it issues.
 
-.. _Resource Warming:
+.. _xds_protocol_resource_warming:
 
 Resource warming
 ~~~~~~~~~~~~~~~~
@@ -260,6 +267,8 @@ server does not provide EDS/RDS responses, Envoy will not initialize
 itself during the initialization phase and the updates sent via CDS/LDS
 will not take effect until EDS/RDS responses are supplied.
 
+.. _xds_protocol_eventual_consistency_considerations:
+
 Eventual consistency considerations
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -296,10 +305,10 @@ adding/removing/updating clusters. On the other hand, routes are not
 warmed, i.e., the management plane must ensure that clusters referenced
 by a route are in place, before pushing the updates for a route.
 
-.. _Aggregated Discovery Service:
+.. _xds_protocol_ads:
 
-Aggregated Discovery Service (ADS)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Aggregated Discovery Service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It's challenging to provide the above guarantees on sequencing to avoid
 traffic drop when management servers are distributed. ADS allow a single
@@ -421,6 +430,8 @@ those resources in the response; due to implementation details hidden
 from the server, the client may have "forgotten" those resources despite
 apparently remaining subscribed.
 
+.. _xds_protocol_unsubscribe:
+
 Unsubscribing from Resources
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -449,8 +460,8 @@ messages. ADS is not available for REST-JSON polling.
 
 When the poll period is set to a small value, with the intention of long
 polling, then there is also a requirement to avoid sending a
-:ref:`DiscoveryResponse <envoy_api_msg_DiscoveryResponse>` :ref:`unless a change to the underlying resources has
-occurred <Resource Updates>`.
+:ref:`DiscoveryResponse <envoy_api_msg_DiscoveryResponse>` unless a change to the underlying resources has
+occurred <Resource Update>.
 
 .. |Multiple EDS requests on the same stream| image:: diagrams/eds-same-stream.svg
-.. |Multiple EDS requests on distinct streams| image:: diagrams/eds-distinct-stream.svg
+.. |Multiple EDS requests on distinct streams| image:: diagrams/eds-distinct-stream.svg
diff --git a/docs/root/configuration/overview/v2_overview.rst b/docs/root/configuration/overview/v2_overview.rst
@@ -8,19 +8,19 @@ The Envoy v2 APIs are defined as `proto3
 <https://developers.google.com/protocol-buffers/>`_ in the `data plane API
 repository <https://github.com/envoyproxy/data-plane-api/tree/master/envoy/api>`_. They support
 
-* Streaming delivery of :repo:`xDS <api/XDS_PROTOCOL.md>` API updates via gRPC. This reduces
+* Streaming delivery of :ref:`xDS <xds_protocol>` API updates via gRPC. This reduces
   resource requirements and can lower the update latency.
 * A new REST-JSON API in which the JSON/YAML formats are derived mechanically via the `proto3
   canonical JSON mapping
   <https://developers.google.com/protocol-buffers/docs/proto3#json>`_.
 * Delivery of updates via the filesystem, REST-JSON or gRPC endpoints.
 * Advanced load balancing through an extended endpoint assignment API and load
   and resource utilization reporting to management servers.
-* :repo:`Stronger consistency and ordering properties
-  <api/XDS_PROTOCOL.md#eventual-consistency-considerations>`
+* :ref:`Stronger consistency and ordering properties
+  <xds_protocol_eventual_consistency_considerations>`
   when needed. The v2 APIs still maintain a baseline eventual consistency model.
 
-See the :repo:`xDS protocol description <api/XDS_PROTOCOL.md>` for
+See the :ref:`xDS protocol description <xds_protocol>` for
 further details on aspects of v2 message exchange between Envoy and the management server.
 
 .. _config_overview_v2_bootstrap:
@@ -199,8 +199,8 @@ In the above example, the EDS management server could then return a proto encodi
 
 
 The versioning and type URL scheme that appear above are explained in more
-detail in the :repo:`streaming gRPC subscription protocol
-<api/XDS_PROTOCOL.md#streaming-grpc-subscriptions>`
+detail in the :ref:`streaming gRPC subscription protocol
+<xds_protocol_streaming_grpc_subscriptions>`
 documentation.
 
 Dynamic
@@ -341,7 +341,7 @@ A v2 xDS management server will implement the below endpoints as required for
 gRPC and/or REST serving. In both streaming gRPC and
 REST-JSON cases, a :ref:`DiscoveryRequest <envoy_api_msg_DiscoveryRequest>` is sent and a
 :ref:`DiscoveryResponse <envoy_api_msg_DiscoveryResponse>` received following the
-:repo:`xDS protocol <api/XDS_PROTOCOL.md>`.
+:ref:`xDS protocol <xds_protocol>`.
 
 .. _v2_grpc_streaming_endpoints:
 
@@ -524,8 +524,7 @@ synchronization to correctly sequence the update. With ADS, the management
 server would deliver the CDS, EDS and then RDS updates on a single stream.
 
 ADS is only available for gRPC streaming (not REST) and is described more fully
-in :repo:`this
-<api/XDS_PROTOCOL.md#aggregated-discovery-services-ads>`
+in :ref:`xDS <xds_protocol_ads>`
 document. The gRPC endpoint is:
 
 .. http:post:: /envoy.service.discovery.v2.AggregatedDiscoveryService/StreamAggregatedResources

diff --git a/docs/root/configuration/secret.rst b/docs/root/configuration/secret.rst
@@ -21,7 +21,7 @@ SDS server
 ----------
 
 A SDS server needs to implement the gRPC service :repo:`SecretDiscoveryService <api/envoy/service/discovery/v2/sds.proto>`.
-It follows the same protocol as other :repo:`xDS <api/XDS_PROTOCOL.md>`.
+It follows the same protocol as other :ref:`xDS <xds_protocol>`.
 
 SDS Configuration
 -----------------

diff --git a/source/common/config/config_provider_impl.h b/source/common/config/config_provider_impl.h
@@ -35,7 +35,7 @@ namespace Config {
 // and/or stream/request (if required by the configuration being processed).
 //
 // Dynamic configuration is distributed via xDS APIs (see
-// https://github.com/envoyproxy/data-plane-api/blob/master/XDS_PROTOCOL.md). The framework exposed
+// https://github.com/envoyproxy/data-plane-api/blob/master/xds_protocol.rst). The framework exposed
 // by these classes simplifies creation of client xDS implementations following a shared ownership
 // model, where according to the config source specification, a config subscription, config protos
 // received over the subscription and the subsequent config "implementation" (i.e., data structures