...

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

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

     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