1# gRPC Name Resolution
2
3## Overview
4
5gRPC supports DNS as the default name-system. A number of alternative
6name-systems are used in various deployments. We support an API that is
7general enough to support a range of name-systems and the corresponding
8syntax for names. The gRPC client library in various languages will
9provide a plugin mechanism so resolvers for different name-systems can
10be plugged in.
11
12## Detailed Design
13
14### Name Syntax
15
16A fully qualified, self contained name used for gRPC channel construction
17uses URI syntax as defined in [RFC 3986](https://tools.ietf.org/html/rfc3986).
18
19The URI scheme indicates what resolver plugin to use.  If no scheme
20prefix is specified or the scheme is unknown, the `dns` scheme is used
21by default.
22
23The URI path indicates the name to be resolved.
24
25Most gRPC implementations support the following URI schemes:
26
27- `dns:[//authority/]host[:port]` -- DNS (default)
28  - `host` is the host to resolve via DNS.
29  - `port` is the port to return for each address.  If not specified,
30    443 is used (but some implementations default to 80 for insecure
31    channels).
32  - `authority` indicates the DNS server to use, although this is only
33    supported by some implementations.  (In C-core, the default DNS
34    resolver does not support this, but the c-ares based resolver
35    supports specifying this in the form "IP:port".)
36
37- `unix:path` or `unix://absolute_path` -- Unix domain sockets (Unix systems only)
38  - `path` indicates the location of the desired socket.
39  - In the first form, the path may be relative or absolute; in the
40    second form, the path must be absolute (i.e., there will actually be
41    three slashes, two prior to the path and another to begin the
42    absolute path).
43
44The following schemes are supported by the gRPC C-core implementation,
45but may not be supported in other languages:
46
47- `ipv4:address[:port][,address[:port],...]` -- IPv4 addresses
48  - Can specify multiple comma-delimited addresses of the form `address[:port]`:
49    - `address` is the IPv4 address to use.
50    - `port` is the port to use.  If not specified, 443 is used.
51
52- `ipv6:address[:port][,address[:port],...]` -- IPv6 addresses
53  - Can specify multiple comma-delimited addresses of the form `address[:port]`:
54    - `address` is the IPv6 address to use. To use with a `port` the `address`
55      must enclosed in literal square brackets (`[` and `]`).  Example:
56      `ipv6:[2607:f8b0:400e:c00::ef]:443` or `ipv6:[::]:1234`
57    - `port` is the port to use.  If not specified, 443 is used.
58
59In the future, additional schemes such as `etcd` could be added.
60
61### Resolver Plugins
62
63The gRPC client library will use the specified scheme to pick the right
64resolver plugin and pass it the fully qualified name string.
65
66Resolvers should be able to contact the authority and get a resolution
67that they return back to the gRPC client library. The returned contents
68include:
69
70- A list of resolved addresses (both IP address and port).  Each address
71  may have a set of arbitrary attributes (key/value pairs) associated with
72  it, which can be used to communicate information from the resolver to the
73  [load balancing](load-balancing.md) policy.
74- A [service config](service_config.md).
75
76The plugin API allows the resolvers to continuously watch an endpoint
77and return updated resolutions as needed.
78