0
# Load Balancing and Name Resolution
1
2
gRPC Core provides default implementations for load balancing and name resolution functionality. The pick-first load balancer is the default strategy, and DNS name resolution handles service discovery for gRPC clients.
3
4
## Capabilities
5
6
### Pick-First Load Balancer Provider
7
8
Default load balancer provider that implements the pick-first strategy.
9
10
```java { .api }
11
/**
12
* Provider for pick-first load balancing strategy
13
* Located: io.grpc.internal.PickFirstLoadBalancerProvider
14
*/
15
class PickFirstLoadBalancerProvider extends LoadBalancerProvider {
16
/**
17
* Checks if this provider is available for use
18
* @return true (always available)
19
*/
20
@Override
21
public boolean isAvailable() {
22
return true;
23
}
24
25
/**
26
* Gets the priority of this provider
27
* @return 5 (standard priority for default providers)
28
*/
29
@Override
30
public int getPriority() {
31
return 5;
32
}
33
34
/**
35
* Gets the policy name for this load balancer
36
* @return "pick_first" - used in service configuration
37
*/
38
@Override
39
public String getPolicyName() {
40
return "pick_first";
41
}
42
43
/**
44
* Creates a new pick-first load balancer instance
45
* @param helper Helper providing access to channel functionality
46
* @return PickFirstLoadBalancer instance
47
*/
48
@Override
49
public LoadBalancer newLoadBalancer(LoadBalancer.Helper helper) {
50
return new PickFirstLoadBalancer(helper);
51
}
52
53
/**
54
* Parses load balancing policy configuration
55
* @param rawLoadBalancingPolicyConfig Raw configuration map
56
* @return ConfigOrError with parsed configuration or error
57
*/
58
@Override
59
public ConfigOrError parseLoadBalancingPolicyConfig(
60
Map<String, ?> rawLoadBalancingPolicyConfig
61
) {
62
return ConfigOrError.fromConfig(new PickFirstConfig());
63
}
64
}
65
```
66
67
### Pick-First Load Balancer Implementation
68
69
Load balancer that connects to the first available server in the list.
70
71
```java { .api }
72
/**
73
* Pick-first load balancing implementation
74
* Located: io.grpc.internal.PickFirstLoadBalancer
75
*/
76
class PickFirstLoadBalancer extends LoadBalancer {
77
/**
78
* Creates a new pick-first load balancer
79
* @param helper Helper for accessing channel functionality
80
*/
81
public PickFirstLoadBalancer(Helper helper);
82
83
/**
84
* Handles resolution result from name resolver
85
* @param resolvedAddresses Result containing server addresses
86
*/
87
@Override
88
public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses);
89
90
/**
91
* Handles name resolution errors
92
* @param error Status indicating the resolution error
93
*/
94
@Override
95
public void handleNameResolutionError(Status error);
96
97
/**
98
* Handles subchannel state changes
99
* @param subchannel The subchannel that changed state
100
* @param stateInfo New state information
101
*/
102
@Override
103
public void handleSubchannelState(Subchannel subchannel, ConnectivityStateInfo stateInfo);
104
105
/**
106
* Initiates shutdown of the load balancer
107
*/
108
@Override
109
public void shutdown();
110
111
/**
112
* Requests connection to be established
113
*/
114
@Override
115
public void requestConnection();
116
}
117
```
118
119
### DNS Name Resolver Provider
120
121
Provider for DNS-based name resolution functionality.
122
123
```java { .api }
124
/**
125
* Provider for DNS-based name resolution
126
* Located: io.grpc.internal.DnsNameResolverProvider
127
*/
128
class DnsNameResolverProvider extends NameResolverProvider {
129
/**
130
* Checks if DNS resolution is available
131
* @return true if DNS resolution can be used
132
*/
133
@Override
134
public boolean isAvailable() {
135
return true;
136
}
137
138
/**
139
* Gets the priority of this provider
140
* @return 5 (standard priority for default providers)
141
*/
142
@Override
143
public int getPriority() {
144
return 5;
145
}
146
147
/**
148
* Gets the default URI scheme handled by this provider
149
* @return "dns" - the scheme for DNS-based name resolution
150
*/
151
@Override
152
public String getDefaultScheme() {
153
return "dns";
154
}
155
156
/**
157
* Creates a new DNS name resolver for the given target URI
158
* @param targetUri The target URI to resolve (e.g., dns:///example.com:443)
159
* @param args Arguments containing channel configuration
160
* @return DnsNameResolver instance or null if URI is not supported
161
*/
162
@Override
163
public NameResolver newNameResolver(URI targetUri, NameResolver.Args args) {
164
if (!"dns".equals(targetUri.getScheme())) {
165
return null;
166
}
167
return new DnsNameResolver(targetUri, args);
168
}
169
}
170
```
171
172
### DNS Name Resolver Implementation
173
174
Resolves DNS names to IP addresses for gRPC connections.
175
176
```java { .api }
177
/**
178
* DNS name resolution implementation
179
* Located: io.grpc.internal.DnsNameResolver
180
*/
181
class DnsNameResolver extends NameResolver {
182
/**
183
* Creates a new DNS name resolver
184
* @param targetUri URI to resolve
185
* @param args Resolution arguments
186
*/
187
public DnsNameResolver(URI targetUri, Args args);
188
189
/**
190
* Gets the service authority for this resolver
191
* @return Service authority string
192
*/
193
@Override
194
public String getServiceAuthority();
195
196
/**
197
* Starts name resolution with the given listener
198
* @param listener Listener to receive resolution results
199
*/
200
@Override
201
public void start(Listener2 listener);
202
203
/**
204
* Shuts down the name resolver
205
*/
206
@Override
207
public void shutdown();
208
209
/**
210
* Refreshes the name resolution
211
*/
212
@Override
213
public void refresh();
214
}
215
```
216
217
## Load Balancing Strategies
218
219
### Pick-First Strategy
220
221
The pick-first load balancing strategy connects to the first available server:
222
223
1. **Address Ordering**: Servers are tried in the order provided by name resolution
224
2. **Connection Attempt**: Attempts connection to the first server in the list
225
3. **Fallback**: If connection fails, tries the next server in the list
226
4. **Sticky Connection**: Once connected, all RPCs use the same connection
227
5. **Reconnection**: If connection is lost, restarts the process from the beginning
228
229
**Configuration:**
230
231
```json
232
{
233
"loadBalancingPolicy": "pick_first"
234
}
235
```
236
237
**Usage Example:**
238
239
```java
240
import io.grpc.ManagedChannel;
241
import io.grpc.ManagedChannelBuilder;
242
243
// Pick-first is the default load balancing policy
244
ManagedChannel channel = ManagedChannelBuilder
245
.forTarget("dns:///example.com:443")
246
.build();
247
248
// Explicitly specify pick-first policy
249
ManagedChannel channel2 = ManagedChannelBuilder
250
.forTarget("dns:///example.com:443")
251
.defaultLoadBalancingPolicy("pick_first")
252
.build();
253
```
254
255
## Name Resolution
256
257
### DNS Resolution Process
258
259
DNS name resolution converts domain names to IP addresses:
260
261
1. **URI Parsing**: Extracts hostname and port from target URI
262
2. **DNS Query**: Performs DNS lookup to resolve hostname to IP addresses
263
3. **Address List**: Returns list of resolved IP addresses with ports
264
4. **Updates**: Periodically refreshes DNS resolution to handle changes
265
5. **Error Handling**: Reports resolution failures to the load balancer
266
267
### Supported URI Formats
268
269
```java
270
// DNS scheme with explicit host and port
271
"dns:///example.com:443"
272
273
// DNS scheme with default port
274
"dns:///example.com"
275
276
// Implicit DNS (default scheme)
277
"example.com:443"
278
279
// IPv4 address with port
280
"192.168.1.100:443"
281
282
// IPv6 address with port
283
"[2001:db8::1]:443"
284
```
285
286
### DNS Configuration
287
288
```java
289
import io.grpc.NameResolverRegistry;
290
import io.grpc.internal.DnsNameResolverProvider;
291
292
// DNS resolver is automatically registered via SPI
293
// Manual registration (not typically needed):
294
NameResolverRegistry.getDefaultRegistry()
295
.register(new DnsNameResolverProvider());
296
```
297
298
## Advanced Load Balancing
299
300
### Custom Load Balancer Integration
301
302
While pick-first is the default, gRPC Core's architecture supports custom load balancers:
303
304
```java
305
// Custom load balancer provider
306
public class CustomLoadBalancerProvider extends LoadBalancerProvider {
307
@Override
308
public boolean isAvailable() {
309
return true;
310
}
311
312
@Override
313
public int getPriority() {
314
return 10; // Higher priority than default
315
}
316
317
@Override
318
public String getPolicyName() {
319
return "custom_policy";
320
}
321
322
@Override
323
public LoadBalancer newLoadBalancer(Helper helper) {
324
return new CustomLoadBalancer(helper);
325
}
326
}
327
```
328
329
### Service Configuration
330
331
Load balancing can be configured via service configuration:
332
333
```json
334
{
335
"loadBalancingConfig": [
336
{
337
"pick_first": {}
338
}
339
],
340
"methodConfig": [
341
{
342
"name": [
343
{
344
"service": "example.Service"
345
}
346
],
347
"timeout": "30s"
348
}
349
]
350
}
351
```
352
353
## Error Handling and Resilience
354
355
### Load Balancer Error Handling
356
357
- **Connection Failures**: Load balancer tries alternative servers
358
- **Service Unavailable**: Reports appropriate status to clients
359
- **Network Partitions**: Handles temporary connectivity issues
360
- **Address Updates**: Adapts to changes in server addresses
361
362
### Name Resolution Error Handling
363
364
- **DNS Failures**: Reports resolution errors to load balancer
365
- **Network Issues**: Retries DNS queries with exponential backoff
366
- **Invalid Addresses**: Filters out unreachable or invalid addresses
367
- **Cache Management**: Uses cached results when resolution fails
368
369
**Example Error Handling:**
370
371
```java
372
// Load balancer handles resolution errors
373
@Override
374
public void handleNameResolutionError(Status error) {
375
if (subchannel != null) {
376
subchannel.shutdown();
377
subchannel = null;
378
}
379
380
// Report error to channel
381
helper.updateBalancingState(TRANSIENT_FAILURE,
382
new ErrorPicker(error));
383
}
384
```
385
386
## Performance Considerations
387
388
### Load Balancing Performance
389
390
- **Connection Reuse**: Pick-first maintains single connection per target
391
- **Lazy Connection**: Connections established only when needed
392
- **Health Checking**: Optional health checking for server availability
393
- **Flow Control**: Respects gRPC flow control mechanisms
394
395
### Name Resolution Performance
396
397
- **DNS Caching**: Results cached to reduce DNS queries
398
- **Resolution Frequency**: Configurable refresh intervals
399
- **Parallel Resolution**: Multiple addresses resolved concurrently
400
- **IPv6 Support**: Handles both IPv4 and IPv6 addresses efficiently