|
|
|
syntax = "proto3";
|
|
|
|
|
|
|
|
package envoy.api.v2;
|
|
|
|
|
|
|
|
option java_outer_classname = "DiscoveryProto";
|
|
|
|
option java_multiple_files = true;
|
|
|
|
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;
|
|
|
|
option (gogoproto.stable_marshaler_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;
|
|
|
|
|
|
|
|
// [#not-implemented-hide:]
|
|
|
|
// The control plane instance that sent the response.
|
|
|
|
core.ControlPlane control_plane = 6;
|
|
|
|
}
|
|
|
|
|
|
|
|
// DeltaDiscoveryRequest and DeltaDiscoveryResponse are used in a new gRPC
|
|
|
|
// endpoint for Delta xDS.
|
|
|
|
//
|
|
|
|
// With Delta xDS, the DeltaDiscoveryResponses do not need to include a full
|
|
|
|
// snapshot of the tracked resources. Instead, DeltaDiscoveryResponses are a
|
|
|
|
// diff to the state of a xDS client.
|
|
|
|
// In Delta XDS there are per resource versions, which allow tracking state at
|
|
|
|
// the resource granularity.
|
|
|
|
// An xDS Delta 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 Delta xDS the nonce field is required and used to pair
|
|
|
|
// DeltaDiscoveryResponse to a DeltaDiscoveryRequest ACK or NACK.
|
|
|
|
// Optionally, a response message level system_version_info is present for
|
|
|
|
// debugging purposes only.
|
|
|
|
//
|
|
|
|
// DeltaDiscoveryRequest 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 DeltaDiscoveryResponse.
|
|
|
|
// 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 DeltaDiscoveryRequest 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 DeltaDiscoveryRequest {
|
|
|
|
// 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;
|
|
|
|
|
|
|
|
// DeltaDiscoveryRequests 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 state-of-the-world 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 state-of-the-world xDS.
|
|
|
|
// These two fields can be set for all types of DeltaDiscoveryRequests
|
|
|
|
// (initial, ACK/NACK or spontaneous).
|
|
|
|
//
|
|
|
|
// NOTE: the server must respond with all resources listed in resource_names_subscribe,
|
|
|
|
// even if it believes the client has the most recent version of them. The reason:
|
|
|
|
// the client may have dropped them, but then regained interest before it had a chance
|
|
|
|
// to send the unsubscribe message. See DeltaSubscriptionStateTest.RemoveThenAdd.
|
|
|
|
//
|
|
|
|
// 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 DeltaDiscoveryRequest is the
|
|
|
|
// first in a stream (assuming there are any resources - this field's purpose is to enable
|
|
|
|
// a session to continue in a reconnected gRPC stream, and so will not be used in the very
|
|
|
|
// first stream of a session). 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 DeltaDiscoveryRequest is a ACK or NACK message in response
|
|
|
|
// to a previous DeltaDiscoveryResponse, the response_nonce must be the
|
|
|
|
// nonce in the DeltaDiscoveryResponse.
|
|
|
|
// 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 DeltaDiscoveryResponse {
|
|
|
|
// 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 DeltaDiscoveryRequest.
|
|
|
|
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 DeltaDiscoveryRequests to uniquely
|
|
|
|
// reference a DeltaDiscoveryResponse. The nonce is required.
|
|
|
|
string nonce = 5;
|
|
|
|
}
|
|
|
|
|
|
|
|
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;
|
|
|
|
|
|
|
|
// The resource being tracked.
|
|
|
|
google.protobuf.Any resource = 2;
|
|
|
|
}
|