.. _envoy_v3_api_file_envoy/config/core/v3/config_source.proto:

Configuration sources (proto)
=============================






.. _envoy_v3_api_msg_config.core.v3.ApiConfigSource:

config.core.v3.ApiConfigSource
------------------------------


:repo:`[config.core.v3.ApiConfigSource proto] <api/envoy/config/core/v3/config_source.proto#L43>`

API configuration source. This identifies the API type and cluster that Envoy
will use to fetch an xDS API.



.. code-block:: json
  :force:

  {
    "api_type": ...,
    "transport_api_version": ...,
    "cluster_names": [],
    "grpc_services": [],
    "refresh_delay": {...},
    "request_timeout": {...},
    "rate_limit_settings": {...},
    "set_node_on_first_message_only": ...,
    "config_validators": []
  }

.. _envoy_v3_api_field_config.core.v3.ApiConfigSource.api_type:


api_type
  (:ref:`config.core.v3.ApiConfigSource.ApiType <envoy_v3_api_enum_config.core.v3.ApiConfigSource.ApiType>`) API type (gRPC, REST, delta gRPC)


.. _envoy_v3_api_field_config.core.v3.ApiConfigSource.transport_api_version:


transport_api_version
  (:ref:`config.core.v3.ApiVersion <envoy_v3_api_enum_config.core.v3.ApiVersion>`) API version for xDS transport protocol. This describes the xDS gRPC/REST
  endpoint and version of [Delta]DiscoveryRequest/Response used on the wire.


.. _envoy_v3_api_field_config.core.v3.ApiConfigSource.cluster_names:


