Documentation: FleetAutoScaler BufferSize could contain both Ready and Reserved GameServers

[aLekSer]

Current documentation of FleetAutoscalers is a bit confusing:
BufferSize - Size of a buffer of "ready" game server instances
But if some gameservers amount is Reserved this statement is not true.

What happened:
Create a simple-udp fleet and a FleetAutoScaler with BufferSize = 1, MinReplicas = 1, wait when one GS become Ready
Move it to a Reserved state (we should update simple-udp to pass duration for a E2E test and this case)
Should have one more GS in Ready state in a minute time as per Current FAS Documentation.

What you expected to happen:
I expect to see one Reserved GS and one Ready as per Buffer Policy Documentation.

How to reproduce it (as minimally and precisely as possible):
Get IP and port of Ready GS.

 for i in {0..20}; do echo RESERVE | nc -w 1  -u 35.230.45.65   7429; sleep 10 ;  done 

On a different terminal run after 1 minute:

kubectl get gs
NAME                     STATE   ADDRESS        PORT   NODE                                     AGE
simple-udp-9hxbj-7rjvc   Reserved    35.230.45.65   7429   gke-test-cluster-default-dc619e10-mdcx   46m

Anything else we need to know?:

kubectl describe fas                                                                                                                                                
Name:         simple-udp-autoscaler
Spec:
  Fleet Name:  simple-udp
  Policy:
    Buffer:
      Buffer Size:   1
      Max Replicas:  2
      Min Replicas:  0

How to fix:
Documentation should be updated.
simple-udp and simple-tcp should have a duration parameter RESERVE 300 - 300 seconds to simulate different scenarios.

Environment:

• Agones version: 1.1
• Kubernetes version (use kubectl version): 1.13
• Cloud provider or hardware configuration: GKE
• Install method (yaml/helm): helm
• Troubleshooting guide log(s):
• Others:

[aLekSer]

Well there is a comment in yaml and source code, which is not documented on agones.dev -> fleetautoscalers page:

Reserved instances won't be deleted on scale down, but won't cause an autoscaler to scale up.

Thus this ticket might be closed as work as designed or we could revise that behaviour.

To sum things up, could we introduce such behaviour when Reserved Replicas trigger scale up? Otherwise in some cases there would be no buffer actually would and no Ready gameservers would exist when all buffer would be Reserved. Resulting in situation when no Ready Gameservers would be created until reserve times out.

[aLekSer]

I opened this bug, because in FleetAutoScaler description we have an inconsistency with SDK Reserve:

    buffer:
      # Size of a buffer of "ready" game server instances

Should be either size of ready + reserved or we should change reserve() functionality and docs here for SDK.
Other flexible option would be to make this optional in FleetAutoScaler CRD: count Reserved GS (with Ready as Buffer) or not.