diff --git a/docs/gameserverbuild.md b/docs/gameserverbuild.md index c9fd7edb..bd48c740 100755 --- a/docs/gameserverbuild.md +++ b/docs/gameserverbuild.md @@ -8,8 +8,6 @@ nav_order: 7 GameServerBuild defines the specification and auto-scaling configuration of the GameServers that you want to run in the cluster. Each version of your game server should have its own GameServerBuild. -> _**NOTE**_: A GameServerBuild is equivalent to a Build region in MPS. GameServer containers that work in Thundernetes should work in a similar way on PlayFab Multiplayer Servers service. - Here you can see the YAML that can be used to create a GameServerBuild in Thundernetes. The only fields that you should change after the GameServerBuild is created are the *standingBy* and the *max* ones. The other fields should be considered immutable. ```yaml @@ -44,42 +42,46 @@ The template.spec contains the definition for a [Kubernetes Pod](https://kuberne ## PortsToExpose -This is a list of ports that you want to be exposed in the [Worker Node/VM](https://kubernetes.io/docs/concepts/architecture/nodes/) when the Pod is created. The way this works is that each Pod you create will have >=1 number of containers. There, each container will have its own *Ports* definition. If a port number in this definition is included in the *portsToExpose* array, this port will be publicly exposed in the Node/VM. This is accomplished by the setting of a **hostPort** value for each of the container ports you want to expose. +This is a list of ports that you want to be exposed in the [Worker Node/VM](https://kubernetes.io/docs/concepts/architecture/nodes/) when the Pod is created. Each Pod you create will have >=1 number of containers. There, each container will have its own *Ports* definition. If a port number in this definition is included in the *portsToExpose* array, this port will be publicly exposed in the Node/VM. Thundernetes accomplishes this by setting a **hostPort** value for each of the container ports you want to expose. If you have set a hostPort value in the container port definition, Thundernetes will override this value. -The reason we need this functionality is that you may want to use some ports on your Pod containers for other purposes rather than players connecting to it. +The reason for the `PortsToExpose` declaration is that you may want to use some ports on your Pod containers for other purposes rather than players connecting to it. Ports that are to be exposed are assigned a number in the port range 10000-12000 by default. This port range is configurable, check [here](howtos/configureportrange.md) for details. -**IMPORTANT**: Port names must be specified for all the ports that are in the *portsToExpose* array. Reason is that these ports are accessible via the GSDK, using their name. This way, the game server can discover them on runtime. +**IMPORTANT**: Port names must be specified for all the ports that are in the *portsToExpose* array. Reason is that these ports are accessible via the [GSDK](gsdk/README.md), using their name. This way, the game server can discover them on runtime. ## CrashesToMarkUnhealthy -CrashesToMarkUnhealthy (integer) is the number of crashes that you want to trigger the GameServerBuild to become Unhealthy. Once this happens, no other operation will take place on the GameServerBuild. To allow Thundernetes to continue performing reconciliations on the GameServerBuild after it has become Unhealthy, you can increase the value of the CrashesToMarkUnhealthy field. The GameServerBuild will be marked as Healthy again till the number of crashes reaches the value of CrashesToMarkUnhealthy. +CrashesToMarkUnhealthy (integer) is the number of crashes that will transition the GameServerBuild to Unhealthy. Once this happens, no other reconcile/resize operation will take place on the GameServerBuild. To allow Thundernetes to continue performing reconciliations on the GameServerBuild after it has become Unhealthy, you can increase the value of the CrashesToMarkUnhealthy field or remove it completely. The GameServerBuild will be marked as Healthy again till the number of crashes reaches the value of CrashesToMarkUnhealthy. + +Be very careful if you decided to remove the CrashesToMarkUnhealthy field. If you remove it, the GameServerBuild will never be marked as Unhealthy, no matter how many crashes it has. This might have the negative impact on Thundernetes constantly creating GameServers to replace the ones that have crashed. For this reason, we always recommend to set the CrashesToMarkUnhealthy field using a value that makes sense for your game/environment. ## Game server image upgrades -You should **not** change the container image of your GameServerBuild. The best practice to upgrade your game server version is to +You should **not** change the container image of your GameServerBuild. The best practice to upgrade your game server version is to: - spin up a separate GameServerBuild - configure your matchmaker to allocate against this new GameServerBuild - configure the original GameServerBuild to 0 standingBy - when all the active games in the original GameServerBuild end, you can safely delete it -At this point, Thundernetes does not do anything to prevent you from changing the container image on the GameServerBuild YAML file, but you should consider the GameServerBuild as immutable (apart from changing the standingBy and max numbers, of course). +Thundernetes does not do anything to prevent you from changing the container image on the GameServerBuild YAML file, but you should consider the GameServerBuild as immutable (apart from changing the standingBy and max numbers, of course). ## Using host networking -Thundernetes supports running your GameServer Pods with host networking. To do that, you need to provide a GameServerBuild YAML like [this](http://github.com/playfab/thundernetes/tree/main/samples/netcore/sample-hostnetwork.yaml), setting the `hostNetwork` value to true on PodSpec template. During Pod creation, thundernetes controllers will override the containerPort with the same value that will be assigned in the hostPort. +Thundernetes supports running your GameServer Pods with host networking. To do that, you need to provide a GameServerBuild YAML like [this](http://github.com/playfab/thundernetes/tree/main/samples/netcore/sample-hostnetwork.yaml), setting the `hostNetwork` value to true on PodSpec template. During Pod creation, Thundernetes controllers will **override** the containerPort with the same value that will be assigned in the hostPort. -You **have to** use the generated port when you instantiate your game server process. To grab the port number, you should use GSDK. +You **have to** use the generated port when you instantiate your game server process. To grab the port number, you should use the [GSDK](gsdk/README.md) `GetGameServerConnectionInfo` method. ```csharp -string ListeningPortKey = "nameOfThePortInTheGameServerBuild"; -IDictionary initialConfig = GameserverSDK.getConfigSettings(); -if (initialConfig?.ContainsKey(ListeningPortKey) == true) +string ListeningPortKey = "gameport"; +var gameServerConnectionInfo = GameserverSDK.GetGameServerConnectionInfo(); +var portInfo = gameServerConnectionInfo.GamePortsConfiguration.Where(x=>x.Name == ListeningPortKey); +if(portInfo.Count() == 0) { - int listeningPort = int.Parse(initialConfig[ListeningPortKey]); - // instantiate your game server with the value of the listeningPort + throw new Exception("No port info found for " + ListeningPortKey); +} +var port = portInfo.Single().ServerListeningPort; ``` -> _**NOTE**_: Unfortunately, it is necessary to provide a `containerPort` value in the GameServerBuild YAML, since it is required for GameServerBuild validation (specifically, the way the PodTemplate is validated). However, as mentioned, this provided value is not used since it's overwritten by the `hostPort` value. \ No newline at end of file +> _**NOTE**_: It is necessary to provide a `containerPort` value in the GameServerBuild YAML, since it is required for GameServerBuild validation (specifically, the way the PodTemplate is validated from Kubernetes). However, as mentioned, this provided value is not used since it's overwritten by the `hostPort` value. \ No newline at end of file