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`, `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 44- `unix-abstract:abstract_path` -- Unix domain socket in abstract namespace (Unix systems only) 45 - `abstract_path` indicates a name in the abstract namespace. 46 - The name has no connection with filesystem pathnames. 47 - No permissions will apply to the socket - any process/user may access the socket. 48 - The underlying implementation of Abstract sockets uses a null byte ('\0') 49 as the first character; the implementation will prepend this null. Do not include 50 the null in `abstract_path`. 51 52- `vsock:cid:port` -- VSOCK (Linux systems only) 53 - `cid` is 32-bit Context Identifier (CID). It indicates the source or 54 destination, which is either a virtual machine or the host. 55 - `port` is a 32-bit port number. It differentiates between multiple 56 services running on a single machine. 57 58The following schemes are supported by the gRPC C-core implementation, 59but may not be supported in other languages: 60 61- `ipv4:address[:port][,address[:port],...]` -- IPv4 addresses 62 - Can specify multiple comma-delimited addresses of the form `address[:port]`: 63 - `address` is the IPv4 address to use. 64 - `port` is the port to use. If not specified, 443 is used. 65 66- `ipv6:address[:port][,address[:port],...]` -- IPv6 addresses 67 - Can specify multiple comma-delimited addresses of the form `address[:port]`: 68 - `address` is the IPv6 address to use. To use with a `port` the `address` 69 must enclosed in literal square brackets (`[` and `]`). Example: 70 `ipv6:[2607:f8b0:400e:c00::ef]:443` or `ipv6:[::]:1234` 71 - `port` is the port to use. If not specified, 443 is used. 72 73In the future, additional schemes such as `etcd` could be added. 74 75### Resolver Plugins 76 77The gRPC client library will use the specified scheme to pick the right 78resolver plugin and pass it the fully qualified name string. 79 80Resolvers should be able to contact the authority and get a resolution 81that they return back to the gRPC client library. The returned contents 82include: 83 84- A list of resolved addresses (both IP address and port). Each address 85 may have a set of arbitrary attributes (key/value pairs) associated with 86 it, which can be used to communicate information from the resolver to the 87 [load balancing](load-balancing.md) policy. 88- A [service config](service_config.md). 89 90The plugin API allows the resolvers to continuously watch an endpoint 91and return updated resolutions as needed. 92