Common types

Common types

Locality

Identifies location of where either Envoy runs or where upstream hosts run.

{
  "region": "...",
  "zone": "...",
  "sub_zone": "..."
}

region

(string) Region this zone belongs to.

zone

(string) Availability Zone (AZ) on AWS, Zone on GCP, etc.

sub_zone

(string) When used for locality of upstream hosts, this field further splits zone into smaller chunks of sub-zones so they can be load balanced independently.

Node

[Node proto]

Identifies a specific Envoy instance. The node identifier is presented to the management server, which may use this identifier to distinguish per Envoy configuration for serving.

{
  "id": "...",
  "cluster": "...",
  "metadata": "{...}",
  "locality": "{...}",
  "build_version": "..."
}

(string) An opaque node identifier for the Envoy node.

cluster

(string) The cluster that the Envoy node belongs to.

metadata

(Struct) Opaque metadata extending the node identifier. Envoy will pass this directly to the management server.

locality

(Locality) Locality specifying where the Envoy instance is running.

build_version

(string) This is motivated by informing a management server during canary which version of Envoy is being tested in a heterogeneous fleet. This will be set by Envoy in management server RPCs.

Endpoint

[Endpoint proto]

Upstream host identifier.

{
  "address": "{...}"
}

address

(Address)

Metadata

[Metadata proto]

Metadata provides additional inputs to filters based on matched listeners, filter chains, routes and endpoints. It is structured as a map from filter name (in reverse DNS format) to metadata specific to the filter. Metadata key-values for a filter are merged as connection and request handling occurs, with later values for the same key overriding earlier values.

An example use of metadata is providing additional values to http_connection_manager in the envoy.http_connection_manager.access_log namespace.

For load balancing, Metadata provides a means to subset cluster endpoints. Endpoints have a Metadata object associated and routes contain a Metadata object to match against. There are some well defined metadata used today for this purpose:

{"envoy.lb": {"canary": <bool> }} This indicates the canary status of an endpoint and is also used during header processing (x-envoy-upstream-canary) and for stats purposes.

{
  "filter_metadata": "{...}"
}

filter_metadata

(map<string, Struct>) Key is the reverse DNS filter name, e.g. com.acme.widget. The envoy.* namespace is reserved for Envoy’s built-in filters.

RuntimeUInt32

[RuntimeUInt32 proto]

Runtime derived uint32 with a default when not specified.

{
  "default_value": "...",
  "runtime_key": "..."
}

default_value

(uint32) Default value if runtime value is not available.

runtime_key

(string, REQUIRED) Runtime key to get value for comparison. This value is used if defined.

HeaderValue

[HeaderValue proto]

Header name/value pair.

{
  "key": "...",
  "value": "..."
}

key

(string) Header name.

value

(string) Header value.

The same format specifier as used for HTTP access logging applies here, however unknown header values are replaced with the empty string instead of -.

HeaderValueOption

[HeaderValueOption proto]

Header name/value pair plus option to control append behavior.

{
  "header": "{...}",
  "append": "{...}"
}

header

(HeaderValue) Header name/value pair that this option applies to.

append

(BoolValue) Should the value be appended? If true (default), the value is appended to existing values.

ApiConfigSource

[ApiConfigSource proto]

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

{
  "api_type": "...",
  "cluster_name": [],
  "refresh_delay": "{...}"
}

api_type

(ApiConfigSource.ApiType)

cluster_name

(string, REQUIRED) Multiple cluster names may be provided. If > 1 cluster is defined, clusters will be cycled through if any kind of failure occurs.

refresh_delay

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

Enum ApiConfigSource.ApiType

[ApiConfigSource.ApiType proto]

APIs may be fetched via either REST or gRPC.

REST_LEGACY

(DEFAULT) ⁣REST-JSON legacy corresponds to the v1 API.

REST

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

GRPC

⁣gRPC v2 API.

AggregatedConfigSource

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

{}

ConfigSource

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

path

(string) Path on the filesystem to source and watch for configuration updates.

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

api_config_source

(ApiConfigSource) API configuration source.

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

ads

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

TransportSocket

[TransportSocket proto]

Configuration for transport socket in listeners and clusters. If the configuration is empty, a default transport socket implementation and configuration will be chosen based on the platform and existence of tls_context.

{
  "name": "...",
  "config": "{...}"
}

name

(string, REQUIRED) The name of the transport socket to instantiate. The name must match a supported transport socket implementation.

config

(Struct) Implementation specific configuration which depends on the implementation being instantiated. See the supported transport socket implementations for further documentation.

Enum RoutingPriority

[RoutingPriority proto]

Envoy supports upstream priority routing both at the route and the virtual cluster level. The current priority implementation uses different connection pool and circuit breaking settings for each priority level. This means that even for HTTP/2 requests, two physical connections will be used to an upstream host. In the future Envoy will likely support true HTTP/2 priority over a single upstream connection.

DEFAULT

(DEFAULT) ⁣

HIGH

⁣

Enum RequestMethod

[RequestMethod proto]

HTTP request method.

METHOD_UNSPECIFIED

(DEFAULT) ⁣

GET

⁣

HEAD

⁣

POST

⁣

PUT

⁣

DELETE

⁣

CONNECT

⁣

OPTIONS

⁣

TRACE

⁣