diff --git a/API_OVERVIEW.md b/API_OVERVIEW.md deleted file mode 100644 index f18d13a4..00000000 --- a/API_OVERVIEW.md +++ /dev/null @@ -1,129 +0,0 @@ -# Envoy v2 APIs for developers - -## Goals - -This repository contains both the implemented and draft v2 JSON REST and gRPC -[Envoy](https://github.com/envoyproxy/envoy/) APIs. - -Version 2 of the Envoy API evolves existing APIs and introduces 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, - CDS API, and EDS (formerly called SDS in v1) API. -* 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 - -See -[here](https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/v2_overview.html#status) -for the current status of the v2 APIs. - -See [here](CONTRIBUTING.md#api-changes) for the v2 API change process. - -## 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. A textual YAML input will be - supported for filesystem configuration files (e.g. the bootstrap file), in - addition to JSON, as a syntactic convenience. YAML file contents will be - internally converted to JSON and then follow the standard JSON-proto3 - conversion during Envoy config ingestion. - -* 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. Stronger consistency - guarantees are possible if the management server is able to sequence the xDS - APIs carefully (for example by using the ADS API below). By following the - `[CDS, EDS, LDS, RDS]` sequence for all pertinent resources, it will be - possible to avoid traffic outages during configuration update. - -* 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. - -* REST-JSON API equivalents will be provided for the basic singleton xDS - subscription services CDS/EDS/LDS/RDS/SDS. Advanced APIs such as HDS, ADS and - EDS multi-dimensional LB will be gRPC only. This avoids having to map - complicated bidirectional stream semantics onto REST. - -* 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`. - -## APIs - -Unless otherwise stated, the APIs with the same names as v1 APIs have a similar role. - -* [Cluster Discovery Service (CDS)](envoy/api/v2/cds.proto). -* [Endpoint Discovery Service (EDS)](envoy/api/v2/eds.proto). This has the same role as SDS in the [v1 API](https://www.envoyproxy.io/docs/envoy/latest/api-v1/cluster_manager/sds), - 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)](envoy/service/discovery/v2/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)](envoy/api/v2/lds.proto). This new API supports dynamic discovery of the listener configuration (which ports to bind to, TLS details, filter chains, etc.). -* [Metric Service (MS)](envoy/service/metrics/v2/metrics_service.proto). This new API allows Envoy to push (stream) metrics forever for servers to consume. -* [Rate Limit Service (RLS)](envoy/service/ratelimit/v2/rls.proto) -* [Route Discovery Service (RDS)](envoy/api/v2/rds.proto). -* [Secret Discovery Service (SDS)](envoy/service/discovery/v2/sds.proto). - -In addition to the above APIs, an aggregation API will be provided to allow for -fine grained control over the sequencing of API updates across discovery -services: - -* [Aggregated Discovery Service (ADS)](envoy/api/v2/discovery.proto). See - the [ADS overview](https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/v2_overview#aggregated-discovery-service). - -A protocol description for the xDS APIs is provided [here](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol). - -## Terminology - -Some relevant [existing terminology](https://www.envoyproxy.io/docs/envoy/latest/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/RLS/RDS/SDS APIs. - -* Zone: Availability Zone (AZ) in AWS, Zone in GCP. diff --git a/README.md b/README.md index 95f49ba5..fa6f3bb1 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,8 @@ The API tree can be found at two locations: # Further API reading -* [API overview for developers](API_OVERVIEW.md) +* [API style guide](STYLE.md) +* [API versioning guide](API_VERSIONING.md) * [API overview for users](https://www.envoyproxy.io/docs/envoy/latest/configuration/overview/v2_overview#) * [xDS protocol overview](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol) * [Contributing guide](CONTRIBUTING.md) diff --git a/STYLE.md b/STYLE.md index 791f9cf7..7e15d2ec 100644 --- a/STYLE.md +++ b/STYLE.md @@ -169,3 +169,61 @@ metadata. We describe these annotations below by category. the given package. This is consumed by `protoxform`. * `option (udpa.annotations.file_status).work_in_progress = true;` to denote a file that is still work-in-progress and subject to breaking changes. + +## Principles + +The following principles should be adhered to when extending or modifying the +xDS APIs: + +* The xDS APIs have a logical distinction between transport and data model: + - The xDS transport protocol describes the network transport on which xDS + configuration resources are delivered to clients. A versioned gRPC streaming + protocol with support for ACK/NACK is provided by xDS; this is known as the + xDS transport protocol (xDS-TP). xDS configuration resources can also be + delivered on other transports, e.g. HTTP or filesystem, with some + limitations (e.g. no version feedback). + - The xDS data model describes the xDS configuration resources themselves, + e.g. listeners, route configurations, clusters, endpoints, secrets. + +* The xDS APIs are directionally client and server neutral. While many aspects + of the APIs reflect the history of their origin as Envoy's control plane APIs, + API decisions going forward should reflect the principle of client neutrality. + +* The xDS APIs are expressed canonically as [Proto3](https://developers.google.com/protocol-buffers/docs/proto3). + Both JSON and YAML are also supported formats, with the standard JSON-proto3 + conversion used during client configuration ingestion. + +* xDS APIs are eventual consistency first. 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. Stronger consistency + guarantees are possible if the management server is able to sequence the xDS + APIs carefully (for example by using the ADS API below). By following the + `[CDS, EDS, LDS, RDS]` sequence for all pertinent resources, it will be + possible to avoid traffic outages during configuration update. + +* 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. With that consideration, + we also aim to have API artifacts readable by humans for debugging and + understanding applied configuration. This implies that APIs do not have to + have ergonomics as the main driver, but should still be reasonable to read by + humans. The APIs and tools used to generate xDS configuration are beyond the + scope of the definitions in this repository. + +* All supported transports (xDS-TP, HTTP, filesystem) support basic singleton xDS + subscription services CDS/EDS/LDS/RDS/SDS. Advanced APIs such as HDS, ADS and + EDS multi-dimensional LB are xDS-TP only. This avoids having to map + complicated bidirectional stream semantics onto REST, etc.. + +* Versioning follows the scheme described [here](API_VERSIONING.md). A key + principle that we target is that API consumers should not be exposed to + breaking changes where there is no substantial gain in functionality, + performance, security or implementation simplification. We will tolerate + technical debt in the API itself, e.g. in the form of vestigial deprecated + fields or reduced ergnomics (such as not using `oneof` when we would prefer + to), in order to meet this principle. + +* Namespaces for extensions, metadata, etc. use a reverse DNS naming scheme, + e.g. `com.google.widget`, `com.lyft.widget`. Client built-ins may be prefixed + with client name, e.g. `envoy.foo`, `grpc.bar`.