allocationOverflow documentation issue

[joeholley]

https://agones.dev/site/docs/reference/fleet/ is the page this issue refers to.

The fleet spec example says this:

  # [Stage:Alpha]
  # [FeatureFlag:FleetAllocationOverflow]
  # Labels and/or Annotations to apply to overflowing GameServers when the number of Allocated
  # GameServers is more than the desired replicas on the underlying GameServerSet 

But the description below it says:

allocationOverflow (Alpha, requires FleetAllocationOverflow flag) The labels and/or Annotations to apply to GameServers when the number of Allocated GameServers drops below the desired replicas on the underlying GameServerSet.

So, the fleet spec says the labels/annotations are applied when there are more allocated gameservers than the number of desired replicas, but the documentation description says the labels/annotations are applied when there are fewer? Unless I'm misreading this.

Also, the spec seems to indicate the labels/annotations are applied only to some gameservers (those who are 'overflowing'), while the description seems to imply it will be applied to all servers. I think the latter is true, unless you're flagging specific gameservers as 'overflowing' the desired number of replicas - and if you are, the docs should explain the criteria for which gameservers are chosen to get this state and which aren't (I read through #2682 and didn't see discussion of this; I suspect it's not specified so defaulting to the order k8s returns gameservers in when queried which would equate to random, but whatever it is should be documented).

[markmandel]

Good catch - this is the canonical reference:
https://agones.dev/site/docs/guides/fleet-updates/#notifying-gameservers-on-fleet-updatedownscale

So this section is wrong:

allocationOverflow (Alpha, requires FleetAllocationOverflow flag) The labels and/or Annotations to apply to GameServers when the number of Allocated GameServers drops below the desired replicas on the underlying GameServerSet.

It should be more not less.

And you are also correct in that only the some (the difference between the number allocated - desired) are marked as "overflow".

As per:

agones/pkg/gameserversets/allocation_overflow.go

Lines 148 to 149 in 61056b0

	rest = SortGameServersByStrategy(gsSet.Spec.Scheduling, rest, c.counter.Counts(), gsSet.Spec.Priorities)
	rest = rest[:(overflow - matches)]

We do also sort based on the Strategy defined by the Fleet - so either Packed or Distributed. This is also good to document somewhere.

[markmandel]

@Kalaiselvi84 or @ashutosji - are one of you able take this on please at some point?

[Kalaiselvi84]

I will take on this work.