data-plane-api/envoy/api/v2/discovery.proto

syntax = "proto3";

package envoy.api.v2;
option java_package = "io.envoyproxy.envoy.api.v2";
option go_package = "v2";

import "envoy/api/v2/core/base.proto";

import "google/protobuf/any.proto";
import "google/rpc/status.proto";
import "gogoproto/gogo.proto";

option (gogoproto.equal_all) = true;

// [#protodoc-title: Common discovery API components]

// A DiscoveryRequest requests a set of versioned resources of the same type for
// a given Envoy node on some API.
message DiscoveryRequest {
  // 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.
  string version_info = 1;

  // The node making the request.
  core.Node node = 2;

  // 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.
  repeated string resource_names = 3;

  // 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.
  string type_url = 4;

  // 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.
  string response_nonce = 5;

  // This is populated when the previous :ref:`DiscoveryResponse <envoy_api_msg_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.
  google.rpc.Status error_detail = 6;
}

message DiscoveryResponse {
  // The version of the response data.
  string version_info = 1;

  // The response resources. These resources are typed and depend on the API being called.
  repeated google.protobuf.Any resources = 2 [(gogoproto.nullable) = false];

  // [#not-implemented-hide:]
  // Canary is used to support two Envoy command line flags:
  //
  // * --terminate-on-canary-transition-failure. When set, Envoy is able to
  //   terminate if it detects that configuration is stuck at canary. Consider
  //   this example sequence of updates:
  //   - Management server applies a canary config successfully.
  //   - Management server rolls back to a production config.
  //   - Envoy rejects the new production config.
  //   Since there is no sensible way to continue receiving configuration
  //   updates, Envoy will then terminate and apply production config from a
  //   clean slate.
  // * --dry-run-canary. When set, a canary response will never be applied, only
  //   validated via a dry run.
  bool canary = 3;

  // 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.
  string type_url = 4;

  // 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.
  string nonce = 5;
}

// 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.
// Optionally, 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.
message IncrementalDiscoveryRequest {
  // The node making the request.
  core.Node node = 1;

  // 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.
  string type_url = 2;

  // 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.
  repeated string resource_names_subscribe = 3;

  // A list of Resource names to remove from the list of tracked resources.
  repeated string resource_names_unsubscribe = 4;

  // 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.
  map<string, string> initial_resource_versions = 5;

  // 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.
  string response_nonce = 6;

  // This is populated when the previous :ref:`DiscoveryResponse <envoy_api_msg_DiscoveryResponse>`
  // failed to update configuration. The *message* field in *error_details*
  // provides the Envoy internal exception related to the failure.
  google.rpc.Status error_detail = 7;
}

message IncrementalDiscoveryResponse {
  // The version of the response data (used for debugging).
  string system_version_info = 1;

  // The response resources. These are typed resources that match the type url
  // in the IncrementalDiscoveryRequest.
  repeated Resource resources = 2 [(gogoproto.nullable) = false];

  // Resources names of resources that have be deleted and to be removed from the xDS Client.
  // Removed resources for missing resources can be ignored.
  repeated string removed_resources = 6;

  // The nonce provides a way for IncrementalDiscoveryRequests to uniquely
  // reference a IncrementalDiscoveryResponse. The nonce is required.
  string nonce = 5;
}

message Resource {
  // The resource level version. It allows xDS to track the state of individual
  // resources.
  string version = 1;

  // The resource being tracked.
  google.protobuf.Any resource = 2;
}