cluster_names
  (**repeated** `string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Cluster names should be used only with REST. If > 1
  cluster is defined, clusters will be cycled through if any kind of failure
  occurs.

  .. note::

   The cluster with name ``cluster_name`` must be statically defined and its
   type must not be ``EDS``.


.. _envoy_v3_api_field_config.core.v3.ApiConfigSource.grpc_services:


grpc_services
  (**repeated** :ref:`config.core.v3.GrpcService <envoy_v3_api_msg_config.core.v3.GrpcService>`) Multiple gRPC services be provided for GRPC. If > 1 cluster is defined,
  services will be cycled through if any kind of failure occurs.


.. _envoy_v3_api_field_config.core.v3.ApiConfigSource.refresh_delay:


refresh_delay
  (`Duration <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration>`_) For REST APIs, the delay between successive polls.


.. _envoy_v3_api_field_config.core.v3.ApiConfigSource.request_timeout:


request_timeout
  (`Duration <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration>`_) For REST APIs, the request timeout. If not set, a default value of 1s will be used.


.. _envoy_v3_api_field_config.core.v3.ApiConfigSource.rate_limit_settings:


rate_limit_settings
  (:ref:`config.core.v3.RateLimitSettings <envoy_v3_api_msg_config.core.v3.RateLimitSettings>`) For GRPC APIs, the rate limit settings. If present, discovery requests made by Envoy will be
  rate limited.


.. _envoy_v3_api_field_config.core.v3.ApiConfigSource.set_node_on_first_message_only:


set_node_on_first_message_only
  (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Skip the node identifier in subsequent discovery requests for streaming gRPC config types.


.. _envoy_v3_api_field_config.core.v3.ApiConfigSource.config_validators:


config_validators
  (**repeated** :ref:`config.core.v3.TypedExtensionConfig <envoy_v3_api_msg_config.core.v3.TypedExtensionConfig>`) A list of config validators that will be executed when a new update is
  received from the ApiConfigSource. Note that each validator handles a
  specific xDS service type, and only the validators corresponding to the
  type url (in ``:ref: DiscoveryResponse`` or ``:ref: DeltaDiscoveryResponse``)
  will be invoked.
  If the validator returns false or throws an exception, the config will be rejected by
  the client, and a NACK will be sent.


  .. _extension_category_envoy.config.validators:

  .. tip::

    This extension category has the following known extensions:


    - :ref:`envoy.config.validators.minimum_clusters_validator <extension_envoy.config.validators.minimum_clusters_validator>`





.. _envoy_v3_api_enum_config.core.v3.ApiConfigSource.ApiType:

Enum config.core.v3.ApiConfigSource.ApiType
-------------------------------------------


:repo:`[config.core.v3.ApiConfigSource.ApiType proto] <api/envoy/config/core/v3/config_source.proto#L47>`

APIs may be fetched via either REST or gRPC.



.. _envoy_v3_api_enum_value_config.core.v3.ApiConfigSource.ApiType.DEPRECATED_AND_UNAVAILABLE_DO_NOT_USE:


DEPRECATED_AND_UNAVAILABLE_DO_NOT_USE
  *(DEFAULT)* ⁣Ideally this would be 'reserved 0' but one can't reserve the default
  value. Instead we throw an exception if this is ever used.


.. _envoy_v3_api_enum_value_config.core.v3.ApiConfigSource.ApiType.REST:


REST
  ⁣REST-JSON v2 API. The `canonical JSON encoding
  <https://developers.google.com/protocol-buffers/docs/proto3#json>`_ for
  the v2 protos is used.


.. _envoy_v3_api_enum_value_config.core.v3.ApiConfigSource.ApiType.GRPC:


GRPC
  ⁣SotW gRPC service.


.. _envoy_v3_api_enum_value_config.core.v3.ApiConfigSource.ApiType.DELTA_GRPC:


DELTA_GRPC
  ⁣Using the delta xDS gRPC service, i.e. DeltaDiscovery{Request,Response}
  rather than Discovery{Request,Response}. Rather than sending Envoy the entire state
  with every update, the xDS server only sends what has changed since the last update.




.. _envoy_v3_api_msg_config.core.v3.AggregatedConfigSource:

config.core.v3.AggregatedConfigSource
-------------------------------------


:repo:`[config.core.v3.AggregatedConfigSource proto] <api/envoy/config/core/v3/config_source.proto#L125>`

Aggregated Discovery Service (ADS) options. This is currently empty, but when
set in :ref:`ConfigSource <envoy_v3_api_msg_config.core.v3.ConfigSource>` can be used to
specify that ADS is to be used.







.. _envoy_v3_api_msg_config.core.v3.RateLimitSettings:

config.core.v3.RateLimitSettings
--------------------------------


:repo:`[config.core.v3.RateLimitSettings proto] <api/envoy/config/core/v3/config_source.proto#L143>`

Rate Limit settings to be applied for discovery requests made by Envoy.



.. code-block:: json
  :force:

  {
    "max_tokens": {...},
    "fill_rate": {...}
  }

.. _envoy_v3_api_field_config.core.v3.RateLimitSettings.max_tokens:


max_tokens
  (`UInt32Value <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#uint32value>`_) Maximum number of tokens to be used for rate limiting discovery request calls. If not set, a
  default value of 100 will be used.


.. _envoy_v3_api_field_config.core.v3.RateLimitSettings.fill_rate:


fill_rate
  (`DoubleValue <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#doublevalue>`_) Rate at which tokens will be filled per second. If not set, a default fill rate of 10 tokens
  per second will be used. The minimal fill rate is once per year. Lower
  fill rates will be set to once per year.



.. _envoy_v3_api_msg_config.core.v3.PathConfigSource:

config.core.v3.PathConfigSource
-------------------------------


:repo:`[config.core.v3.PathConfigSource proto] <api/envoy/config/core/v3/config_source.proto#L158>`

Local filesystem path configuration source.



.. code-block:: json
  :force:

  {
    "path": ...,
    "watched_directory": {...}
  }

.. _envoy_v3_api_field_config.core.v3.PathConfigSource.path:


path
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *REQUIRED*) Path on the filesystem to source and watch for configuration updates.
  When sourcing configuration for a :ref:`secret <envoy_v3_api_msg_extensions.transport_sockets.tls.v3.Secret>`,
  the certificate and key files are also watched for updates.

  .. note::

   The path to the source must exist at config load time.

  .. note::

    If ``watched_directory`` is *not* configured, Envoy will watch the file path for *moves*.
    This is because in general only moves are atomic. The same method of swapping files as is
    demonstrated in the :ref:`runtime documentation <config_runtime_symbolic_link_swap>` can be
    used here also. If ``watched_directory`` is configured, no watch will be placed directly on
    this path. Instead, the configured ``watched_directory`` will be used to trigger reloads of
    this path. This is required in certain deployment scenarios. See below for more information.


