More Local Dev Server Annotations

[CauhxMilloy]

Is your feature request related to a problem? Please describe. Not really a "problem", just some quality of life improvements. This is a follow up from some discussion on https://github.com/googleforgames/agones/pull/3252, specifically mentioned in https://github.com/googleforgames/agones/pull/3252#discussion_r1264965321.

This is in the interest of bridging the gap between locally debuggable GameServers and prod-like functionality. There are a few annotations that would be useful for adjusting state progression on dev game servers.

Describe the solution you'd like

Add agones.dev/auto-ready annotation support Currently, dev game servers will automatically always progress from the Creating state to the Ready state. While this functionality can be quite useful in many developer flows, it is unlike the flow taken in prod-like environments (shown in https://agones.dev/site/docs/reference/gameserver/#gameserver-state-diagram) where GameServers are instead set into the Scheduled state. Progression from this state is done by the game server binary calling SDK.Ready() which puts the GameServer into the RequestReady state, which is then further progressed by the controller into the Ready state.

The proposal for this is that the controller progresses dev game servers from Creating state into Scheduled instead of directly into Ready. The current functionality would be optionally preserved by adding the annotation agones.dev/auto-ready: true to the GameServer resource. The https://agones.dev/site/docs/guides/local-game-server/ documentation page could be updated to include this annotation.

This automatic state progression is handled here: https://github.com/googleforgames/agones/blob/8f575ed49c59e24a606e6a7562d87809e544701e/pkg/gameservers/controller.go#L526

Add agones.dev/recycle-gs annotation support Currently, when a dev game server gets SDK.Shutdown() called, the GameServer naturally goes into the Shutdown state; but the controller will always delete the GameServer resource just as it does for any GameServer resource in the Shutdown state.

This proposal is to support adding an annotation agones.dev/recycle-gs: true that, when set, will reset the GameServer resource back into the Scheduled state (or Ready with above mentioned agones.dev/auto-ready: true) instead of deleting the GameServer.

Admittedly, this is not exactly like what happens on prod-like environments -- instead its mimicking functionality that would be handled by a fleet (keeping up GameServer counts after they terminate).

This automatic state progression is handled here: https://github.com/googleforgames/agones/blob/8f575ed49c59e24a606e6a7562d87809e544701e/pkg/gameservers/controller.go#L898

Describe alternatives you've considered

agones.dev/auto-ready annotation alternatives The existing functionality performs the auto-ready logic. The current alternative would be to manually set the state via a REST call. However, doing so is slightly tedious and not representative of how prod-like environments would function. When performing GameServer allocation on a dev server, it would be nice to know that allocation can't happen until the binary itself has called SDK.Ready().

Another alternative considered as to keep the current default "auto-ready" behavior and the annotation would be to disable it. However, adding a negative logic agones.dev/dont-auto-ready seems a bit awkward (feel free to disagree).

agones.dev/recycle-gs annotation alternatives The current functionality requires re-running kubectl create -f ./my_dev_server.yml, which is not the worst but it is slightly tedious and just another step when trying to quickly iterate and dev (especially when prototyping). The suggested agones.dev/recycle-gs annotation is just a small QoL bit of automation.

Additional context Agones is cool. 😎 Thanks!

[markmandel]

agones.dev/recycle-gs annotation alternatives

I'll give another alternative to this annotation - that the local sidecar is the one that's responsible for recreating a new GameServer with the requisite annotations.

That would require restarting the local sidecar though to recreate the GameServer (I figure, it would create one on startup, probably with a requirement for agones.dev/dev-address to be set on the gameserver.yaml file passed in).

Then there is less manual management on the cluster of the GameServer resource. WDYT?

[CauhxMilloy]

Both seem useful. I don't see it as an "alternative" in the impl sense, but maybe in the flow sense. To say another way. I think that both would be useful to have, some devs might use either.

agones.dev/recycle-gs could be useful for some flows (that want a pre-made GameServer before the SDK Server starts, similar to prod), and having the SDK Server create the resource (e.g. with --file) would be useful for other flows ("I just want to get something started").

Though, I think there are a few open questions that I see with the latter.

• Does the SDK Server "own" the GameServer? It created it on start up via the --file flag + internal kubectl create call. Is it also responsible for tearing it down upon exit?
  • Does this inversion of lifetimes have any issues or present further inconsistencies when compared with prod flow?
• If a developer were to run the SDK Server in this manner, terminate it, then run it again, what would be the expected state/behavior?
  • Would it have kept the previous GameServer? Or would it be different (deleted then re-created)?
  • If it didn't re-create it, should running the SDK Server fail (due to internal kubectl create call failing)? This would then require the developer to make an extra kubectl delete call (which seems counter to this "just get stuff working" goal).
• Should it mimic kubectl apply instead?
  • Does it overwrite all fields?
  • Does it delete any fields (if some were applied during its previous usage, e.g. High Density GameServers)?
• Given that GAMESERVER_NAME/--gameserver-name needs to be passed into the SDK Server, what should happen when this differs from the name in the yml file?
• What sort of implications does this flow have on the expectations / learning of the developer when compared to Agones as a whole (discussed more below)?

I think the notion of having the SDK Server modify the GameServer resource in this way (on start up, not related to any SDK calls) brings up many questions and inconsistencies. If a developer learns of all these implications/quirks for this flow, have they internalized something representative of how Agones actually works? I'd argue no, instead they learned of some quirks in a dev flow process -- which doesn't offer better understanding of Agones. Truth be told, there will always be quirks in some API or some dev flow, but I think the goal of those quirks (why they were implemented the way that they were / what they are trying to move towards) is important and makes understanding them better for the whole system. Sure, those quirks can change, but hopefully cognitive overhead is minimized when the real understanding is "this is how prod / the larger system works; this is trying to be similar, though in this different context".

As such, I think that documenting agones.dev/recycle-gs as "mimicking functionality that would be handled by a fleet / deployment" gives insight into what the dev flow (quirky-ness and all) is and why the API takes the form it does (its goal is to be like prod-like things). agones.dev/recycle-gs interacts with the controller, which is the normal mechanism for handling GameServer state/lifetime. While it is a quirky way to set lifecycles for a dev flow, it's using the normal mechanisms.

It can definitely be said that some of the unflushed out issues mentioned above (like cleaning up dynamic fields, e.g. for HDGSs) also apply when just having a GameServer get "reset" by the controller when using agones.dev/recycle-gs. This is where I'd argue that the manual management of the GameServer (developer needs to create it with kubectl create or similar in the first place) offers this pseudo-disclaimer of expected self-management in a wider scope. When trying to make "oh it just works" (with abstraction) APIs, there's always a breaking point where the "just works" needs to be abandoned in favor of the thing the dev actually needs -- and that can feel like starting over when there were enough abstractions. Perhaps this could be an argument against agones.dev/recycle-gs or similar syntactic sugar -- or maybe agones.dev/recycle-gs is minimal enough.

Despite all the critique, none of this is to say that supporting --file on the SDK Server to create the GameServer shouldn't be done, as I could see it being a nice thing for some minimal effort dev flows. But I think that agones.dev/recycle-gs still has a number of pluses over that.

Obviously, this is just my sense of things. Feel free to disagree and/or discuss more.

[github-actions[bot]]

'This issue is marked as Stale due to inactivity for more than 30 days. To avoid being marked as 'stale' please add 'awaiting-maintainer' label or add a comment. Thank you for your contributions '