Configuration sources¶

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

api/v2/core/config_source.proto

config.core.v3.ApiConfigSource¶

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

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

api_type: (config.core.v3.ApiConfigSource.ApiType) API type (gRPC, REST, delta gRPC)

transport_api_version: (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.

cluster_names: (repeated string) 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.

grpc_services: (repeated 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.

refresh_delay: (Duration) For REST APIs, the delay between successive polls.

request_timeout: (Duration) For REST APIs, the request timeout. If not set, a default value of 1s will be used.

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

set_node_on_first_message_only: (bool) Skip the node identifier in subsequent discovery requests for streaming gRPC config types.

config_validators

(repeated 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.

Tip

This extension category has the following known extensions:

envoy.config.validators.minimum_clusters

Enum config.core.v3.ApiConfigSource.ApiType¶

[config.core.v3.ApiConfigSource.ApiType proto]

APIs may be fetched via either REST or gRPC.

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.

REST: ⁣REST-JSON v2 API. The canonical JSON encoding for the v2 protos is used.

GRPC: ⁣SotW gRPC service.

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.

config.core.v3.AggregatedConfigSource¶

[config.core.v3.AggregatedConfigSource proto]

Aggregated Discovery Service (ADS) options. This is currently empty, but when set in ConfigSource can be used to specify that ADS is to be used.

config.core.v3.RateLimitSettings¶

[config.core.v3.RateLimitSettings proto]

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

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

max_tokens: (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.

fill_rate: (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.

config.core.v3.PathConfigSource¶

[config.core.v3.PathConfigSource proto]

Local filesystem path configuration source.

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

path: (string, REQUIRED) Path on the filesystem to source and watch for configuration updates. When sourcing configuration for a 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 runtime documentation 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.

watched_directory

(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, 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.

config.core.v3.ConfigSource¶

[config.core.v3.ConfigSource proto]

Configuration for listeners, clusters, routes, endpoints etc. may either be sourced from the filesystem or from an xDS API source. Filesystem configs are watched with inotify for updates.

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

path

(string) Deprecated in favor of path_config_source. Use that field instead.

Precisely one of path, path_config_source, api_config_source, ads must be set.

path_config_source

(config.core.v3.PathConfigSource) Local filesystem path configuration source.

Precisely one of path, path_config_source, api_config_source, ads must be set.

api_config_source

(config.core.v3.ApiConfigSource) API configuration source.

Precisely one of path, path_config_source, api_config_source, ads must be set.

ads

(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 path, path_config_source, api_config_source, ads must be set.

initial_fetch_timeout: (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 initialization process. 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.

resource_api_version: (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.

config.core.v3.ExtensionConfigSource¶

[config.core.v3.ExtensionConfigSource proto]

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.

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

config_source: (config.core.v3.ConfigSource)

default_config: (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.

apply_default_config_without_warming: (bool) Use the default config as the initial configuration without warming and waiting for the first discovery response. Requires the default configuration to be supplied.

type_urls: (repeated string, REQUIRED) A set of permitted extension type URLs. Extension configuration updates are rejected if they do not match any type URL in the set.

Enum config.core.v3.ApiVersion¶

[config.core.v3.ApiVersion proto]

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

AUTO: (DEFAULT) ⁣When not specified, we assume v2, to ease migration to Envoy’s stable API versioning. If a client does not support v2 (e.g. due to deprecation), this is an invalid value.

V2: ⁣Use xDS v2 API.

V3: ⁣Use xDS v3 API.