Explicit client versioning

[andrewjstone]

Hi all,

I can't find any precise documentation around compatibility of v3 clients with given versions and v3 servers with given versions.

While it may be possible to take entire Etcd clusters down and replace them at once, doing that with a larger set of clients is somewhat unrealistic.

Are there any backwards or forwards compatibility guarantees across the client API? For example:

• Backwards compatibility: Will any new version of a v3 client work with any older v3 version of Etcd? For instance, will existing grpc/protobuf messages only add optional fields, such that old messages are still understood, and those fields can be ignored? Will responses change across minor versions? In essence what guarantees can be provided if any? This allows upgrading clients first and then Etcd.
• Forwards compatibility: Will any old version of a v3 client work with any new v3 version of Etcd? For instance, will new versions of Etcd be able to interpret old protobuf client messages with missing optional fields correctly? This allows Etcd to be updated first and then clients to be updated individually over time.

It would be great if you could provide some information about how the Etcd team plans for such scenarios and how you attempt to maintain compatibility, if at all. If not, that should be documented as well.

Thanks!

[jingyih]

cc @jpbetz

[jhzhu89]

Is there any documents about Backwards/Forwards compatibility?
I want to upgrade etcd server from v3.3.15 to v3.4.0, do I have to update the client code? Or the old version client still works?

[jfbai]

Is there any update? we have same consideration.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[andrewjstone]

Update to please the stalebot. This is still important given Etcd's standing in the ecosystem.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 21 days if no further activity occurs. Thank you for your contributions.

[ptabor]

I think its very important.

API Changes since 3.1.0

I did some reaserch about API changes since v3.1.0 (there seems to be a lot of change since v3.0.0:)
(mostly based on git diff v3.1.0 ./etcdserver/etcdserverpb/rpc.proto):

and identified following differences:

• REST URLs evolution: (/v3{alpha,beta,}) but that does not have impact on gRPC layer compatibility.
• etcd quorum management:
  • learner support: e.g. MemberPromote
  • MoveLeader
  • Member related methods return list of members in response
• StatusResponse expanded (dbSizeInUse, errors, raftAppliedIndex)
• HashKV verb added
• RangeRequest expanded with support of { ignore_value, ignore_lease }
• RequestOp{TxnRequest} <- nested transactions support (transaction in transaction)
• WatchCreateRequest {watch_id, fragment}
• AuthUserAddRequest (authpb.UserAddOptions options)
• LeaseLeases added -> ListLeases ?
• LeaseCheckpointRequest -> seems abandoned message (not used in any verb)

All changes were RPC compatible.

Proposal

IMHO etcd client v3.x.y should:

1. declare being forward compatible with all >=v3.x.0 releases of etcd server

   • This allows us safely update etcd servers ahead of any application.

2. declare being backward compatible with any >3.1.0+ release of etcd server, with the regards to limited feature set.

   • e.g. MoveLeader was added in 3.3.0, so should be explicitly documented as available since >=3.3.0 in proto and client lib.
   • etcdclient 3.3.0 can be used with >etcd-3.1 server as long as the methods like MoveLeader are not being called.

3. Explicitly document new features added in consective etcd clients (and public API).

4. Move etcd client to a separate go module, such that dependency set is minimal when importing.

[wenjiaswe]

cc @xiang90 @jingyih @gyuho

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 21 days if no further activity occurs. Thank you for your contributions.

[ptabor]

not-stale

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 21 days if no further activity occurs. Thank you for your contributions.

[andrewjstone]

:keep-alive

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 21 days if no further activity occurs. Thank you for your contributions.

[andrewjstone]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 21 days if no further activity occurs. Thank you for your contributions.

Can a human please just explicitly say that this documentation is not going to get written or that it's planned for the future? Marking valid issues stale by bot is not productive.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 21 days if no further activity occurs. Thank you for your contributions.

[andrewjstone]

:keep-alive

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 21 days if no further activity occurs. Thank you for your contributions.

[andrewjstone]

Holla

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 21 days if no further activity occurs. Thank you for your contributions.

[andrewjstone]

bing

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 21 days if no further activity occurs. Thank you for your contributions.

[andrewjstone]

X

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed after 21 days if no further activity occurs. Thank you for your contributions.

[andrewjstone]

X