.. _envoy_v3_api_field_config.core.v3.PathConfigSource.watched_directory:


watched_directory
  (:ref:`config.core.v3.WatchedDirectory <envoy_v3_api_msg_config.core.v3.WatchedDirectory>`) If configured, this directory will be watched for *moves*. When an entry in this directory is
  moved to, the ``path`` will be reloaded. This is required in certain deployment scenarios.

  Specifically, if trying to load an xDS resource using a
  `Kubernetes ConfigMap <https://kubernetes.io/docs/concepts/configuration/configmap/>`_, the
  following configuration might be used:
  1. Store xds.yaml inside a ConfigMap.
  2. Mount the ConfigMap to ``/config_map/xds``
  3. Configure path ``/config_map/xds/xds.yaml``
  4. Configure watched directory ``/config_map/xds``

  The above configuration will ensure that Envoy watches the owning directory for moves which is
  required due to how Kubernetes manages ConfigMap symbolic links during atomic updates.



.. _envoy_v3_api_msg_config.core.v3.ConfigSource:

config.core.v3.ConfigSource
---------------------------


:repo:`[config.core.v3.ConfigSource proto] <api/envoy/config/core/v3/config_source.proto#L200>`

Configuration for :ref:`listeners <config_listeners>`, :ref:`clusters
<config_cluster_manager>`, :ref:`routes
<envoy_v3_api_msg_config.route.v3.RouteConfiguration>`, :ref:`endpoints
<arch_overview_service_discovery>` etc. may either be sourced from the
filesystem or from an xDS API source. Filesystem configs are watched with
inotify for updates.



.. code-block:: json
  :force:

  {
    "path": ...,
    "path_config_source": {...},
    "api_config_source": {...},
    "ads": {...},
    "initial_fetch_timeout": {...},
    "resource_api_version": ...
  }

.. _envoy_v3_api_field_config.core.v3.ConfigSource.path:


