Fix Reference docs and sync it with Examples dir

There was a discrepancy between website agones.dev and Examples dir
yaml files content.
For googleforgames#969.

site/content/en/docs/Examples/_index.md

@@ -9,7 +9,9 @@ weight: 120
 
 These are full examples for each of the resource types of Agones
 
+{{% feature expiryVersion="0.12.0" %}}
 > These examples are for reference only. They are not backed by working images.
+{{% /feature %}}
 
 - {{< ghlink href="examples/gameserver.yaml" >}}Full GameServer Configuration{{< /ghlink >}}
 - {{< ghlink href="examples/fleet.yaml" >}}Full Fleet Configuration{{< /ghlink >}}

site/content/en/docs/Reference/fleet.md

@@ -50,19 +50,39 @@ spec:
 apiVersion: "agones.dev/v1"
 kind: Fleet
 metadata:
+  # Fleet Metadata
+  # https://v1-9.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.9/#objectmeta-v1-meta
   name: fleet-example
 spec:
+  # the number of GameServers to keep Ready or Allocated in this Fleet
   replicas: 2
+  # defines how GameServers are organised across the cluster.
+  # Options include:
+  # "Packed" (default) is aimed at dynamic Kubernetes clusters, such as cloud providers, wherein we want to bin pack
+  # resources
+  # "Distributed" is aimed at static Kubernetes clusters, wherein we want to distribute resources across the entire
+  # cluster
   scheduling: Packed
+  # a GameServer template - see:
+  # https://agones.dev/site/docs/reference/gameserver/ for all the options
   strategy:
+    # The replacement strategy for when the GameServer template is changed. Default option is "RollingUpdate",
+    # "RollingUpdate" will increment by maxSurge value on each iteration, while decrementing by maxUnavailable on each
+    # iteration, until all GameServers have been switched from one version to another.
+    # "Recreate" terminates all non-allocated GameServers, and starts up a new set with the new details to replace them.
     type: RollingUpdate
+    # Only relevant when `type: RollingUpdate`
     rollingUpdate:
+      # the amount to increment the new GameServers by. Defaults to 25%
       maxSurge: 25%
-      maxUnavailable: 25%  
+      # the amount to decrements GameServers by. Defaults to 25%
+      maxUnavailable: 25%
   template:
+    # GameServer metadata
     metadata:
       labels:
         foo: bar
+    # GameServer specification
     spec:
       ports:
       - name: default
@@ -71,11 +91,12 @@ spec:
       health:
         initialDelaySeconds: 30
         periodSeconds: 60
+      # The GameServer's Pod template
       template:
         spec:
           containers:
-          - name: example-server
-            image: gcr.io/agones/test-server:0.1
+          - name: simple-udp
+            image: gcr.io/agones-images/udp-server:0.14
 ```
 {{% /feature %}}
 
@@ -129,7 +150,6 @@ A `FleetAllocation` is used to allocate a `GameServer` out of an existing `Fleet
 A full `FleetAllocation` specification is available below and in the 
 {{< ghlink href="examples/fleetallocation.yaml" >}}example folder{{< /ghlink >}} for reference:
 
-{{% feature expiryVersion="0.12.0" %}}
 ```yaml
 apiVersion: "stable.agones.dev/v1alpha1"
 kind: FleetAllocation
@@ -143,22 +163,6 @@ spec:
     annotations:
       map:  garden22
 ```
-{{% /feature %}}
-{{% feature publishVersion="0.12.0" %}}
-```yaml
-apiVersion: "agones.dev/v1"
-kind: FleetAllocation
-metadata:
-  generateName: fleet-allocation-example-
-spec:
-  fleetName: fleet-example
-  metadata:
-    labels:
-      mode: deathmatch
-    annotations:
-      map:  garden22
-```
-{{% /feature %}}
 
 We recommend using `metadata > generateName`, to declare to Kubernetes that a unique
 name for the `FleetAllocation` is generated when the `FleetAllocation` is created.

site/content/en/docs/Reference/fleetautoscaler.md

@@ -30,14 +30,29 @@ spec:
 apiVersion: "autoscaling.agones.dev/v1"
 kind: FleetAutoscaler
 metadata:
+  # FleetAutoscaler Metadata
+  # https://v1-9.docs.kubernetes.io/docs/reference/generated/kubernetes-api/v1.9/#objectmeta-v1-meta
   name: fleet-autoscaler-example
 spec:
+  # The name of the fleet to attach to and control. Must be an existing Fleet in the same namespace
+  # as this FleetAutoscaler
   fleetName: fleet-example
+  # The autoscaling policy
   policy:
+    # type of the policy. for now, only Buffer is available
     type: Buffer
+    # parameters of the buffer policy
     buffer:
+      # Size of a buffer of "ready" game server instances
+      # The FleetAutoscaler will scale the fleet up and down trying to maintain this buffer, 
+      # as instances are being allocated or terminated
+      # it can be specified either in absolute (i.e. 5) or percentage format (i.e. 5%)
       bufferSize: 5
+      # minimum fleet size to be set by this FleetAutoscaler. 
+      # if not specified, the actual minimum fleet size will be bufferSize
       minReplicas: 10
