Document multiple EquivalentAddressGroups vs multiple SocketAddresses in NameResolver

[ST-DDT]

Currently the javadocs don't state when to use multiple EquivalentAddressGroups or multiple SocketAddresses in a single EquivalentAddressGroup.

io.grpc.EquivalentAddressGroup

A group of SocketAddresses that are considered equivalent when channel makes connections.

Usually the addresses are addresses resolved from the same host name, and connecting to any of them is equally sufficient. They do have order. An address appears earlier on the list is likely to be tried earlier.

io.grpc.NameResolver.Listener.onAddresses(List, Attributes)

Handles updates on resolved addresses and attributes.

Implementations will not modify the given servers.

Parameters:

• servers the resolved server addresses. An empty list will trigger onError
• attributes extra information from naming system.

• Do I use multiple SocketAddresses if there are multiple paths to one and the same server, such as 10.1.2.3 , 127.0.0.1 or ::1? (Would that ever happen?)
• Or do I always create new EquivalentAddressGroups for each address? (But then why am I able to list more addresses?)

It is also unsure when (and for what) the attributes on the single EquivalentAddressGroup is used and when (and for what) the attributes from the onAddresses call is used, and finally whether they are merged somehow or not.

Affects

• grpc-core

Related

• Tracking Issue for NameResolution being Experimental. #1770
• Determine final NameResolver to LoadBalancer communication #4302
• Document expectations about NameResolver SocketAddresses #5213

[ejona86]

Basically, use multiple EquivalentAddressGroups (EAG) if you want the Round Robin load balancer (and similar) to treat each address as a separate backend.

It's actually a debate now whether EAG needs to contain a list of addresses. We added the support so that users could use Round Robin LB while also migrating from IPv4 to IPv6. So each server would have two (or more! because IPv6 is like that) addresses, one for IPv4 and one for IPv6. But since all the addresses are in a single EAG, we'll still only make one connection. That way you can roll out IPv6 without having IPv6-enabled backends receiving 2x the traffic.

[alxn]

@ejona86 oh wow. suddenly EAG's make a lot of sense from a dual-stack thought. Thanks for the explanation!