path
  (`string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Deprecated in favor of ``path_config_source``. Use that field instead.


  

  Precisely one of :ref:`path <envoy_v3_api_field_config.core.v3.ConfigSource.path>`, :ref:`path_config_source <envoy_v3_api_field_config.core.v3.ConfigSource.path_config_source>`, :ref:`api_config_source <envoy_v3_api_field_config.core.v3.ConfigSource.api_config_source>`, :ref:`ads <envoy_v3_api_field_config.core.v3.ConfigSource.ads>` must be set.

.. _envoy_v3_api_field_config.core.v3.ConfigSource.path_config_source:


path_config_source
  (:ref:`config.core.v3.PathConfigSource <envoy_v3_api_msg_config.core.v3.PathConfigSource>`) Local filesystem path configuration source.


  

  Precisely one of :ref:`path <envoy_v3_api_field_config.core.v3.ConfigSource.path>`, :ref:`path_config_source <envoy_v3_api_field_config.core.v3.ConfigSource.path_config_source>`, :ref:`api_config_source <envoy_v3_api_field_config.core.v3.ConfigSource.api_config_source>`, :ref:`ads <envoy_v3_api_field_config.core.v3.ConfigSource.ads>` must be set.

.. _envoy_v3_api_field_config.core.v3.ConfigSource.api_config_source:


api_config_source
  (:ref:`config.core.v3.ApiConfigSource <envoy_v3_api_msg_config.core.v3.ApiConfigSource>`) API configuration source.


  

  Precisely one of :ref:`path <envoy_v3_api_field_config.core.v3.ConfigSource.path>`, :ref:`path_config_source <envoy_v3_api_field_config.core.v3.ConfigSource.path_config_source>`, :ref:`api_config_source <envoy_v3_api_field_config.core.v3.ConfigSource.api_config_source>`, :ref:`ads <envoy_v3_api_field_config.core.v3.ConfigSource.ads>` must be set.

.. _envoy_v3_api_field_config.core.v3.ConfigSource.ads:


ads
  (:ref:`config.core.v3.AggregatedConfigSource <envoy_v3_api_msg_config.core.v3.AggregatedConfigSource>`) When set, ADS will be used to fetch resources. The ADS API configuration
  source in the bootstrap configuration is used.


  

  Precisely one of :ref:`path <envoy_v3_api_field_config.core.v3.ConfigSource.path>`, :ref:`path_config_source <envoy_v3_api_field_config.core.v3.ConfigSource.path_config_source>`, :ref:`api_config_source <envoy_v3_api_field_config.core.v3.ConfigSource.api_config_source>`, :ref:`ads <envoy_v3_api_field_config.core.v3.ConfigSource.ads>` must be set.

.. _envoy_v3_api_field_config.core.v3.ConfigSource.initial_fetch_timeout:


initial_fetch_timeout
  (`Duration <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#duration>`_) When this timeout is specified, Envoy will wait no longer than the specified time for first
  config response on this xDS subscription during the :ref:`initialization process
  <arch_overview_initialization>`. After reaching the timeout, Envoy will move to the next
  initialization phase, even if the first config is not delivered yet. The timer is activated
  when the xDS API subscription starts, and is disarmed on first config update or on error. 0
  means no timeout - Envoy will wait indefinitely for the first xDS config (unless another
  timeout applies). The default is 15s.


.. _envoy_v3_api_field_config.core.v3.ConfigSource.resource_api_version:


resource_api_version
  (:ref:`config.core.v3.ApiVersion <envoy_v3_api_enum_config.core.v3.ApiVersion>`) API version for xDS resources. This implies the type URLs that the client
  will request for resources and the resource type that the client will in
  turn expect to be delivered.



.. _envoy_v3_api_msg_config.core.v3.ExtensionConfigSource:

config.core.v3.ExtensionConfigSource
------------------------------------


:repo:`[config.core.v3.ExtensionConfigSource proto] <api/envoy/config/core/v3/config_source.proto#L265>`

Configuration source specifier for a late-bound extension configuration. The
parent resource is warmed until all the initial extension configurations are
received, unless the flag to apply the default configuration is set.
Subsequent extension updates are atomic on a per-worker basis. Once an
extension configuration is applied to a request or a connection, it remains
constant for the duration of processing. If the initial delivery of the
extension configuration fails, due to a timeout for example, the optional
default configuration is applied. Without a default configuration, the
extension is disabled, until an extension configuration is received. The
behavior of a disabled extension depends on the context. For example, a
filter chain with a disabled extension filter rejects all incoming streams.



.. code-block:: json
  :force:

  {
    "config_source": {...},
    "default_config": {...},
    "apply_default_config_without_warming": ...,
    "type_urls": []
  }

.. _envoy_v3_api_field_config.core.v3.ExtensionConfigSource.config_source:


config_source
  (:ref:`config.core.v3.ConfigSource <envoy_v3_api_msg_config.core.v3.ConfigSource>`) 

.. _envoy_v3_api_field_config.core.v3.ExtensionConfigSource.default_config:


default_config
  (`Any <https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#any>`_) Optional default configuration to use as the initial configuration if
  there is a failure to receive the initial extension configuration or if
  ``apply_default_config_without_warming`` flag is set.


.. _envoy_v3_api_field_config.core.v3.ExtensionConfigSource.apply_default_config_without_warming:


apply_default_config_without_warming
  (`bool <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_) Use the default config as the initial configuration without warming and
  waiting for the first discovery response. Requires the default configuration
  to be supplied.


.. _envoy_v3_api_field_config.core.v3.ExtensionConfigSource.type_urls:


type_urls
  (**repeated** `string <https://developers.google.com/protocol-buffers/docs/proto#scalar>`_, *REQUIRED*) A set of permitted extension type URLs. Extension configuration updates are rejected
  if they do not match any type URL in the set.



.. _envoy_v3_api_enum_config.core.v3.ApiVersion:

Enum config.core.v3.ApiVersion
------------------------------


:repo:`[config.core.v3.ApiVersion proto] <api/envoy/config/core/v3/config_source.proto#L29>`

xDS API and non-xDS services version. This is used to describe both resource and transport
protocol versions (in distinct configuration fields).



.. _envoy_v3_api_enum_value_config.core.v3.ApiVersion.AUTO:


AUTO
  *(DEFAULT)* ⁣When not specified, we assume v3; it is the only supported version.


.. _envoy_v3_api_enum_value_config.core.v3.ApiVersion.V2:


V2
  ⁣Use xDS v2 API. This is no longer supported.


.. _envoy_v3_api_enum_value_config.core.v3.ApiVersion.V3:


V3
  ⁣Use xDS v3 API.