data-plane-api/README.md

# Envoy v2 JSON REST and gRPC APIs

## Goals

This repository contains the draft v2 JSON REST and gRPC
[Envoy](https://github.com/lyft/envoy/) APIs. Envoy today has a number of JSON
REST APIs through which it may discover and have updated its runtime
configuration from some management server. These are:

* [Cluster Discovery Service (CDS)](https://lyft.github.io/envoy/docs/configuration/cluster_manager/cds.html)
* [Rate Limit Service (RLS)](https://lyft.github.io/envoy/docs/configuration/overview/rate_limit.html)
* [Route Discovery Service (RDS)](https://lyft.github.io/envoy/docs/configuration/http_conn_man/rds.html)
* [Service Discovery Service (SDS)](https://lyft.github.io/envoy/docs/configuration/cluster_manager/sds_api.html)

Version 2 of the Envoy API will evolve existing APIs and introduce new APIs to:

* Allow for more advanced load balancing through load and resource utilization reporting to management servers.
* Improve N^2 health check scalability issues by optionally offloading health checking to other Envoy instances.
* Support Envoy deployment in edge, sidecar and middle proxy deployment models via changes to the listener model and CDS/SDS APIs.
* Allow streaming updates from the management server on change, instead of polling APIs from Envoy. gRPC APIs will be supported
  alongside JSON REST APIs to provide for this.
* Ensure all Envoy runtime configuration is dynamically discoverable via API
  calls, including listener configuration, certificates and runtime settings, which are today sourced from the filesystem. There
  will still remain a static bootstrap configuration file that will specify items
  unlikely to change during runtime, including the Envoy node identity, xDS
  management server addresses, administration interface and tracing
  configuration.
* Revisit and where appropriate cleanup any v1 technical debt.

## Status

Draft work-in-progress. Input is welcome via issue filing. Small, localized PRs
are also welcome, but any major changes or suggestions should be coordinated in
a tracking issue with the authors.

Implementation work has begun and work items are tracked at
[here](https://github.com/lyft/envoy/issues?q=is%3Aopen+is%3Aissue+label%3A%22v2+API%22).

New features that correspond to the v2 API are initially tracked in this
repository. When they are agreed upon and the related PRs are merged, they
should be closed out and a corresponding issue created in
https://github.com/lyft/envoy/ and tagged with `v2 API`. A reference to the
closed issue should also be included.

## Principles

* [Proto3](https://developers.google.com/protocol-buffers/docs/proto3) will be
  used to specify the canonical API. This will provide directly the gRPC API and
  via gRPC-JSON transcoding the JSON REST API.

* xDS APIs should support eventual consistency. For example, if RDS references a
  cluster that has not yet been supplied by CDS, it should be silently ignored
  and traffic not forwarded until the CDS update occurs.

* The API is primarily intended for machine generation and consumption. It is
  expected that the management server is responsible for mapping higher level
  configuration concepts to API responses. Similarly, static configuration
  fragments may be generated by templating tools, etc. The APIs and tools
  used to generate xDS configuration are beyond the scope of the definitions in
  this repository.

* Listeners will be immutable. Any updates to a listener via LDS will require
  the draining of existing connections for the specific bound IP/port. As a
  result, new requests will only be guaranteed to observe the new configuration
  after existing connections have drained or the drain timeout.

* Versioning will be expressed via [proto3 package
  namespaces](https://developers.google.com/protocol-buffers/docs/proto3#packages),
  i.e. `package envoy.api.v2;`.

* Custom components (e.g. filters, resolvers, loggers) will use a reverse DNS naming scheme,
  e.g. `com.google.widget`, `com.lyft.widget`.

* [Wrapped](https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto)
  protobuf fields should be used for all non-string [scalar
  types](https://developers.google.com/protocol-buffers/docs/proto3#scalar), to
  support non-zero default values. While only some fields require wrapping, for
  consistency we prefer to have all non-string scalar fields wrapped.

## APIs

Unless otherwise stated, the APIs with the same names as v1 APIs have a similar role.

* [Cluster Discovery Service (CDS)](api/cds.proto).
* [Endpoint Discovery Service (EDS)](api/eds.proto). This has the same role as SDS in the [v1 API](https://lyft.github.io/envoy/docs/configuration/cluster_manager/sds_api.html),
  the new name better describes what the API does in practice. Advanced global load balancing capable of utilizing N-dimensional upstream metrics is now supported.
* [Health Discovery Service (HDS)](api/hds.proto). This new API supports efficient endpoint health discovery by the management server via the Envoy instances it manages. Individual Envoy instances
  will typically receive HDS instructions to health check a subset of all
  endpoints. The health check subset may not be a subset of the Envoy instance's
  EDS endpoints.
* [Listener Discovery Service (LDS)](api/lds.proto). This new API supports dynamic discovery of the listener configuration (which ports to bind to, TLS details, filter chains, etc.).
* Rate Limit Discovery Service (RLDS). This is the same as RLS in v1.
* [Route Discovery Service (RDS)](api/rds.proto).

## Terminology

Some relevant [existing terminology](https://lyft.github.io/envoy/docs/intro/arch_overview/terminology.html) is
repeated below and some new v2 terms introduced.

* Cluster: A cluster is a group of logically similar endpoints that Envoy
  connects to. In v2, RDS routes points to clusters, CDS provides cluster configuration and
  Envoy discovers the cluster members via EDS.

* Downstream: A downstream host connects to Envoy, sends requests, and receives responses.

* Endpoint: An endpoint is an upstream host that is a member of one or more clusters. Endpoints are discovered via EDS.

* Listener: A listener is a named network location (e.g., port, unix domain socket, etc.) that can be connected to by downstream clients. Envoy exposes one or more listeners that downstream hosts connect to.

* Locality: A location where an Envoy instance or an endpoint runs. This includes
  region, zone and sub-zone identification.

* Management server: A logical server implementing the v2 Envoy APIs. This is not necessarily a single physical machine since it may be replicated/sharded and API serving for different xDS APIs may be implemented on different physical machines.

* Region: Geographic region where a zone is located.

* Sub-zone: Location within a zone where an Envoy instance or an endpoint runs.
  This allows for multiple load balancing targets within a zone.

* Upstream: An upstream host receives connections and requests from Envoy and returns responses.

* xDS: CDS/EDS/HDS/LDS/RLDS/RDS APIs.

* Zone: Availability Zone (AZ) in AWS, Zone in GCP.