API: Add alias to resource message (#6283)

Added an optional alias field to the resource message for use in the implementation of on-demand xDS.

Risk Level: Low
Testing: Validated Yaml

Fixes #6128

Signed-off-by: Brian Avery <bavery@redhat.com>

Mirrored from https://github.com/envoyproxy/envoy @ 4d18f6e893b59a323ed0119016f1c1cbdb4fbcf9

XDS_PROTOCOL.md

@@ -151,7 +151,7 @@ For EDS/RDS, the management server does not need to supply every requested
 resource and may also supply additional, unrequested resources. `resource_names`
 is only a hint. Envoy will silently ignore 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` 
+known value for this resource except in the case where the `Cluster` or `Listener`
 is being warmed. See [Resource warming](#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 `node` identification in the
@@ -213,13 +213,13 @@ expect a `DiscoveryResponse` for every `DiscoveryRequest` it issues.
 
 ### Resource warming
 
-[`Clusters`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/cluster_manager.html#cluster-warming) 
+[`Clusters`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/cluster_manager.html#cluster-warming)
 and [`Listeners`](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/lds#config-listeners-lds)
-go through  `warming` before they can serve requests. This process happens both during 
-[`Envoy initialization`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/init.html#initialization) 
-and when the `Cluster` or `Listener` is updated. Warming of `Cluster` is completed only when a 
+go through  `warming` before they can serve requests. This process happens both during
+[`Envoy initialization`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/init.html#initialization)
+and when the `Cluster` or `Listener` is updated. Warming of `Cluster` is completed only when a
 `ClusterLoadAssignment` response is supplied by management server. Similarly, warming of `Listener`
-is completed only when a `RouteConfiguration` is supplied by management server if the listener 
+is completed only when a `RouteConfiguration` is supplied by management server if the listener
 refers to an RDS configuration. Management server is expected to provide the EDS/RDS updates during
 warming. If management 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
@@ -350,6 +350,24 @@ resources to avoid resending them over the network.
 
 ![Incremental reconnect example](diagrams/incremental-reconnect.svg)
 
+#### Resource names
+Resources are identified by a resource name or an alias. Aliases of a resource, if present, can be
+identified by the alias field in the resource of a `DeltaDiscoveryResponse`. The resource name will
+be returned in the name field in the resource of a `DeltaDiscoveryResponse`.
+
+#### Subscribing to Resources
+Envoy can send either an alias or the name of a resource in the `resource_names_subscribe` field of
+a `DeltaDiscoveryRequest` in order to subscribe to a resource. Envoy should check both the names and
+aliases of resources in order to determine whether the entity in question has been subscribed to.
+
+#### Unsubscribing from Resources
+Envoy will keep track of a per resource reference count internally. This count will keep track of the
+total number of aliases/resource names that are currently subscribed to. When the reference count
+reaches zero, Envoy will send a `DeltaDiscoveryRequest` containing the resource name of the resource
+to unsubscribe from in the `resource_names_unsubscribe` field. When Envoy unsubscribes from a resource,
+it should check for both the resource name and all aliases and appropriately update all resources
+that reference either.
+
 ## REST-JSON polling subscriptions
 
 Synchronous (long) polling via REST endpoints is also available for the xDS

envoy/api/v2/discovery.proto

@@ -199,6 +199,10 @@ message Resource {
   // The resource's name, to distinguish it from others of the same type of resource.
   string name = 3;
 
+  // [#not-implemented-hide:]
+  // The aliases are a list of other names that this resource can go by.
+  repeated string aliases = 4;
+
   // The resource level version. It allows xDS to track the state of individual
   // resources.
   string version = 1;