base.proto

Package: envoy.api.v2.core

Types:

Enums:
- [RoutingPriority](#routingpriority)
- [RequestMethod](#requestmethod)
- [TrafficDirection](#trafficdirection)
Source File: envoy/api/v2/core/base.proto

Locality

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

"region": string
"zone": string
"subZone": string
Field Type Description Default
region string Region this :ref:zone <envoy_api_field_core.Locality.zone> belongs to.
zone string Defines the local service zone where Envoy is running. Though optional, it should be set if discovery service routing is used and the discovery service exposes :ref:zone data <envoy_api_field_endpoint.LocalityLbEndpoints.locality>, either in this message or via :option:--service-zone. The meaning of zone is context dependent, e.g. Availability Zone (AZ) <https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html>_ on AWS, Zone <https://cloud.google.com/compute/docs/regions-zones/>_ on GCP, etc.
subZone 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

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": string
"cluster": string
"metadata": .google.protobuf.Struct
"locality": .envoy.api.v2.core.Locality
"buildVersion": string
Field Type Description Default
id string An opaque node identifier for the Envoy node. This also provides the local service node name. It should be set if any of the following features are used: :ref:statsd <arch_overview_statistics>, :ref:CDS <config_cluster_manager_cds>, and :ref:HTTP tracing <arch_overview_tracing>, either in this message or via :option:--service-node.
cluster string Defines the local service cluster name where Envoy is running. Though optional, it should be set if any of the following features are used: :ref:statsd <arch_overview_statistics>, :ref:health check cluster verification <envoy_api_field_core.HealthCheck.HttpHealthCheck.service_name>, :ref:runtime override directory <envoy_api_msg_config.bootstrap.v2.Runtime>, :ref:user agent addition <envoy_api_field_config.filter.network.http_connection_manager.v2.HttpConnectionManager.add_user_agent>, :ref:HTTP global rate limiting <config_http_filters_rate_limit>, :ref:CDS <config_cluster_manager_cds>, and :ref:HTTP tracing <arch_overview_tracing>, either in this message or via :option:--service-cluster.
metadata .google.protobuf.Struct Opaque metadata extending the node identifier. Envoy will pass this directly to the management server.
locality .envoy.api.v2.core.Locality Locality specifying where the Envoy instance is running.
buildVersion 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.

Metadata

Metadata provides additional inputs to filters based on matched listeners, filter chains, routes and endpoints. It is structured as a map, usually 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.

Another example use of metadata is to per service config info in cluster metadata, which may get consumed by multiple filters.

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:

Field Type Description Default
filterMetadata map<string, .google.protobuf.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

Runtime derived uint32 with a default when not specified.

"defaultValue": int
"runtimeKey": string
Field Type Description Default
defaultValue int Default value if runtime value is not available.
runtimeKey string Runtime key to get value for comparison. This value is used if defined.

RuntimeFeatureFlag

Runtime derived bool with a default when not specified.

"defaultValue": .google.protobuf.BoolValue
"runtimeKey": string
Field Type Description Default
defaultValue .google.protobuf.BoolValue Default value if runtime value is not available.
runtimeKey string Runtime key to get value for comparison. This value is used if defined. The boolean value must be represented via its canonical JSON encoding <https://developers.google.com/protocol-buffers/docs/proto3#json>_.

HeaderValue

Header name/value pair.

"key": string
"value": string
Field Type Description Default
key string Header name.
value string Header value. The same :ref:format specifier <config_access_log_format> as used for :ref:HTTP access logging <config_access_log> applies here, however unknown header values are replaced with the empty string instead of -.

HeaderValueOption

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

"header": .envoy.api.v2.core.HeaderValue
"append": .google.protobuf.BoolValue
Field Type Description Default
header .envoy.api.v2.core.HeaderValue Header name/value pair that this option applies to.
append .google.protobuf.BoolValue Should the value be appended? If true (default), the value is appended to existing values.

HeaderMap

Wrapper for a set of headers.

"headers": []envoy.api.v2.core.HeaderValue
Field Type Description Default
headers []envoy.api.v2.core.HeaderValue

DataSource

Data source consisting of either a file or an inline value.

"filename": string
"inlineBytes": bytes
"inlineString": string
Field Type Description Default
filename string Local filesystem data source. Only one of filename, or inlineString can be set.
inlineBytes bytes Bytes inlined in the configuration. Only one of inlineBytes, or inlineString can be set.
inlineString string String inlined in the configuration. Only one of inlineString, or inlineBytes can be set.

RemoteDataSource

The message specifies how to fetch data from remote and how to verify it.

"httpUri": .envoy.api.v2.core.HttpUri
"sha256": string
Field Type Description Default
httpUri .envoy.api.v2.core.HttpUri The HTTP URI to fetch the remote data.
sha256 string SHA256 string for verifying data.

AsyncDataSource

Async data source which support async data fetch.

"local": .envoy.api.v2.core.DataSource
"remote": .envoy.api.v2.core.RemoteDataSource
Field Type Description Default
local .envoy.api.v2.core.DataSource Local async data source. Only one of local or remote can be set.
remote .envoy.api.v2.core.RemoteDataSource Remote async data source. Only one of remote or local can be set.

TransportSocket

Configuration for transport socket in :ref:listeners <config_listeners> and :ref:clusters <envoy_api_msg_Cluster>. 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": string
"config": .google.protobuf.Struct
"typedConfig": .google.protobuf.Any
Field Type Description Default
name string The name of the transport socket to instantiate. The name must match a supported transport socket implementation.
config .google.protobuf.Struct Only one of config or typedConfig can be set.
typedConfig .google.protobuf.Any Only one of typedConfig or config can be set.

SocketOption

Generic socket option message. This would be used to set socket options that might not exist in upstream kernels or precompiled Envoy binaries.

"description": string
"level": int
"name": int
"intValue": int
"bufValue": bytes
"state": .envoy.api.v2.core.SocketOption.SocketState
Field Type Description Default
description string An optional name to give this socket option for debugging, etc. Uniqueness is not required and no special meaning is assumed.
level int Corresponding to the level value passed to setsockopt, such as IPPROTO_TCP.
name int The numeric name as passed to setsockopt.
intValue int Because many sockopts take an int value. Only one of intValue or bufValue can be set.
bufValue bytes Otherwise it’s a byte buffer. Only one of bufValue or intValue can be set.
state .envoy.api.v2.core.SocketOption.SocketState The state in which the option will be applied. When used in BindConfig STATE_PREBIND is currently the only valid value.

SocketState

Name Description
STATE_PREBIND Socket options are applied after socket creation but before binding the socket to a port
STATE_BOUND Socket options are applied after binding the socket to a port but before calling listen()
STATE_LISTENING Socket options are applied after calling listen()

RuntimeFractionalPercent

Runtime derived FractionalPercent with defaults for when the numerator or denominator is not specified via a runtime key.

"defaultValue": .envoy.type.FractionalPercent
"runtimeKey": string
Field Type Description Default
defaultValue .envoy.type.FractionalPercent Default value if the runtime value’s for the numerator/denominator keys are not available.
runtimeKey string Runtime key for a YAML representation of a FractionalPercent.

ControlPlane

Identifies a specific ControlPlane instance that Envoy is connected to.

"identifier": string
Field Type Description Default
identifier string An opaque control plane identifier that uniquely identifies an instance of control plane. This can be used to identify which control plane instance, the Envoy is connected to.

RoutingPriority

Description: Envoy supports :ref:upstream priority routing <arch_overview_http_routing_priority> 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.

Name Description
DEFAULT
HIGH

RequestMethod

Description: HTTP request method.

Name Description
METHOD_UNSPECIFIED
GET
HEAD
POST
PUT
DELETE
CONNECT
OPTIONS
TRACE
PATCH

TrafficDirection

Description: Identifies the direction of the traffic relative to the local Envoy.

Name Description
UNSPECIFIED Default option is unspecified.
INBOUND The transport is used for incoming traffic.
OUTBOUND The transport is used for outgoing traffic.