To use the v2 API, it’s necessary to supply a bootstrap configuration file. This
provides static server configuration and configures Envoy to access dynamic
configuration if needed. As with the v1
JSON/YAML configuration, this is supplied on the command-line via the -c
flag, i.e.:

./envoy -c <path to config>.{json,yaml,pb,pb_text} --v2-config-only

where the extension reflects the underlying v2 config representation. The
--v2-config-only flag is not strictly required as Envoy will attempt
to autodetect the config file version, but this option provides an enhanced
debug experience when configuration parsing fails.

Notice above that xds_cluster is defined to point Envoy at the management server. Even in
an otherwise completely dynamic configurations, some static resources need to
be defined to point Envoy at its xDS management server(s).

In the above example, the EDS management server could then return a proto encoding of a
DiscoveryResponse:

A v2 xDS management server will implement the below endpoints as required for
gRPC and/or REST serving. In both streaming gRPC and
REST-JSON cases, a DiscoveryRequest is sent and a
DiscoveryResponse received following the
xDS protocol.

While Envoy fundamentally employs an eventual consistency model, ADS provides an
opportunity to sequence API update pushes and ensure affinity of a single
management server for an Envoy node for API updates. ADS allows one or more APIs
and their resources to be delivered on a single, bidirectional gRPC stream by
the management server. Without this, some APIs such as RDS and EDS may require
the management of multiple streams and connections to distinct management
servers.

ADS will allow for hitless updates of configuration by appropriate sequencing.
For example, suppose foo.com was mappped to cluster X. We wish to change the
mapping in the route table to point foo.com at cluster Y. In order to do
this, a CDS/EDS update must first be delivered containing both clusters X and
Y.

Without ADS, the CDS/EDS/RDS streams may point at distinct management servers,
or when on the same management server at distinct gRPC streams/connections that
require coordination. The EDS resource requests may be split across two distinct
streams, one for X and one for Y. ADS allows these to be coalesced to a
single stream to a single management server, avoiding the need for distributed
synchronization to correctly sequence the update. With ADS, the management
server would deliver the CDS, EDS and then RDS updates on a single stream.

ADS is only available for gRPC streaming (not REST) and is described more fully
in this
document. The gRPC endpoint is:

All features described in the v2 API reference are
implemented unless otherwise noted. In the v2 API reference and the
v2 API repository, all protos are
frozen unless they are tagged as draft or experimental. Here, frozen
means that we will not break wire format compatibility.

Frozen protos may be further extended, e.g. by adding new fields, in a
manner that does not break backwards compatibility.
Fields in the above protos may be later deprecated, subject to the
breaking change policy,
when their related functionality is no longer required. While frozen APIs
have their wire format compatibility preserved, we reserve the right to change
proto namespaces, file locations and nesting relationships, which may cause
breaking code changes. We will aim to minimize the churn here.

Protos tagged draft, meaning that they are near finalized, are
likely to be at least partially implemented in Envoy but may have wire format
breaking changes made prior to freezing.

Protos tagged experimental, have the same caveats as draft protos
and may have have major changes made prior to Envoy implementation and freezing.