.. _envoy_v3_api_file_envoy/service/discovery/v3/discovery.proto: Common discovery API components (proto) ======================================= .. _envoy_v3_api_msg_service.discovery.v3.ResourceLocator: service.discovery.v3.ResourceLocator ------------------------------------ :repo:`[service.discovery.v3.ResourceLocator proto] ` Specifies a resource to be subscribed to. .. code-block:: json :force: { "name": ..., "dynamic_parameters": {...} } .. _envoy_v3_api_field_service.discovery.v3.ResourceLocator.name: name (`string `_) The resource name to subscribe to. .. _envoy_v3_api_field_service.discovery.v3.ResourceLocator.dynamic_parameters: dynamic_parameters (**repeated** map<`string `_, `string `_>) A set of dynamic parameters used to match against the dynamic parameter constraints on the resource. This allows clients to select between multiple variants of the same resource. .. _envoy_v3_api_msg_service.discovery.v3.ResourceName: service.discovery.v3.ResourceName --------------------------------- :repo:`[service.discovery.v3.ResourceName proto] ` Specifies a concrete resource name. .. code-block:: json :force: { "name": ..., "dynamic_parameter_constraints": {...} } .. _envoy_v3_api_field_service.discovery.v3.ResourceName.name: name (`string `_) The name of the resource. .. _envoy_v3_api_field_service.discovery.v3.ResourceName.dynamic_parameter_constraints: dynamic_parameter_constraints (:ref:`service.discovery.v3.DynamicParameterConstraints `) Dynamic parameter constraints associated with this resource. To be used by client-side caches (including xDS proxies) when matching subscribed resource locators. .. _envoy_v3_api_msg_service.discovery.v3.DiscoveryRequest: service.discovery.v3.DiscoveryRequest ------------------------------------- :repo:`[service.discovery.v3.DiscoveryRequest proto] ` A DiscoveryRequest requests a set of versioned resources of the same type for a given Envoy node on some API. .. code-block:: json :force: { "version_info": ..., "node": {...}, "resource_names": [], "type_url": ..., "response_nonce": ..., "error_detail": {...} } .. _envoy_v3_api_field_service.discovery.v3.DiscoveryRequest.version_info: version_info (`string `_) 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. .. _envoy_v3_api_field_service.discovery.v3.DiscoveryRequest.node: node (:ref:`config.core.v3.Node `) The node making the request. .. _envoy_v3_api_field_service.discovery.v3.DiscoveryRequest.resource_names: resource_names (**repeated** `string `_) 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 may have empty ``resource_names``, which will cause all resources for the Envoy instance to be returned. 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``. .. _envoy_v3_api_field_service.discovery.v3.DiscoveryRequest.type_url: type_url (`string `_) 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. .. _envoy_v3_api_field_service.discovery.v3.DiscoveryRequest.response_nonce: response_nonce (`string `_) nonce corresponding to ``DiscoveryResponse`` being ACK/NACKed. See above discussion on ``version_info`` and the ``DiscoveryResponse`` nonce comment. This may be empty only if: * This is a non-persistent-stream xDS such as HTTP, or * The client has not yet accepted an update in this xDS stream (unlike delta, where it is populated only for new explicit ACKs). .. _envoy_v3_api_field_service.discovery.v3.DiscoveryRequest.error_detail: error_detail (`Status `_) This is populated when the previous :ref:`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. .. _envoy_v3_api_msg_service.discovery.v3.DiscoveryResponse: service.discovery.v3.DiscoveryResponse -------------------------------------- :repo:`[service.discovery.v3.DiscoveryResponse proto] ` .. code-block:: json :force: { "version_info": ..., "resources": [], "type_url": ..., "nonce": ..., "control_plane": {...} } .. _envoy_v3_api_field_service.discovery.v3.DiscoveryResponse.version_info: version_info (`string `_) The version of the response data. .. _envoy_v3_api_field_service.discovery.v3.DiscoveryResponse.resources: resources (**repeated** `Any `_) The response resources. These resources are typed and depend on the API being called. .. _envoy_v3_api_field_service.discovery.v3.DiscoveryResponse.type_url: type_url (`string `_) Type URL for resources. Identifies the xDS API when muxing over ADS. Must be consistent with the ``type_url`` in the 'resources' repeated Any (if non-empty). .. _envoy_v3_api_field_service.discovery.v3.DiscoveryResponse.nonce: nonce (`string `_) 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. .. _envoy_v3_api_field_service.discovery.v3.DiscoveryResponse.control_plane: control_plane (:ref:`config.core.v3.ControlPlane `) The control plane instance that sent the response. .. _envoy_v3_api_msg_service.discovery.v3.DeltaDiscoveryRequest: service.discovery.v3.DeltaDiscoveryRequest ------------------------------------------ :repo:`[service.discovery.v3.DeltaDiscoveryRequest proto] ` 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`` plays two independent roles. Any ``DeltaDiscoveryRequest`` can be either or both of: * Informing the server of what resources the client has gained/lost interest in (using ``resource_names_subscribe`` and ``resource_names_unsubscribe``), or * (N)ACKing an earlier resource update from the server (using ``response_nonce``, with presence of ``error_detail`` making it a NACK). Additionally, the first message (for a given ``type_url``) of a reconnected gRPC stream has a third role: informing the server of the resources (and their versions) that the client already possesses, using the ``initial_resource_versions`` field. As with state-of-the-world, when multiple resource types are multiplexed (ADS), all requests/acknowledgments/updates are logically walled off by ``type_url``: a Cluster ACK exists in a completely separate world from a prior Route NACK. In particular, ``initial_resource_versions`` being sent at the "start" of every gRPC stream actually entails a message for each ``type_url``, each with its own ``initial_resource_versions``. .. code-block:: json :force: { "node": {...}, "type_url": ..., "resource_names_subscribe": [], "resource_names_unsubscribe": [], "initial_resource_versions": {...}, "response_nonce": ..., "error_detail": {...} } .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryRequest.node: node (:ref:`config.core.v3.Node `) The node making the request. .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryRequest.type_url: type_url (`string `_) Type of the resource that is being requested, e.g. ``type.googleapis.com/envoy.api.v2.ClusterLoadAssignment``. This does not need to be set if resources are only referenced via ``xds_resource_subscribe`` and ``xds_resources_unsubscribe``. .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryRequest.resource_names_subscribe: resource_names_subscribe (**repeated** `string `_) 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* 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. *Like* state-of-the-world xDS, the server must send updates for all tracked resources, but can also send updates for resources the client has not subscribed to. .. 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. These two fields can be set in any ``DeltaDiscoveryRequest``, including ACKs and ``initial_resource_versions``. A list of Resource names to add to the list of tracked resources. .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryRequest.resource_names_unsubscribe: resource_names_unsubscribe (**repeated** `string `_) A list of Resource names to remove from the list of tracked resources. .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryRequest.initial_resource_versions: initial_resource_versions (**repeated** map<`string `_, `string `_>) Informs the server of the versions of the resources the xDS client knows of, to enable the client to continue the same logical xDS session even in the face of gRPC stream reconnection. It will not be populated: * In the very first stream of a session, since the client will not yet have any resources. * In any message after the first in a stream (for a given ``type_url``), since the server will already be correctly tracking the client's state. (In ADS, the first message ``of each type_url`` of a reconnected stream populates this map.) The map's keys are names of xDS resources known to the xDS client. The map's values are opaque resource versions. .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryRequest.response_nonce: response_nonce (`string `_) 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 (unlike in ``DiscoveryRequest``) ``response_nonce`` must be omitted. .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryRequest.error_detail: error_detail (`Status `_) This is populated when the previous :ref:`DiscoveryResponse ` failed to update configuration. The ``message`` field in ``error_details`` provides the Envoy internal exception related to the failure. .. _envoy_v3_api_msg_service.discovery.v3.DeltaDiscoveryResponse: service.discovery.v3.DeltaDiscoveryResponse ------------------------------------------- :repo:`[service.discovery.v3.DeltaDiscoveryResponse proto] ` .. code-block:: json :force: { "system_version_info": ..., "resources": [], "type_url": ..., "removed_resources": [], "removed_resource_names": [], "nonce": ... } .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryResponse.system_version_info: system_version_info (`string `_) The version of the response data (used for debugging). .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryResponse.resources: resources (**repeated** :ref:`service.discovery.v3.Resource `) The response resources. These are typed resources, whose types must match the ``type_url`` field. .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryResponse.type_url: type_url (`string `_) Type URL for resources. Identifies the xDS API when muxing over ADS. Must be consistent with the ``type_url`` in the Any within 'resources' if 'resources' is non-empty. .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryResponse.removed_resources: removed_resources (**repeated** `string `_) Resource names of resources that have been deleted and to be removed from the xDS Client. Removed resources for missing resources can be ignored. .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryResponse.removed_resource_names: removed_resource_names (**repeated** :ref:`service.discovery.v3.ResourceName `) Alternative to ``removed_resources`` that allows specifying which variant of a resource is being removed. This variant must be used for any resource for which dynamic parameter constraints were sent to the client. .. _envoy_v3_api_field_service.discovery.v3.DeltaDiscoveryResponse.nonce: nonce (`string `_) The nonce provides a way for ``DeltaDiscoveryRequests`` to uniquely reference a ``DeltaDiscoveryResponse`` when (N)ACKing. The nonce is required. .. _envoy_v3_api_msg_service.discovery.v3.DynamicParameterConstraints: service.discovery.v3.DynamicParameterConstraints ------------------------------------------------ :repo:`[service.discovery.v3.DynamicParameterConstraints proto] ` A set of dynamic parameter constraints associated with a variant of an individual xDS resource. These constraints determine whether the resource matches a subscription based on the set of dynamic parameters in the subscription, as specified in the :ref:`ResourceLocator.dynamic_parameters ` field. This allows xDS implementations (clients, servers, and caching proxies) to determine which variant of a resource is appropriate for a given client. .. code-block:: json :force: { "constraint": {...}, "or_constraints": {...}, "and_constraints": {...}, "not_constraints": {...} } .. _envoy_v3_api_field_service.discovery.v3.DynamicParameterConstraints.constraint: constraint (:ref:`service.discovery.v3.DynamicParameterConstraints.SingleConstraint `) A single constraint to evaluate. Only one of :ref:`constraint `, :ref:`or_constraints `, :ref:`and_constraints `, :ref:`not_constraints ` may be set. .. _envoy_v3_api_field_service.discovery.v3.DynamicParameterConstraints.or_constraints: or_constraints (:ref:`service.discovery.v3.DynamicParameterConstraints.ConstraintList `) A list of constraints that match if any one constraint in the list matches. Only one of :ref:`constraint `, :ref:`or_constraints `, :ref:`and_constraints `, :ref:`not_constraints ` may be set. .. _envoy_v3_api_field_service.discovery.v3.DynamicParameterConstraints.and_constraints: and_constraints (:ref:`service.discovery.v3.DynamicParameterConstraints.ConstraintList `) A list of constraints that must all match. Only one of :ref:`constraint `, :ref:`or_constraints `, :ref:`and_constraints `, :ref:`not_constraints ` may be set. .. _envoy_v3_api_field_service.discovery.v3.DynamicParameterConstraints.not_constraints: not_constraints (:ref:`service.discovery.v3.DynamicParameterConstraints `) The inverse (NOT) of a set of constraints. Only one of :ref:`constraint `, :ref:`or_constraints `, :ref:`and_constraints `, :ref:`not_constraints ` may be set. .. _envoy_v3_api_msg_service.discovery.v3.DynamicParameterConstraints.SingleConstraint: service.discovery.v3.DynamicParameterConstraints.SingleConstraint ----------------------------------------------------------------- :repo:`[service.discovery.v3.DynamicParameterConstraints.SingleConstraint proto] ` A single constraint for a given key. .. code-block:: json :force: { "key": ..., "value": ..., "exists": {...} } .. _envoy_v3_api_field_service.discovery.v3.DynamicParameterConstraints.SingleConstraint.key: key (`string `_) The key to match against. .. _envoy_v3_api_field_service.discovery.v3.DynamicParameterConstraints.SingleConstraint.value: value (`string `_) Matches this exact value. Precisely one of :ref:`value `, :ref:`exists ` must be set. .. _envoy_v3_api_field_service.discovery.v3.DynamicParameterConstraints.SingleConstraint.exists: exists (:ref:`service.discovery.v3.DynamicParameterConstraints.SingleConstraint.Exists `) Key is present (matches any value except for the key being absent). This allows setting a default constraint for clients that do not send a key at all, while there may be other clients that need special configuration based on that key. Precisely one of :ref:`value `, :ref:`exists ` must be set. .. _envoy_v3_api_msg_service.discovery.v3.DynamicParameterConstraints.SingleConstraint.Exists: service.discovery.v3.DynamicParameterConstraints.SingleConstraint.Exists ------------------------------------------------------------------------ :repo:`[service.discovery.v3.DynamicParameterConstraints.SingleConstraint.Exists proto] ` .. _envoy_v3_api_msg_service.discovery.v3.DynamicParameterConstraints.ConstraintList: service.discovery.v3.DynamicParameterConstraints.ConstraintList --------------------------------------------------------------- :repo:`[service.discovery.v3.DynamicParameterConstraints.ConstraintList proto] ` .. code-block:: json :force: { "constraints": [] } .. _envoy_v3_api_field_service.discovery.v3.DynamicParameterConstraints.ConstraintList.constraints: constraints (**repeated** :ref:`service.discovery.v3.DynamicParameterConstraints `) .. _envoy_v3_api_msg_service.discovery.v3.Resource: service.discovery.v3.Resource ----------------------------- :repo:`[service.discovery.v3.Resource proto] ` .. code-block:: json :force: { "name": ..., "resource_name": {...}, "aliases": [], "version": ..., "resource": {...}, "ttl": {...}, "metadata": {...} } .. _envoy_v3_api_field_service.discovery.v3.Resource.name: name (`string `_) The resource's name, to distinguish it from others of the same type of resource. Only one of ``name`` or ``resource_name`` may be set. .. _envoy_v3_api_field_service.discovery.v3.Resource.resource_name: resource_name (:ref:`service.discovery.v3.ResourceName `) Alternative to the ``name`` field, to be used when the server supports multiple variants of the named resource that are differentiated by dynamic parameter constraints. Only one of ``name`` or ``resource_name`` may be set. .. _envoy_v3_api_field_service.discovery.v3.Resource.aliases: aliases (**repeated** `string `_) The aliases are a list of other names that this resource can go by. .. _envoy_v3_api_field_service.discovery.v3.Resource.version: version (`string `_) The resource level version. It allows xDS to track the state of individual resources. .. _envoy_v3_api_field_service.discovery.v3.Resource.resource: resource (`Any `_) The resource being tracked. .. _envoy_v3_api_field_service.discovery.v3.Resource.ttl: ttl (`Duration `_) Time-to-live value for the resource. For each resource, a timer is started. The timer is reset each time the resource is received with a new TTL. If the resource is received with no TTL set, the timer is removed for the resource. Upon expiration of the timer, the configuration for the resource will be removed. The TTL can be refreshed or changed by sending a response that doesn't change the resource version. In this case the ``resource`` field does not need to be populated, which allows for light-weight "heartbeat" updates to keep a resource with a TTL alive. The TTL feature is meant to support configurations that should be removed in the event of a management server failure. For example, the feature may be used for fault injection testing where the fault injection should be terminated in the event that Envoy loses contact with the management server. .. _envoy_v3_api_field_service.discovery.v3.Resource.metadata: metadata (:ref:`config.core.v3.Metadata `) The Metadata field can be used to provide additional information for the resource. E.g. the trace data for debugging.