diff --git a/site/content/en/docs/Getting Started/create-fleet.md b/site/content/en/docs/Getting Started/create-fleet.md index 7a0197cdc1..7dc51a8ae0 100644 --- a/site/content/en/docs/Getting Started/create-fleet.md +++ b/site/content/en/docs/Getting Started/create-fleet.md @@ -171,7 +171,7 @@ are often used in conjunction. kubectl create -f https://raw.githubusercontent.com/googleforgames/agones/{{< release-branch >}}/examples/simple-udp/gameserverallocation.yaml -o yaml ``` -For the full details of the YAML file head to the [Fleet Specification Guide]({{< ref "/docs/Reference/fleet.md#gameserver-allocation-specification" >}}) +For the full details of the YAML file head to the [GameServerAllocation Specification Guide]({{< ref "/docs/Reference/gamserverallocation.md" >}}) You should get back a response that looks like the following: @@ -443,7 +443,7 @@ You have now deployed a new version of your game! ## Next Steps -- Have a look at the [GameServerAllocation specification]({{< ref "/docs/Reference/fleet.md#gameserver-allocation-specification" >}}), and see +- Have a look at the [GameServerAllocation specification]({{< ref "/docs/Reference/gamserverallocation.md" >}}), and see how the extra functionality can enable smoke testing, server information communication, and more. - You can now create a fleet autoscaler to automatically resize your fleet based on the actual usage. See [Create a Fleet Autoscaler]({{< relref "create-fleetautoscaler.md" >}}). diff --git a/site/content/en/docs/Guides/Client SDKs/_index.md b/site/content/en/docs/Guides/Client SDKs/_index.md index de74b57454..839981936d 100644 --- a/site/content/en/docs/Guides/Client SDKs/_index.md +++ b/site/content/en/docs/Guides/Client SDKs/_index.md @@ -98,7 +98,7 @@ This can be useful to track `GameServer > Status > State` changes, `metadata` ch In combination with this SDK, manipulating [Annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) and [Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) can also be a useful way to communicate information through to running game server processes from outside those processes. -This is especially useful when combined with `GameServerAllocation` [applied metadata]({{< ref "/docs/Reference/fleet.md#gameserver-allocation-specification" >}}). +This is especially useful when combined with `GameServerAllocation` [applied metadata]({{< ref "/docs/Reference/gamserverallocation.md" >}}). Since the GameServer contains an entire [PodTemplate](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/#pod-templates) the returned object is limited to that configuration that was deemed useful. If there are @@ -115,7 +115,7 @@ and the {{< ghlink href="examples" >}}examples{{< /ghlink >}}. With some matchmakers and game matching strategies, it can be important for game servers to mark themselves as `Allocated`. For those scenarios, this SDK functionality exists. -> Note: Using a [GameServerAllocation]({{< ref "/docs/Reference/fleet.md#gameserver-allocation-specification" >}}) is preferred in all other scenarios, +> Note: Using a [GameServerAllocation]({{< ref "/docs/Reference/gamserverallocation.md" >}}) is preferred in all other scenarios, as it gives Agones control over how packed `GameServers` are scheduled within a cluster, whereas with `Allocate()` you relinquish control to an external service which likely doesn't have as much information as Agones. diff --git a/site/content/en/docs/Guides/Client SDKs/rest.md b/site/content/en/docs/Guides/Client SDKs/rest.md index b1281887f4..093e4d85c4 100644 --- a/site/content/en/docs/Guides/Client SDKs/rest.md +++ b/site/content/en/docs/Guides/Client SDKs/rest.md @@ -154,7 +154,7 @@ Response: With some matchmakers and game matching strategies, it can be important for game servers to mark themselves as `Allocated`. For those scenarios, this SDK functionality exists. -> Note: Using a [GameServerAllocation]({{< ref "/docs/Reference/fleet.md#gameserver-allocation-specification" >}}) is preferred in all other scenarios, +> Note: Using a [GameServerAllocation]({{< ref "/docs/Reference/gamserverallocation.md" >}}) is preferred in all other scenarios, as it gives Agones control over how packed `GameServers` are scheduled within a cluster, whereas with `Allocate()` you relinquish control to an external service which likely doesn't have as much information as Agones. diff --git a/site/content/en/docs/Reference/fleet.md b/site/content/en/docs/Reference/fleet.md index 20386be9f4..6a0dfb4474 100644 --- a/site/content/en/docs/Reference/fleet.md +++ b/site/content/en/docs/Reference/fleet.md @@ -75,71 +75,7 @@ The `spec` field is the actual `Fleet` specification and it is composed as follo - `template` a full `GameServer` configuration template. See the [GameServer]({{< relref "gameserver.md" >}}) reference for all available fields. -## GameServer Allocation Specification - -A `GameServerAllocation` is used to atomically allocate a GameServer out of a set of GameServers. -This could be a single Fleet, multiple Fleets, or a self managed group of GameServers. - -A full `GameServerAllocation` specification is available below and in the -{{< ghlink href="/examples/gameserverallocation.yaml" >}}example folder{{< /ghlink >}} for reference: - - -```yaml -apiVersion: "stable.agones.dev/v1alpha1" -kind: GameServerAllocation -metadata: - generateName: simple-udp- -spec: - required: - matchLabels: - game: my-game - matchExpressions: - - {key: tier, operator: In, values: [cache]} - # ordered list of preferred allocations - # This also support `matchExpressions` - preferred: - - matchLabels: - stable.agones.dev/fleet: green-fleet - - matchLabels: - stable.agones.dev/fleet: blue-fleet - # 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 - # Optional custom metadata that is added to the game server at allocation - # You can use this to tell the server necessary session data - metadata: - labels: - mode: deathmatch - annotations: - map: garden22 -``` - -We recommend using `metadata > generateName`, to declare to Kubernetes that a unique -name for the `GameServerAllocation` is generated when the `GameServerAllocation` is created. - -The `spec` field is the actual `GameServerAllocation` specification and it is composed as follow: - -- `required` is a [label selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) - (matchLabels and/or matchExpressions) from which to choose GameServers from. - GameServers still have the hard requirement to be `Ready` to be allocated from -- `preferred` is an order list of [label selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) - 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. -- `scheduling` defines how GameServers are organised across the cluster, in this case specifically when allocating - `GameServers` for usage. - "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. See [Scheduling and Autoscaling]({{< ref "/docs/Advanced/scheduling-and-autoscaling.md" >}}) for more details. - -- `metadata` is an optional list of custom labels and/or annotations that will be used to patch - the game server's metadata in the moment of allocation. This can be used to tell the server necessary session data - -{{< feature expiryVersion="0.12.0" >}} +{{% feature expiryVersion="0.12.0" %}} ## Fleet Allocation Specification > Fleet Allocation is **deprecated** in version 0.10.0, and will be removed in the 0.12.0 release. @@ -173,7 +109,7 @@ The `spec` field is the actual `FleetAllocation` specification and it is compose when the `FleetAllocation` is created - `metadata` is an optional list of custom labels and/or annotations that will be used to patch the game server's metadata in the moment of allocation. This can be used to tell the server necessary session data -{{< /feature >}} +{{% /feature %}} ## Fleet Scale Subresource Specification diff --git a/site/content/en/docs/Reference/gamserverallocation.md b/site/content/en/docs/Reference/gamserverallocation.md new file mode 100644 index 0000000000..babaaf4bc6 --- /dev/null +++ b/site/content/en/docs/Reference/gamserverallocation.md @@ -0,0 +1,67 @@ +--- +title: "GameServerAllocation Specification" +linkTitle: "GameServerAllocation" +date: 2019-07-07T03:58:52Z +description: "A `GameServerAllocation` is used to atomically allocate a GameServer out of a set of GameServers. + This could be a single Fleet, multiple Fleets, or a self managed group of GameServers." +weight: 30 +--- + +A full `GameServerAllocation` specification is available below and in the +{{< ghlink href="/examples/gameserverallocation.yaml" >}}example folder{{< /ghlink >}} for reference: + + +```yaml +apiVersion: "stable.agones.dev/v1alpha1" +kind: GameServerAllocation +metadata: + generateName: simple-udp- +spec: + required: + matchLabels: + game: my-game + matchExpressions: + - {key: tier, operator: In, values: [cache]} + # ordered list of preferred allocations + # This also support `matchExpressions` + preferred: + - matchLabels: + stable.agones.dev/fleet: green-fleet + - matchLabels: + stable.agones.dev/fleet: blue-fleet + # 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 + # Optional custom metadata that is added to the game server at allocation + # You can use this to tell the server necessary session data + metadata: + labels: + mode: deathmatch + annotations: + map: garden22 +``` + +We recommend using `metadata > generateName`, to declare to Kubernetes that a unique +name for the `GameServerAllocation` is generated when the `GameServerAllocation` is created. + +The `spec` field is the actual `GameServerAllocation` specification and it is composed as follow: + +- `required` is a [label selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) + (matchLabels and/or matchExpressions) from which to choose GameServers from. + GameServers still have the hard requirement to be `Ready` to be allocated from +- `preferred` is an order list of [label selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) + 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. +- `scheduling` defines how GameServers are organised across the cluster, in this case specifically when allocating + `GameServers` for usage. + "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. See [Scheduling and Autoscaling]({{< ref "/docs/Advanced/scheduling-and-autoscaling.md" >}}) for more details. + +- `metadata` is an optional list of custom labels and/or annotations that will be used to patch + the game server's metadata in the moment of allocation. This can be used to tell the server necessary session data \ No newline at end of file