Common discovery API components¶

DiscoveryRequest¶

A DiscoveryRequest requests a set of versioned resources of the same type for a given Envoy node on some API.

{
  "version_info": "...",
  "node": "{...}",
  "resource_names": [],
  "type_url": "...",
  "response_nonce": "..."
}

version_info: (string) The version_info provided in the request messages will be the version_info received with the most recent successfully processed response or empty on the first request. It is expected that no new request is sent after a response is received until the Envoy instance is ready to ACK/NACK the new configuration. ACK/NACK takes place by returning the new API config version as applied or the previous API config version respectively. Each type_url (see below) has an independent version associated with it.

resource_names: (string) List of resources to subscribe to, e.g. list of cluster names or a route configuration name. If this is empty, all resources for the API are returned. LDS/CDS expect empty resource_names, since this is global discovery for the Envoy instance. The LDS and CDS responses will then imply a number of resources that need to be fetched via EDS/RDS, which will be explicitly enumerated in resource_names.

type_url: (string) Type of the resource that is being requested, e.g. “type.googleapis.com/envoy.api.v2.ClusterLoadAssignment”. This is implicit in requests made via singleton xDS APIs such as CDS, LDS, etc. but is required for ADS.

response_nonce: (string) nonce corresponding to DiscoveryResponse being ACK/NACKed. See above discussion on version_info and the DiscoveryResponse nonce comment. This may be empty if no nonce is available, e.g. at startup or for non-stream xDS implementations.

{
  "version_info": "...",
  "resources": [],
  "type_url": "...",
  "nonce": "..."
}

resources: (Any) The response resources. These resources are typed and depend on the API being called.

type_url: (string) Type URL for resources. This must be consistent with the type_url in the Any messages for resources if resources is non-empty. This effectively identifies the xDS API when muxing over ADS.

nonce: (string) For gRPC based subscriptions, the nonce provides a way to explicitly ack a specific DiscoveryResponse in a following DiscoveryRequest. Additional messages may have been sent by Envoy to the management server for the previous version on the stream prior to this DiscoveryResponse, that were unprocessed at response send time. The nonce allows the management server to ignore any further DiscoveryRequests for the previous version until a DiscoveryRequest bearing the nonce. The nonce is optional and is not required for non-stream based xDS implementations.