1syntax = "proto3";
2
3package envoy.service.discovery.v3;
4
5import "envoy/config/core/v3/base.proto";
6
7import "google/protobuf/any.proto";
8import "google/protobuf/duration.proto";
9import "google/rpc/status.proto";
10
11import "udpa/annotations/migrate.proto";
12import "udpa/annotations/status.proto";
13import "udpa/annotations/versioning.proto";
14
15option java_package = "io.envoyproxy.envoy.service.discovery.v3";
16option java_outer_classname = "DiscoveryProto";
17option java_multiple_files = true;
18option (udpa.annotations.file_status).package_version_status = ACTIVE;
19
20// [#protodoc-title: Common discovery API components]
21
22// A DiscoveryRequest requests a set of versioned resources of the same type for
23// a given Envoy node on some API.
24// [#next-free-field: 7]
25message DiscoveryRequest {
26 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.DiscoveryRequest";
27
28 // The version_info provided in the request messages will be the version_info
29 // received with the most recent successfully processed response or empty on
30 // the first request. It is expected that no new request is sent after a
31 // response is received until the Envoy instance is ready to ACK/NACK the new
32 // configuration. ACK/NACK takes place by returning the new API config version
33 // as applied or the previous API config version respectively. Each type_url
34 // (see below) has an independent version associated with it.
35 string version_info = 1;
36
37 // The node making the request.
38 config.core.v3.Node node = 2;
39
40 // List of resources to subscribe to, e.g. list of cluster names or a route
41 // configuration name. If this is empty, all resources for the API are
42 // returned. LDS/CDS may have empty resource_names, which will cause all
43 // resources for the Envoy instance to be returned. The LDS and CDS responses
44 // will then imply a number of resources that need to be fetched via EDS/RDS,
45 // which will be explicitly enumerated in resource_names.
46 repeated string resource_names = 3;
47
48 // Type of the resource that is being requested, e.g.
49 // "type.googleapis.com/envoy.api.v2.ClusterLoadAssignment". This is implicit
50 // in requests made via singleton xDS APIs such as CDS, LDS, etc. but is
51 // required for ADS.
52 string type_url = 4;
53
54 // nonce corresponding to DiscoveryResponse being ACK/NACKed. See above
55 // discussion on version_info and the DiscoveryResponse nonce comment. This
56 // may be empty only if 1) this is a non-persistent-stream xDS such as HTTP,
57 // or 2) the client has not yet accepted an update in this xDS stream (unlike
58 // delta, where it is populated only for new explicit ACKs).
59 string response_nonce = 5;
60
61 // This is populated when the previous :ref:`DiscoveryResponse <envoy_api_msg_service.discovery.v3.DiscoveryResponse>`
62 // failed to update configuration. The *message* field in *error_details* provides the Envoy
63 // internal exception related to the failure. It is only intended for consumption during manual
64 // debugging, the string provided is not guaranteed to be stable across Envoy versions.
65 google.rpc.Status error_detail = 6;
66}
67
68// [#next-free-field: 7]
69message DiscoveryResponse {
70 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.DiscoveryResponse";
71
72 // The version of the response data.
73 string version_info = 1;
74
75 // The response resources. These resources are typed and depend on the API being called.
76 repeated google.protobuf.Any resources = 2;
77
78 // [#not-implemented-hide:]
79 // Canary is used to support two Envoy command line flags:
80 //
81 // * --terminate-on-canary-transition-failure. When set, Envoy is able to
82 // terminate if it detects that configuration is stuck at canary. Consider
83 // this example sequence of updates:
84 // - Management server applies a canary config successfully.
85 // - Management server rolls back to a production config.
86 // - Envoy rejects the new production config.
87 // Since there is no sensible way to continue receiving configuration
88 // updates, Envoy will then terminate and apply production config from a
89 // clean slate.
90 // * --dry-run-canary. When set, a canary response will never be applied, only
91 // validated via a dry run.
92 bool canary = 3;
93
94 // Type URL for resources. Identifies the xDS API when muxing over ADS.
95 // Must be consistent with the type_url in the 'resources' repeated Any (if non-empty).
96 string type_url = 4;
97
98 // For gRPC based subscriptions, the nonce provides a way to explicitly ack a
99 // specific DiscoveryResponse in a following DiscoveryRequest. Additional
100 // messages may have been sent by Envoy to the management server for the
101 // previous version on the stream prior to this DiscoveryResponse, that were
102 // unprocessed at response send time. The nonce allows the management server
103 // to ignore any further DiscoveryRequests for the previous version until a
104 // DiscoveryRequest bearing the nonce. The nonce is optional and is not
105 // required for non-stream based xDS implementations.
106 string nonce = 5;
107
108 // [#not-implemented-hide:]
109 // The control plane instance that sent the response.
110 config.core.v3.ControlPlane control_plane = 6;
111}
112
113// DeltaDiscoveryRequest and DeltaDiscoveryResponse are used in a new gRPC
114// endpoint for Delta xDS.
115//
116// With Delta xDS, the DeltaDiscoveryResponses do not need to include a full
117// snapshot of the tracked resources. Instead, DeltaDiscoveryResponses are a
118// diff to the state of a xDS client.
119// In Delta XDS there are per-resource versions, which allow tracking state at
120// the resource granularity.
121// An xDS Delta session is always in the context of a gRPC bidirectional
122// stream. This allows the xDS server to keep track of the state of xDS clients
123// connected to it.
124//
125// In Delta xDS the nonce field is required and used to pair
126// DeltaDiscoveryResponse to a DeltaDiscoveryRequest ACK or NACK.
127// Optionally, a response message level system_version_info is present for
128// debugging purposes only.
129//
130// DeltaDiscoveryRequest plays two independent roles. Any DeltaDiscoveryRequest
131// can be either or both of: [1] informing the server of what resources the
132// client has gained/lost interest in (using resource_names_subscribe and
133// resource_names_unsubscribe), or [2] (N)ACKing an earlier resource update from
134// the server (using response_nonce, with presence of error_detail making it a NACK).
135// Additionally, the first message (for a given type_url) of a reconnected gRPC stream
136// has a third role: informing the server of the resources (and their versions)
137// that the client already possesses, using the initial_resource_versions field.
138//
139// As with state-of-the-world, when multiple resource types are multiplexed (ADS),
140// all requests/acknowledgments/updates are logically walled off by type_url:
141// a Cluster ACK exists in a completely separate world from a prior Route NACK.
142// In particular, initial_resource_versions being sent at the "start" of every
143// gRPC stream actually entails a message for each type_url, each with its own
144// initial_resource_versions.
145// [#next-free-field: 8]
146message DeltaDiscoveryRequest {
147 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.DeltaDiscoveryRequest";
148
149 // The node making the request.
150 config.core.v3.Node node = 1;
151
152 // Type of the resource that is being requested, e.g.
153 // "type.googleapis.com/envoy.api.v2.ClusterLoadAssignment". This does not need to be set if
154 // resources are only referenced via *xds_resource_subscribe* and
155 // *xds_resources_unsubscribe*.
156 string type_url = 2;
157
158 // DeltaDiscoveryRequests allow the client to add or remove individual
159 // resources to the set of tracked resources in the context of a stream.
160 // All resource names in the resource_names_subscribe list are added to the
161 // set of tracked resources and all resource names in the resource_names_unsubscribe
162 // list are removed from the set of tracked resources.
163 //
164 // *Unlike* state-of-the-world xDS, an empty resource_names_subscribe or
165 // resource_names_unsubscribe list simply means that no resources are to be
166 // added or removed to the resource list.
167 // *Like* state-of-the-world xDS, the server must send updates for all tracked
168 // resources, but can also send updates for resources the client has not subscribed to.
169 //
170 // NOTE: the server must respond with all resources listed in resource_names_subscribe,
171 // even if it believes the client has the most recent version of them. The reason:
172 // the client may have dropped them, but then regained interest before it had a chance
173 // to send the unsubscribe message. See DeltaSubscriptionStateTest.RemoveThenAdd.
174 //
175 // These two fields can be set in any DeltaDiscoveryRequest, including ACKs
176 // and initial_resource_versions.
177 //
178 // A list of Resource names to add to the list of tracked resources.
179 repeated string resource_names_subscribe = 3;
180
181 // A list of Resource names to remove from the list of tracked resources.
182 repeated string resource_names_unsubscribe = 4;
183
184 // Informs the server of the versions of the resources the xDS client knows of, to enable the
185 // client to continue the same logical xDS session even in the face of gRPC stream reconnection.
186 // It will not be populated: [1] in the very first stream of a session, since the client will
187 // not yet have any resources, [2] in any message after the first in a stream (for a given
188 // type_url), since the server will already be correctly tracking the client's state.
189 // (In ADS, the first message *of each type_url* of a reconnected stream populates this map.)
190 // The map's keys are names of xDS resources known to the xDS client.
191 // The map's values are opaque resource versions.
192 map<string, string> initial_resource_versions = 5;
193
194 // When the DeltaDiscoveryRequest is a ACK or NACK message in response
195 // to a previous DeltaDiscoveryResponse, the response_nonce must be the
196 // nonce in the DeltaDiscoveryResponse.
197 // Otherwise (unlike in DiscoveryRequest) response_nonce must be omitted.
198 string response_nonce = 6;
199
200 // This is populated when the previous :ref:`DiscoveryResponse <envoy_api_msg_service.discovery.v3.DiscoveryResponse>`
201 // failed to update configuration. The *message* field in *error_details*
202 // provides the Envoy internal exception related to the failure.
203 google.rpc.Status error_detail = 7;
204}
205
206// [#next-free-field: 7]
207message DeltaDiscoveryResponse {
208 option (udpa.annotations.versioning).previous_message_type =
209 "envoy.api.v2.DeltaDiscoveryResponse";
210
211 // The version of the response data (used for debugging).
212 string system_version_info = 1;
213
214 // The response resources. These are typed resources, whose types must match
215 // the type_url field.
216 repeated Resource resources = 2;
217
218 // field id 3 IS available!
219
220 // Type URL for resources. Identifies the xDS API when muxing over ADS.
221 // Must be consistent with the type_url in the Any within 'resources' if 'resources' is non-empty.
222 string type_url = 4;
223
224 // Resources names of resources that have be deleted and to be removed from the xDS Client.
225 // Removed resources for missing resources can be ignored.
226 repeated string removed_resources = 6;
227
228 // The nonce provides a way for DeltaDiscoveryRequests to uniquely
229 // reference a DeltaDiscoveryResponse when (N)ACKing. The nonce is required.
230 string nonce = 5;
231}
232
233// [#next-free-field: 8]
234message Resource {
235 option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.Resource";
236
237 // Cache control properties for the resource.
238 // [#not-implemented-hide:]
239 message CacheControl {
240 // If true, xDS proxies may not cache this resource.
241 // Note that this does not apply to clients other than xDS proxies, which must cache resources
242 // for their own use, regardless of the value of this field.
243 bool do_not_cache = 1;
244 }
245
246 // The resource's name, to distinguish it from others of the same type of resource.
247 string name = 3;
248
249 // The aliases are a list of other names that this resource can go by.
250 repeated string aliases = 4;
251
252 // The resource level version. It allows xDS to track the state of individual
253 // resources.
254 string version = 1;
255
256 // The resource being tracked.
257 google.protobuf.Any resource = 2;
258
259 // Time-to-live value for the resource. For each resource, a timer is started. The timer is
260 // reset each time the resource is received with a new TTL. If the resource is received with
261 // no TTL set, the timer is removed for the resource. Upon expiration of the timer, the
262 // configuration for the resource will be removed.
263 //
264 // The TTL can be refreshed or changed by sending a response that doesn't change the resource
265 // version. In this case the resource field does not need to be populated, which allows for
266 // light-weight "heartbeat" updates to keep a resource with a TTL alive.
267 //
268 // The TTL feature is meant to support configurations that should be removed in the event of
269 // a management server failure. For example, the feature may be used for fault injection
270 // testing where the fault injection should be terminated in the event that Envoy loses contact
271 // with the management server.
272 google.protobuf.Duration ttl = 6;
273
274 // Cache control properties for the resource.
275 // [#not-implemented-hide:]
276 CacheControl cache_control = 7;
277}
View as plain text