From db35106e1575c3c1b01b8d7660af19b81bfed588 Mon Sep 17 00:00:00 2001 From: Mark Mandel Date: Mon, 6 Apr 2020 17:49:00 -0700 Subject: [PATCH] FAQ for Agones Wrote an FAQ for Agones based on user questions that have been received over time. --- site/content/en/docs/FAQ/_index.md | 190 +++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 site/content/en/docs/FAQ/_index.md diff --git a/site/content/en/docs/FAQ/_index.md b/site/content/en/docs/FAQ/_index.md new file mode 100644 index 0000000000..1d8646815e --- /dev/null +++ b/site/content/en/docs/FAQ/_index.md @@ -0,0 +1,190 @@ +--- +title: "Frequently Asked Questions" +linkTitle: "FAQ" +weight: 400 +date: 2020-04-06 +--- + +## Architecture + +### What is the relationship between a Kubernetes Pod and an Agones GameServer? + +Agones creates a backing Pod with the appropriate configuration parameters for each GameServer that is configured in +the cluster. They both have the same name if you are ever looking to match one to the other. + +### Can I reuse a GameServer for multiple game sessions? + +Yes. + +Agones is inherently un-opinionated about the lifecycle of your game. When you call +[SDK.Allocate()]({{< ref "/docs/Guides/Client SDKs/_index.md#allocate" >}}) you are +protecting that GameServer instance from being scaled down for the duration of the Allocation. Typically, you would +run one game session within a single allocation. However, you could allocate, and run N sessions on a single +GameServer, and then de-allocate/shutdown at a later time. + +### How can I return an `Allocated` GameServer to the `Ready` state? + +If you wish to return an `Allocated` GameServer to the `Ready` state, you can use the +[SDK.Ready()]({{< ref "/docs/Guides/Client SDKs/_index.md#ready" >}}) command whenever it +makes sense for your GameServer to return to the pool of potentially Allocatable and/or scaled down GameServers. + +## Integration + +### What steps do I need to take to integrate my GameServer? + +1. Integrate your game server binary with the [Agones SDK]({{< ref "/docs/Guides/Client SDKs/_index.md" >}}), + calling the appropriate [lifecycle event]({{< ref "/docs/Guides/gameserver-lifecycle.md" >}}) hooks. +1. Containerize your game server binary with [Docker](https://www.docker.com/) +1. Publish your Docker image in a [container registry/repository](https://docs.docker.com/docker-hub/repos/). +1. Create a [gameserver.yaml]({{< ref "/docs/Reference/gameserver.md" >}}) file for your container image. +1. Test your gameserver.yaml file. +1. Consider utilizing [Fleets]({{< ref "/docs/Reference/fleet.md" >}}). + and [Autoscalers]({{< ref "/docs/Reference/fleetautoscaler.md" >}}) for deploying at scale. + +### What are some common patterns for integrating the SDK with a Game Server Binary? + +* In-Engine + * Integrate the SDK directly with the dedicated game server, such that it is part of the same codebase. +* Sidecar + * Use a Kubernetes [sidecar pattern](https://blog.davemdavis.net/2018/03/13/the-sidecar-pattern/) to run the SDK + in a separate process that runs alongside your game server binary, and can share the disk and network namespace. + This game server binary could expose its own API, or write to a shared file, that the sidecar process + integrates with, and can then communicate back to Agones through the SDK. +* Wrapper + * Write a process that wraps the game server binary, and intercepts aspects such as the foreground log output, and + use that information to react and communicate with Agones appropriately. + This can be particularly useful for legacy game servers or game server binaries wherein you do not have access to + the original source. You can see this in both the {{< ghlink href="examples/xonotic" >}}Xonotic{{< /ghlink >}} and + {{< ghlink href="examples/supertuxkart" >}}SuperTuxKart{{< /ghlink >}} examples. + +### What if my engine / language of choice does not have a supported SDK, what can I do? + +Either utilise the [REST API]({{< ref "/docs/Guides/Client SDKs/rest.md" >}}), which can be +[generated from the Swagger specification]({{< ref "/docs/Guides/Client SDKs/rest.md#generating-clients" >}}), +or [generate your own gRPC client from the proto file]({{< ref "/docs/Guides/Client SDKs/_index.md" >}}). + +Game Server SDKs are a thin wrapper around either REST or gRPC clients, depending on language or platform, and can be +used as examples. + +### How can I pass data to my Game Server binary on Allocation? + +A `GameServerAllocation` has a [spec.metadata section]({{< ref "/docs/Reference/gameserverallocation.md" >}}), +that will apply any configured [Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) +and/or [Annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) to a requested +GameServer at Allocation time. + +The game server binary can watch for the state change to `Allocated`, as well as changes to the GameServer metadata, +through [SDK.WatchGameServer()]({{< ref "/docs/Guides/Client SDKs/_index.md#watchgameserver-function-gameserver" >}}). + +Combining these two features allows you to pass information such as map data, gameplay metadata and more to a game +server binary at Allocation time, through Agones functionality. + +### How can I expose information from my game server binary to an external service? + +The Agones game server SDK allows you to set custom +[Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) +and [Annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) through +the [SDK.SetLabel()]({{< ref "/docs/Guides/Client SDKs/rest.md#setlabel-key-value" >}}) +and [SDK.SetAnnotation()]({{< ref "/docs/Guides/Client SDKs/rest.md#setannotation-key-value" >}}) functionality +respectively. + +This information is then queryable via the [Kubernetes API]({{< ref "/docs/Guides/access-api.md" >}}), +and can be used for game specific, custom integrations. + +### If my game server requires more states than what Agones provides (e.g. Ready, Allocated, Shutdown, etc), can I add my own? + +If you want to track custom game server states, then you can utilise the game server client SDK +[SDK.SetLabel()]({{< ref "/docs/Guides/Client SDKs/rest.md#setlabel-key-value" >}}) +and [SDK.SetAnnotation()]({{< ref "/docs/Guides/Client SDKs/rest.md#setannotation-key-value" >}}) functionality to +expose these custom states to outside systems via your own labels and annotations. + +This information is then queryable via the [Kubernetes API]({{< ref "/docs/Guides/access-api.md" >}}), and +can be used for game specific state integrations with systems like matchmakers and more. + +Custom labels could also potentially be utilised with [GameServerAllocation required and/or preferred label +selectors](http://localhost:1313/docs/reference/gameserverallocation/), to further refine `Ready` GameServer +selection on Allocation. + +## Scaling + +### How large can an Agones cluster be? / How many GameServers can be supported in a single cluster? + +The answer to this question is "it depends" 😁. + +As a rule of thumb, we recommend clusters no larger than 500 nodes, based on production workloads. + +That being said, this is highly dependent on Kubernetes hosting platform, master resources, nodes resources, resource +requirements of your game server, game server session length, node spin up time, etc, and therefore you should run your +own load tests against your hosting provider to determine the optimal cluster size for your game. + +We recommend running multiple clusters for your production GameServer workloads, to spread the load and +provide extra redundancy across your entire game server fleet. + +## Network + +### How are IP addresses allocated to GameServers? + +Each `GameServer` inherits the IP Address of the Node on which it resides. If it can find an `ExternalIP` address on +the Node (which it should if it's a publicly addressable Node), that it utilised, otherwise it falls back to using the +`InternalIP` address. + +### How is traffic routed from the allocated Port to the GameServer container? + +Traffic is routed to the GameServer Container utilising the `hostPort` field on a +[Pod's Container specification](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#containerport-v1-core). + +This opens a port on the host Node and routes traffic to the container +via [iptables](https://en.wikipedia.org/wiki/Iptables) or +[ipvs](https://kubernetes.io/blog/2018/07/09/ipvs-based-in-cluster-load-balancing-deep-dive/), depending on host +provider and/or network overlay. + +In worst case scenarios this routing can add an extra 0.5ms latency to UDP packets, but that is extremely rare. + +#### Why did you use hostPort and not hostNetwork for your networking? + +The decision was made not to use `hostNetwork`, as the benefits of having isolated network namespaces between +game server processes give us the ability to run +[sidecar containers](https://blog.davemdavis.net/2018/03/13/the-sidecar-pattern/), and provides an extra layer of +security to each game server process. + +## Performance + +### How big an image can I use for my GameServer? + +We routinely see users running container images that are multiple GB in size. + +The only downside to larger images, is that they can take longer to first load on a Kubernetes node, but that can be +managed by your +[Fleet]({{< ref "/docs/Reference/fleet.md" >}}) and +[Fleet Autoscaling]({{< ref "/docs/Reference/fleetautoscaler.md" >}}) +configuration to ensure this load time is taken into account on a new Node's container initial load. + +### How quickly can Agones spin up new GameServer instances? + +When running Agones on GKE, we have verified that an Agones cluster can start up +to 10,000 GameServer instances per minute (not including node creation). + +This number could vary depending on the underlying scaling capabilities +of your cloud provider, Kubernetes cluster configuration, and your GameServer Ready startup time, and +therefore we recommend you always run your own load tests for your specific game and game server containers. + +## Operating Systems + +### Are Windows Container game servers supported by Agones? + +As of Kubernetes 1.14, Windows Container support +[has been released as GA](https://kubernetes.io/blog/2019/03/25/kubernetes-1-14-release-announcement/). + +That being said, Agones has yet to be tested with Windows Nodes and work on this feature has not been started. + +If you are interested in this feature and/or contributing, please add a comment to the +[Running windows game server](https://github.com/googleforgames/agones/issues/54) ticket. + +## Ecosystem + +### Is there an example of Agones and Open Match working together? + +Space Agon is a demo integration of [Agones](https://agones.dev/) and +[Open Match](https://open-match.dev/), that runs a browser based game. + +You can find it at: https://github.com/Laremere/space-agon. \ No newline at end of file