From 3cadfb152fee3160be689ee4545e15dfcf8ebd37 Mon Sep 17 00:00:00 2001 From: "Mark D. Roth" Date: Wed, 14 Dec 2016 07:52:47 -0800 Subject: Started updating docs. --- doc/naming.md | 49 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 39 insertions(+), 10 deletions(-) (limited to 'doc/naming.md') diff --git a/doc/naming.md b/doc/naming.md index d0c892e8d9..5d603061f8 100644 --- a/doc/naming.md +++ b/doc/naming.md @@ -1,30 +1,59 @@ -#gRPC Naming and Discovery Support +# gRPC Name Resolution ## Overview -gRPC supports DNS as the default name-system. A number of alternative name-systems are used in various deployments. We propose an API that is general enough to support a range of name-systems and the corresponding syntax for names. The gRPC client library in various languages will provide a plugin mechanism so resolvers for different name-systems can be plugged in. +gRPC supports DNS as the default name-system. A number of alternative +name-systems are used in various deployments. We support an API that is +general enough to support a range of name-systems and the corresponding +syntax for names. The gRPC client library in various languages will +provide a plugin mechanism so resolvers for different name-systems can +be plugged in. -## Detailed Proposal +## Detailed Design - A fully qualified, self contained name used for gRPC channel construction uses the syntax: +### Name Syntax + +A fully qualified, self contained name used for gRPC channel construction +uses the syntax: ``` scheme://authority/endpoint_name ``` -Here, scheme indicates the name-system to be used. Example schemes to be supported include: +Here, `scheme` indicates the name-system to be used. Example schemes to +be supported include: * `dns` * `etcd` -Authority indicates some scheme-specific bootstrap information, e.g., for DNS, the authority may include the IP[:port] of the DNS server to use. Often, a DNS name may used as the authority, since the ability to resolve DNS names is already built into all gRPC client libraries. +The `authority` indicates some scheme-specific bootstrap information, e.g., +for DNS, the authority may include the IP[:port] of the DNS server to +use. Often, a DNS name may be used as the authority, since the ability to +resolve DNS names is already built into all gRPC client libraries. + +Finally, the `endpoint_name` indicates a concrete name to be looked up +in a given name-system identified by the scheme and the authority. The +syntax of the endpoint name is dictated by the scheme in use. -Finally, the endpoint_name indicates a concrete name to be looked up in a given name-system identified by the scheme and the authority. The syntax of endpoint name is dictated by the scheme in use. +### Resolver Plugins -### Plugins +The gRPC client library will switch on the scheme to pick the right +resolver plugin and pass it the fully qualified name string. -The gRPC client library will switch on the scheme to pick the right resolver plugin and pass it the fully qualified name string. +Resolvers should be able to contact the authority and get a resolution +that they return back to the gRPC client library. The returned contents +include: -Resolvers should be able to contact the authority and get a resolution that they return back to the gRPC client library. The returned contents include a list of IP:port, an optional config and optional auth config data to be used for channel authentication. The plugin API allows the resolvers to continuously watch an endpoint_name and return updated resolutions as needed. +- A list of resolved addresses, each of which has three attributes: + - The address itself, in IP:port form. + - A boolean indicating whether the address is a backend address (i.e., + the address to use to contact the server directly) or a balancer + address (for cases where [external load balancing](load-balancing.md) + is in use). + - The name of the balancer, if the address is a balancer address. + This will be used to perform peer authorization. +- A [service config](service-config.md). +The plugin API allows the resolvers to continuously watch an endpoint +and return updated resolutions as needed. -- cgit v1.2.3