Configuration sources

Configuration sources

core.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": "..."
}

api_type

(core.ApiConfigSource.ApiType) API type (gRPC, REST, delta gRPC)

transport_api_version

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

(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

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

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

Enum core.ApiConfigSource.ApiType

[core.ApiConfigSource.ApiType proto]

APIs may be fetched via either REST or gRPC.

UNSUPPORTED_REST_LEGACY

(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

⁣gRPC v2 API.

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.

DELTA_GRPC is not yet entirely implemented! Initially, only CDS is available. Do not use for other xDSes.

core.AggregatedConfigSource

[core.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.

{}

core.RateLimitSettings

[core.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.

core.ConfigSource

[core.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": "...",
  "api_config_source": "{...}",
  "ads": "{...}",
  "initial_fetch_timeout": "{...}",
  "resource_api_version": "..."
}

path

(string) Path on the filesystem to source and watch for configuration updates. When sourcing configuration for secret, the certificate and key files are also watched for updates.

Note

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

Note

Envoy will only 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.

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

api_config_source

(core.ApiConfigSource) API configuration source.

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

ads

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

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

Enum core.ApiVersion

[core.ApiVersion proto]

xDS API 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.

⁣Use xDS v2 API.

⁣Use xDS v3 API.