Upcoming experimental Balancer API changes

[easwars]

The balancer API uses important pieces of functionality provided by gRPC via the following interfaces: balancer.ClientConn and balancer.SubConn.

While the balancer.ClientConn interface provides the functionality to create and delete a balancer.SubConn, the functionality to modify the addresses of an existing balancer.SubConn is provided by the balancer.SubConn interface itself. This asymmetry create an unnecessary pain-point for LB policy implementations in a setup with a tree of LB policies.

The proposed API change here is as follows:

• Extend the balancer.ClientConn interface by providing a way to update addresses of an existing balancer.SubConn.

	// UpdateAddresses updates the addresses used in the passed in SubConn.
	// gRPC checks if the currently connected address is still in the new list.
	// If so, the connection will be kept. Else, the connection will be
	// gracefully closed, and a new connection will be created.
	//
	// This will trigger a state transition for the SubConn.
	UpdateAddresses(SubConn, []resolver.Address)

• Remove the UpdateAddresses method on the balancer.SubConn interface, which would then provide a single Connect() method.

The plan would be as follows:

• Add UpdateAddresses() to balancer.ClientConn as part of the 1.37.x release.
• Remove UpdateAddresses() from balancer.SubConn in a future release. Maybe 1.38.x or a subsequent one.
  • We will wait 2 release. So UpdateAddresses() will be removed in v1.39.x

While these changes are not strictly following semantic versioning or the Go compatibility promise, they are in accordance with our versioning policy as the changes are limited to experimental APIs.

[easwars]

@dfawley @menghanl

[UnderTreeTech]

still remember the pain of etcd. Hope this change would not cause another disaster.

[dfawley]

To align better with gRPC-Java's LB policy API, and to simplify the effort required to implement LB policies in a hierarchy, we will be making these changes in the opposite direction from what was originally proposed in this issue.

Namely:

• Remove balancer.ClientConn.UpdateAddresses and un-deprecate balancer.SubConn.UpdateAddresses as its replacement
• Remove balancer.ClientConn.RemoveSubConn and add balancer.SubConn.Shutdown as its replacement
• Add balancer.SubConn.SetStateListener (exact name TBD) to enable subscribing to subconn state changes via callbacks

still remember the pain of etcd. Hope this change would not cause another disaster.

I hope so too. The package is and always has been clearly labeled as experimental, meaning no backward compatibility guarantees are promised, but big scary warnings apparently don't prevent library developers from using it anyway.

[patrickfreed]

Is there a projected timeline for when the balancer package will become stable? Or at least a subset of its API?

[dfawley]

Unfortunately not. The Java API is also still experimental, and C++ still doesn't have a public API for this at all. We would want to do this all together so we can be sure we have a consistent set of features available (or at least possible) for our users. The changes we're proposing here will bring us more in line with Java, so that should help to make this happen sooner.

[dfawley]

Replacing this notice with #6472 to encompass all the new things required by gRFC A61 as well.