To be Reviewed By: 2021.02.02

Authors: Alberto Gomez

Status: Draft | Discussion | Active | Dropped | Superseded

Superseded by: N/A

Related: N/A

Problem

Apache Geode clients are not allowed to connect to servers running a version of Geode older than the one of the clients.

This is guaranteed at client connection during the handshake between clients and servers in which clients send their Geode version to the server. If the version sent by the client is newer than the one of the server, the connection is rejected. (As a side note, this is valid for Java clients but not exactly for clients using the C++ native client API.)

This implies that during a rolling upgrade of Geode, clients must be the last components to be upgraded as it is stated in the Geode documentation on Backward compatibility and Rolling Upgrade: "clients using the new version will not be used until the system is fully rolled to the new version."

While this assumption is valid for most scenarios and it facilitates the implementation of backward compatibility between clients and servers, there are scenarios in which it is required to be able to upgrade the clients before the servers during a rolling upgrade (for example in Kubernetes deployments where clients, locators and servers are packaged in the same Helm chart).

Anti-Goals

This proposal does not intend to support the total backward compatibility of Geode clients with any Geode server version.

Solution

A new configuration parameter may be added to the client so that, if used, the client would send a different Geode version during the handshake, in order to be able to communicate with servers in an older version with which it is compatible.

Two alternatives for this new configuration parameter are proposed:

  • A new optional numeric System Property could be used by the Geode Java client to set the version used by it in the handshake with a server. With this property, a Geode Java client in version X could advertise itself towards a server, during the handshake, as being in version Y (Y being older than X) to allow to connect to a server in version Y or older.

In case a client version is incompatible with an older server version, the client should reject the setting of that version in the new System Property proposed.

For example, in order for a client using version 1.15 of the Geode Java API to connect to a server in version 1.14, the client would be required to use the following system property:

-Dgemfire.forced-client-version=125
  • A new optional boolean System Property could be used by the Geode Java client so that, if used, the client would send in the handshake the oldest Geode server version compatible with this client.

For example, in order for a client using version 1.15 of the Geode Java API to connect to a server in version 1.12, the client would be required to use the following system property:

-Dgemfire.backward-compatible-client

In this case, assuming that the oldest Geode server compatible with a client in version 1.15 is 1.9.0, the client will send in the handshake the 1.9.0 version. Consequently, a client using version 1.15 would not be able to communicate with a server in version 1.8 or older even if it used this parameter.

The use of any of these parameters, by itself, will not guarantee the compatibility between the client and the server. Nevertheless, incompatibilities (specially between minor releases) are very rare so, in the general case, no changes will be required in the client to support backward compatibility.

In order to have certainty about the compatibility between versions, test cases would be added to verify the correct behavior of newer clients using this new parameter connecting to older servers or the incompatibility between clients and servers.

Optionally, it could be desirable to provide a compatibility table between Geode client versions and Geode server versions just as other similar systems do (for example Hazelcast or Cassandra) in the official Apache Geode documentation.

Changes and Additions to Public Interfaces

A new system property will be added to Geode (-Dgemfire.forced-client-version or -Dgemfire.backward-compatible-client depending on the option selected) that will allow to change the Geode version to be sent by the client to the server during the handshake.

Performance Impact

-

Backwards Compatibility and Upgrade Path

The proposed System property is optional. If the property is not set, clients will not change their behavior.

Prior Art

With the current restriction that clients in a newer version of Geode cannot connect to Geode servers in an older version, any rolling upgrade that cannot guarantee such order of upgrade between clients and servers will fail. As a result, in such an scenario, a rolling upgrade would not be possible and other upgrade alternatives more complex or with downtime might need to be explored.

FAQ

Answers to questions you’ve commonly been asked after requesting comments for this proposal.

Errata

What are minor adjustments that had to be made to the proposal since it was approved?

  • No labels

1 Comment

  1. Alberto Gomez

    RFC not implemented. The benefits of the solution are not so clear and the use case for which it was proposed (deployments that cannot control the order in which Geode clients and servers are upgraded) might not be so frequent or might have other ways to tackle the problem in an easier way than in Geode.

    Also, depending on the changes each release brings, it could be that the parameter is not useful if the release contains changes that make the client backward incompatible with servers. Creating test cases to verify if the compatibility is broken would require a significant amount of effort.

    A more complete solution that includes supporting backward compatibility in clients would require a big amount of effort, would add extra complexity to the code and as commented above, would not be worth for supporting a quite unprobable use case.