In-place Agones Upgrades: SDK Compatability

[zmerlynn]

[!NOTE] Milestone of #3766, which we are seeking feedback on. We will move forward with pieces that seem non-contentious, though.

SDK Compatibility

This milestone satisfies the requirements in "SDK proto" and "Client SDKs" of #3766 - in particular, see the "SDK Compatibility Contract" mentioned there.

As of now, we have APIs in Stable and Alpha, but no Beta SDK protos - in fact, there is no Beta surface in the Client SDKs because Player Tracking, the first Alpha Client SDK feature, never graduated off Alpha. The next Client SDK feature to graduate is Counts & Lists - at which time, we will need to create a Beta Client SDK surface across the SDKs. This will be handled as part of Counts & Lists graduation, not as part of this project.

Because of this, there is no need to do any coding work towards Client SDK Compatibility if we accept the requirements in #3766.

Use Patch vs Update #

However, there is still a gotcha in how the sdk-server works today: We need to improve how sdk-server handles fields that are known by the remainder of the Agones Control Plane but are unknown by the sdk-server, which may happen in the event of newly lit feature gate paths. In particular, updates like this:

https://github.com/googleforgames/agones/blob/05d8232c937d756d9b8e848915e04e4159924b7b/pkg/sdkserver/sdkserver.go#L472

are likely to wipe out new API fields. We can use Patch() instead, by using optimistic locking in patch similar to contoller-runtime.

---

To close this issue requires:

• [ ] Documentation:
  • Document SDK proto compatibility guarantees and deprecation policies.
  • Keep a chart of each API and its stability level and different versions so users can easily reference to see if there are changes. The chart can be started as of Agones 1.40 (we don't need to back date it, we haven't provided a guarantee in the past.)
• [ ] Move sdk-server to Patch() instead of Update()