• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Service Config in gRPC
2======================
3
4# Objective
5
6The service config is a mechanism that allows service owners to publish
7parameters to be automatically used by all clients of their service.
8
9# Format
10
11The format of the service config is defined by the
12[`grpc.service_config.ServiceConfig` protocol buffer
13message](https://github.com/grpc/grpc-proto/blob/master/grpc/service_config/service_config.proto).
14Note that new fields may be added in the future as new functionality is
15introduced.
16
17# Architecture
18
19A service config is associated with a server name.  The [name
20resolver](naming.md) plugin, when asked to resolve a particular server
21name, will return both the resolved addresses and the service config.
22
23The name resolver returns the service config to the gRPC client in JSON form.
24Individual resolver implementations determine where and in what format the
25service config is stored.  If the resolver implemention obtains the
26service config in protobuf form, it must convert it to JSON using the
27normal [protobuf to JSON translation
28rules](https://developers.google.com/protocol-buffers/docs/proto3#json).
29Alternatively, a resolver implementation may obtain the service config
30already in JSON form, in which case it may return it directly.
31
32For details of how the DNS resolver plugin supports service configs, see
33[gRFC A2: Service Config via
34DNS](https://github.com/grpc/proposal/blob/master/A2-service-configs-in-dns.md).
35
36# Example
37
38Here is an example service config in protobuf form:
39
40```
41{
42  // Use round_robin LB policy.
43  load_balancing_config: { round_robin: {} }
44  // This method config applies to method "foo/bar" and to all methods
45  // of service "baz".
46  method_config: {
47    name: {
48      service: "foo"
49      method: "bar"
50    }
51    name: {
52      service: "baz"
53    }
54    // Default timeout for matching methods.
55    timeout: {
56      seconds: 1
57      nanos: 1
58    }
59  }
60}
61```
62
63Here is the same example service config in JSON form:
64
65```
66{
67  "loadBalancingConfig": [ { "round_robin": {} } ],
68  "methodConfig": [
69    {
70      "name": [
71        { "service": "foo", "method": "bar" },
72        { "service": "baz" }
73      ],
74      "timeout": "1.0000000001s"
75    }
76  ]
77}
78```
79
80# APIs
81
82The service config is used in the following APIs:
83
84- In the resolver API, used by resolver plugins to return the service
85  config to the gRPC client.
86- In the gRPC client API, where users can query the channel to obtain
87  the service config associated with the channel (for debugging
88  purposes).
89- In the gRPC client API, where users can set the service config
90  explicitly.  This can be used to set the config in unit tests.  It can
91  also be used to set the default config that will be used if the
92  resolver plugin does not return a service config.
93