+      # maximum fleet size that can be set by this FleetAutoscaler
+      # required
       maxReplicas: 20
 ```
 {{% /feature %}}
@@ -66,16 +81,22 @@ spec:
 apiVersion: "autoscaling.agones.dev/v1"
 kind: FleetAutoscaler
 metadata:
-  name: fleet-autoscaler-example
+  name: webhook-fleet-autoscaler
 spec:
-  fleetName: fleet-example
+  fleetName: simple-udp
   policy:
+    # type of the policy - this example is Webhook
     type: Webhook
+    # parameters for the webhook policy - this is a WebhookClientConfig, as per other K8s webhooks
     webhook:
-      name: "fleet-autoscaler-webhook"
-      namespace: "default"
-      path: "/scale"
-      caBundle: "<base64 encoded string>"
+      # use a service, or URL
+      service:
+        name: autoscaler-webhook-service
+        namespace: default
+        path: scale
+      # optional for URL defined webhooks
+      # url: ""
+      # caBundle:  optional, used for HTTPS webhook type
 ```
 {{% /feature %}}
 
@@ -207,6 +228,9 @@ type FleetStatus struct {
 	Replicas int32 `json:"replicas"`
 	// ReadyReplicas are the number of Ready GameServer replicas
 	ReadyReplicas int32 `json:"readyReplicas"`
+	// ReservedReplicas are the total number of Reserved GameServer replicas in this fleet.
+	// Reserved instances won't be deleted on scale down, but won't cause an autoscaler to scale up.
+	ReservedReplicas int32 `json:"reservedReplicas"`
 	// AllocatedReplicas are the number of Allocated GameServer replicas
 	AllocatedReplicas int32 `json:"allocatedReplicas"`
 }

site/content/en/docs/Reference/gameserver.md

@@ -42,24 +42,51 @@ spec:
 ```yaml
 apiVersion: "agones.dev/v1"
 kind: GameServer
+# GameServer Metadata
+# https://v1-8.docs.kubernetes.io/docs/api-reference/v1.8/#objectmeta-v1-meta
 metadata:
-  name: "gds-example"
+  # generateName: "gds-example" # generate a unique name, with the given prefix
+  name: "gds-example" # set a fixed name
 spec:
+  # if there is more than one container, specify which one is the game server
+  container: example-server
+  # Array of ports that can be exposed as direct connections to the game server container
   ports:
+    # name is a descriptive name for the port
   - name: default
-    portPolicy: Static
+    # portPolicy has two options:
+    # - "Dynamic" (default) the system allocates a free hostPort for the gameserver, for game clients to connect to
+    # - "Static", user defines the hostPort that the game client will connect to. Then onus is on the user to ensure that the
+    # - "Passthrough" dynamically sets the `containerPort` to the same value as the dynamically selected hostPort.
+    #      This will mean that users will need to lookup what port has been opened through the server side SDK.
+    # port is available. When static is the policy specified, `hostPort` is required to be populated
+    portPolicy: Dynamic
+    # the port that is being opened on the game server process
     containerPort: 7654
+    # the port exposed on the host, only required when `portPolicy` is "Static". Overwritten when portPolicy is "Dynamic".
     hostPort: 7777
+    # protocol being used. Defaults to UDP. TCP is the only other option
     protocol: UDP
+  # Health checking for the running game server
   health:
+    # Disable health checking. defaults to false, but can be set to true
     disabled: false
+    # Number of seconds after the container has started before health check is initiated. Defaults to 5 seconds
     initialDelaySeconds: 5
+    # If the `Health()` function doesn't get called at least once every period (seconds), then
+    # the game server is not healthy. Defaults to 5
     periodSeconds: 5
+    # Minimum consecutive failures for the health probe to be considered failed after having succeeded.
+    # Defaults to 3. Minimum value is 1
     failureThreshold: 3
+  # Pod template configuration
+  # https://v1-8.docs.kubernetes.io/docs/api-reference/v1.8/#podtemplate-v1-core
   template:
+    # pod metadata. Name & Namespace is overwritten
     metadata:
       labels:
         myspeciallabel: myspecialvalue
+    # Pod Specification
     spec:
       containers:
       - name: example-server

site/content/en/docs/Reference/gameserverallocation.md

@@ -47,17 +47,23 @@ spec:
 {{% /feature %}}
 {{% feature publishVersion="0.12.0" %}}
 ```yaml
-apiVersion: "agones.dev/v1"
+apiVersion: "allocation.agones.dev/v1"
 kind: GameServerAllocation
-metadata:
-  generateName: simple-udp-
 spec:
+  # GameServer selector from which to choose GameServers from.
+  # GameServers still have the hard requirement to be `Ready` to be allocated from
+  # however we can also make available `matchExpressions` for even greater
+  # flexibility.
+  # Below is an example of a GameServer allocated against a given fleet.
+  # See: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/ for more details
   required:
     matchLabels:
       game: my-game
     matchExpressions:
       - {key: tier, operator: In, values: [cache]}
-  # ordered list of preferred allocations 
+  # ordered list of preferred allocations out of the `required` set.
+  # If the first selector is not matched, the selection attempts the second selector, and so on.
+  # This is useful for things like smoke testing of new game servers.
   # This also support `matchExpressions`
   preferred:
     - matchLabels: