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