Common discovery API components

DiscoveryRequest

[DiscoveryRequest proto]

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": "...",
  "error_detail": "{...}"
}

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.

node

(core.Node) The node making the request.

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.

error_detail

(Status) This is populated when the previous DiscoveryResponse failed to update configuration. The message field in error_details provides the Envoy internal exception related to the failure. It is only intended for consumption during manual debugging, the string provided is not guaranteed to be stable across Envoy versions.

DiscoveryResponse

[DiscoveryResponse proto]

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

version_info

(string) The version of the response data.

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.

IncrementalDiscoveryRequest

[IncrementalDiscoveryRequest proto]

IncrementalDiscoveryRequest and IncrementalDiscoveryResponse are used in a new gRPC endpoint for Incremental xDS. The feature is not supported for REST management servers.

With Incremental xDS, the IncrementalDiscoveryResponses do not need to include a full snapshot of the tracked resources. Instead IncrementalDiscoveryResponses are a diff to the state of a xDS client. In Incremental XDS there are per resource versions which allows to track state at the resource granularity. An xDS Incremental session is always in the context of a gRPC bidirectional stream. This allows the xDS server to keep track of the state of xDS clients connected to it.

In Incremental xDS the nonce field is required and used to pair IncrementalDiscoveryResponse to a IncrementalDiscoveryRequest ACK or NACK. Optionaly, a response message level system_version_info is present for debugging purposes only.

IncrementalDiscoveryRequest can be sent in 3 situations:

1. Initial message in a xDS bidirectional gRPC stream.
2. As a ACK or NACK response to a previous IncrementalDiscoveryResponse. In this case the response_nonce is set to the nonce value in the Response. ACK or NACK is determined by the absence or presence of error_detail.
3. Spontaneous IncrementalDiscoveryRequest from the client. This can be done to dynamically add or remove elements from the tracked resource_names set. In this case response_nonce must be omitted.

{
  "node": "{...}",
  "type_url": "...",
  "resource_names_subscribe": [],
  "resource_names_unsubscribe": [],
  "initial_resource_versions": "{...}",
  "response_nonce": "...",
  "error_detail": "{...}"
}

node

(core.Node) The node making the request.

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.

resource_names_subscribe

(string) IncrementalDiscoveryRequests allow the client to add or remove individual resources to the set of tracked resources in the context of a stream. All resource names in the resource_names_subscribe list are added to the set of tracked resources and all resource names in the resource_names_unsubscribe list are removed from the set of tracked resources. Unlike in non incremental xDS, an empty resource_names_subscribe or resource_names_unsubscribe list simply means that no resources are to be added or removed to the resource list. The xDS server must send updates for all tracked resources but can also send updates for resources the client has not subscribed to. This behavior is similar to non incremental xDS. These two fields can be set for all types of IncrementalDiscoveryRequests (initial, ACK/NACK or spontaneous).

A list of Resource names to add to the list of tracked resources.

resource_names_unsubscribe

(string) A list of Resource names to remove from the list of tracked resources.

initial_resource_versions

(map<string, string>) This map must be populated when the IncrementalDiscoveryRequest is the first in a stream. The keys are the resources names of the xDS resources known to the xDS client. The values in the map are the associated resource level version info.

response_nonce

(string) When the IncrementalDiscoveryRequest is a ACK or NACK message in response to a previous IncrementalDiscoveryResponse, the response_nonce must be the nonce in the IncrementalDiscoveryResponse. Otherwise response_nonce must be omitted.

error_detail

(Status) This is populated when the previous DiscoveryResponse failed to update configuration. The message field in error_details provides the Envoy internal exception related to the failure.

IncrementalDiscoveryResponse

[IncrementalDiscoveryResponse proto]

{
  "system_version_info": "...",
  "resources": [],
  "removed_resources": [],
  "nonce": "..."
}

system_version_info

(string) The version of the response data (used for debugging).

resources

(Resource) The response resources. These are typed resources that match the type url in the IncrementalDiscoveryRequest.

removed_resources

(string) Resources names of resources that have be deleted and to be removed from the xDS Client. Removed resources for missing resources can be ignored.

nonce

(string) The nonce provides a way for IncrementalDiscoveryRequests to uniquely reference a IncrementalDiscoveryResponse. The nonce is required.

Resource

[Resource proto]

{
  "version": "...",
  "resource": "{...}"
}

version

(string) The resource level version. It allows xDS to track the state of individual resources.

resource

(Any) The resource being tracked.