...

Text file src/github.com/datawire/ambassador/v2/api/envoy/service/discovery/v3/discovery.proto

Documentation: github.com/datawire/ambassador/v2/api/envoy/service/discovery/v3

     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