diff --git a/docs/README.md b/docs/README.md index a8dd64fc..1105f989 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,7 +22,7 @@ Thundernetes is a project originating from the [Azure PlayFab Multiplayer Server Thundernetes offers: -- game server auto-scaling enabled by default, based on [requested standingBy levels](./gameserverbuild.md) +- game server auto-scaling, based on [requested standingBy levels](./gameserverbuild.md) - a [latency server](./howtos/latencyserver.md) to test client connection to multiple Kubernetes cluster and determine the best cluster to connect to - a [Game Server SDK](./gsdk/README.md) in multiple languages/environments (Unity, Unreal, C#, C++, Java, Go) and a [local utility](./gsdk/runlocalmultiplayeragent.md) to test your game server integration locally - a [web-based User Interface](./thundernetesui/README.md) to manage Thundernetes deployments in multiple clusters. This component utilizes a [REST API](./gameserverapi/README.md) which you can use to manage your game servers diff --git a/docs/architecture.md b/docs/architecture.md index da39b337..ecd8ae44 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -34,7 +34,7 @@ GSDK libraries need to read configuration from a file (GSDKConfig.json). In orde ## End to end (e2e) testing -We are using [kind](https://kind.sigs.k8s.io/) and Kubernetes [client-go](https://github.com/kubernetes/client-go) library for end-to-end testing scenarios. Kind dynamically setups a Kubernetes cluster in which we create and allocate game servers and test various scenarios. Check [this](../cmd/e2e) folder for more details. +We are using [kind](https://kind.sigs.k8s.io/) and Kubernetes [client-go](https://github.com/kubernetes/client-go) library for end-to-end testing scenarios. Kind dynamically setups a Kubernetes cluster in which we create and allocate game servers and test various scenarios. Check [this](https://github.com/PlayFab/thundernetes/tree/main/e2e) folder for more details. ## metrics diff --git a/docs/contributing.md b/docs/contributing.md index ffe211f5..ece7d544 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -47,8 +47,8 @@ We welcome many different types of contributions including: We have good first issues for new contributors and help wanted issues suitable for any contributor. -[good first issue](TODO) has extra information to help you make your first contribution. -[help wanted](TODO) are issues suitable for someone who isn't a core maintainer and is +[good first issue](https://github.com/PlayFab/thundernetes/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) has extra information to help you make your first contribution. +[help wanted](https://github.com/PlayFab/thundernetes/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) are issues suitable for someone who isn't a core maintainer and is good to move onto after your first pull request. Sometimes there won’t be any issues with these labels. diff --git a/docs/development/release.md b/docs/development/release.md index ceb33bb6..2bf7f998 100644 --- a/docs/development/release.md +++ b/docs/development/release.md @@ -15,5 +15,5 @@ This will require 2 PRs. - Manually run the GitHub Actions workflows to create new [linux images](https://github.com/PlayFab/thundernetes/actions/workflows/publish.yml) and [windows images](https://github.com/PlayFab/thundernetes/actions/workflows/publish-windows.yml) - Git pull the latest changes from the main branch - Run `make create-install-files` to generate the operator install files -- Replace the image on the [netcore-sample YAML files](https://github.com/PlayFab/thundernetes/samples/netcore) -- Push and merge \ No newline at end of file +- Replace the image tag on the [samples folder](https://github.com/PlayFab/thundernetes/samples/) and especially the [netcore-sample YAML files](https://github.com/PlayFab/thundernetes/samples/netcore) since these are referenced by our quickstart doc. +- Push and merge. Good luck! \ No newline at end of file diff --git a/docs/development/windows.md b/docs/development/windows.md index 09654732..88c9ff5c 100644 --- a/docs/development/windows.md +++ b/docs/development/windows.md @@ -7,7 +7,7 @@ nav_order: 2 # Developing with Windows containers -Thundernetes now supports game servers running on Windows containers, you can read more about it [here](./howtos/windowscontainers.md). If you want to try this you need both a Windows machine, with Windows 2019 or higher, to build the necessary Windows Docker images, and a Kubernetes cluster with Windows nodes. You can't build or run Windows containers on a Linux machine. If you have all of this, you can follow these next steps: +Thundernetes now supports game servers running on Windows containers, you can read more about it [here](../howtos/windowscontainers.md). If you want to try this you need both a Windows machine, with Windows 2019 or higher, to build the necessary Windows Docker images, and a Kubernetes cluster with Windows nodes. You can't build or run Windows containers on a Linux machine. If you have all of this, you can follow these next steps: - Login to your container registry (`docker login `) on your Linux machine or WSL, where `` is the registry where you want to upload your images. - Run `NS= make clean build push create-install-files-dev`. diff --git a/docs/gameserverbuild.md b/docs/gameserverbuild.md index 632a3070..80c4f76b 100755 --- a/docs/gameserverbuild.md +++ b/docs/gameserverbuild.md @@ -73,4 +73,4 @@ Thundernetes supports Kubernetes host networking (i.e. using the Node's network ## Game server image upgrades -You should **not** change any parts of the Pod specification in your GameServerBuild (including image/ports etc.). The best practice to upgrade your game server version is to spin up a separate GameServerBuild and gradually move traffic from the old GameServerBuild to the new one. Check our [relevant documentation](../howtos/upgradebuild.md) for more information. \ No newline at end of file +You should **not** change any parts of the Pod specification in your GameServerBuild (including image/ports etc.). The best practice to upgrade your game server version is to spin up a separate GameServerBuild and gradually move traffic from the old GameServerBuild to the new one. Check our [relevant documentation](./howtos/upgradebuild.md) for more information. \ No newline at end of file diff --git a/docs/gsdk/README.md b/docs/gsdk/README.md index 32c566b0..61efbf0a 100644 --- a/docs/gsdk/README.md +++ b/docs/gsdk/README.md @@ -7,9 +7,10 @@ has_children: true # How to run your game server on Thundernetes? -Once you [install Thundernetes](quickstart/installing-thundernetes.md) (either on [kind](quickstart/installing-kind.md) or [AKS](quickstart/installing-aks.md)) and verify it's working as intended, you can prepare your game server for Thundernetes by integrating with the open source [Game Server SDK (GSDK)](https://github.com/playfab/gsdk). GSDK library is also used by [Azure PlayFab Multiplayer Servers (MPS)](https://docs.microsoft.com/gaming/playfab/features/multiplayer/servers/) service. In this way, you can easily migrate your game servers from MPS to Thundernetes and vice versa. +Once you [install Thundernetes](../quickstart/installing-thundernetes.md) (either on [kind](../quickstart/installing-kind.md) or [AKS](quickstart/installing-aks.md)) and verify it's working as intended, you can prepare your game server for Thundernetes by integrating with the open source [Game Server SDK (GSDK)](https://github.com/playfab/gsdk). GSDK library is also used by [Azure PlayFab Multiplayer Servers (MPS)](https://docs.microsoft.com/gaming/playfab/features/multiplayer/servers/) service. In this way, you can easily migrate your game servers from MPS to Thundernetes and vice versa. Integrating with GSDK is required for your game server to run on Thundernetes. Integration serves two purposes: + - allows your game server process to communicate its state to Thundernetes (Initializing, StandingBy, Terminated) - allows Thundernetes to allocate your game server for a game session diff --git a/docs/gsdk/gameserverlifecycle.md b/docs/gsdk/gameserverlifecycle.md index 81680a38..fe9b6788 100755 --- a/docs/gsdk/gameserverlifecycle.md +++ b/docs/gsdk/gameserverlifecycle.md @@ -24,7 +24,7 @@ You can view the states of your GameServers by typing `kubectl get gs`. The stat - **Empty**: when the GameServer is created, the status is empty since we are waiting for the game server process to start and call the necessary GSDK methods. - **Initializing**: GameServer transitions to this state when it calls the **Start()** GSDK method. In this state, the game server should be starting to load the necessary assets. - **StandingBy**: GameServer transitions to this state when it calls the **ReadyForPlayers()** GSDK method. This state implies that the GameServer has loaded all the necessary assets and its ready for allocation. -- **Active**: GameServer transitions to this state when it is [allocated](../quickstart/allocation-scaling/md) by an external call to the allocation API service. Usually it's the responsibility of your matchmaker or lobby service to make this API call. This state implies that players can connect to the game server. When the server is in this state, it can never go back to the **Initializing** or **StandingBy** state. +- **Active**: GameServer transitions to this state when it is [allocated](../quickstart/allocation-scaling.md) by an external call to the allocation API service. Usually it's the responsibility of your matchmaker or lobby service to make this API call. This state implies that players can connect to the game server. When the server is in this state, it can never go back to the **Initializing** or **StandingBy** state. - **Terminated**: GameServer process can reach this state by terminating, either gracefully or via a crash. Thundernetes monitors all containers in the Pod you specify and will consider a termination of any of them as the termination of the game server. This can happen at any GameServer state. When this happens, Thundernetes will remove the Pod running this GameServer and will create a new one in its place, which will start from the **Empty** state. GameServer Pods in the Initializing or StandingBy state can be taken down during a cluster scale-down. Thundernetes makes every effort to prevent Active GameServer Pods from being taken down, since this would have the undesirable effect of breaking an existing game. Moreover, as mentioned, GameServer can never transition back to StandingBy state from Active state. The only way to get a new game server in StandingBy state is if the GameServer process exits. You should gracefully exit your game server process when the game session is done and the last connected player has exited the game. @@ -37,7 +37,7 @@ GameServer Pods in the Initializing or StandingBy state can be taken down during ## Verifying GSDK integration with your game server -You can use the open source tool **LocalMultiplayerAgent** to test GSDK integration and maybe test the game server in your local environment. You can download it [here](https://github.com/PlayFab/MpsAgent) and you can check the docs [here](../howtos/runlocalmultiplayeragent.md) for more information. +You can use the open source tool **LocalMultiplayerAgent** to test GSDK integration and maybe test the game server in your local environment. You can download it [here](https://github.com/PlayFab/MpsAgent) and you can check the docs [here](./runlocalmultiplayeragent.md) for more information. ## GSDK samples diff --git a/docs/gsdk/gsdkfooter.md b/docs/gsdk/gsdkfooter.md index 7f035943..d7cab327 100644 --- a/docs/gsdk/gsdkfooter.md +++ b/docs/gsdk/gsdkfooter.md @@ -1,16 +1,16 @@ ### Testing with LocalMultiplayerAgent -You can use [LocalMultiplayerAgent](runlocalmultiplayeragent.md) to test your GSDK integration of your game server before uploading to Thundernetes. +You can use [LocalMultiplayerAgent](runlocalmultiplayeragent.html) to test your GSDK integration of your game server before uploading to Thundernetes. #### Other GSDK methods and callbacks There are some other GSDK methods you can use from your game server process: -- `GetGameServerConnectionInfo`: Returns the connection information for the GameServer. Usually, it should be the port that you have already defined in your Pod specification. It is **required** use this method if you want to use the [hostNetwork](../howtos/hostnetworking.md) option. -- `GetInitialPlayers`: Returns the IDs of the players that are expected to connect to the GameServer when it starts. It is set during the call to [the allocation service API](../quickstart/allocation-scaling.md). +- `GetGameServerConnectionInfo`: Returns the connection information for the GameServer. Usually, it should be the port that you have already defined in your Pod specification. It is **required** use this method if you want to use the [hostNetwork](../howtos/hostnetworking.html) option. +- `GetInitialPlayers`: Returns the IDs of the players that are expected to connect to the GameServer when it starts. It is set during the call to [the allocation service API](../quickstart/allocation-scaling.html). - `UpdateConnectedPlayers`: It updates the currently connected players to the GameServer. On the backend, Thundernetes updates the `GameServerDetail` Custom Resource with the new number and IDs of connected players. -- `GetConfigSettings`: Returns the current configuration settings for the GameServer. You can retrieve the [associated GameServerBuild metadata](../gameserverbuild.md) with this method. -- `GetLogsDirectory`: Returns the path to the directory for the GameServer logs. It is recommended to just send the logs to standard output/standard error streams, where you can use [a Kubernetes-native logging solution](../howtos/gameserverlogs.md) to grab them. +- `GetConfigSettings`: Returns the current configuration settings for the GameServer. You can retrieve the [associated GameServerBuild metadata](../gameserverbuild.html) with this method. +- `GetLogsDirectory`: Returns the path to the directory for the GameServer logs. It is recommended to just send the logs to standard output/standard error streams, where you can use [a Kubernetes-native logging solution](../howtos/gameserverlogs.html) to grab them. - `LogMessage`: Writes an entry to the log file. As mentioned, it is recommended to send your logs to standard output/standard error streams - `GetSharedContentDirectory`: Not used in Thundernetes - `RegisterMaintenanceCallback` (name might be slightly different depending on your environment): Used to determine the `Health` status of the GameServer diff --git a/docs/howtos/hostnetworking.md b/docs/howtos/hostnetworking.md index a24ce7d5..afaadec7 100644 --- a/docs/howtos/hostnetworking.md +++ b/docs/howtos/hostnetworking.md @@ -9,7 +9,7 @@ nav_order: 7 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 the [GSDK](gsdk/README.md) `GetGameServerConnectionInfo` method. +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 = "gameport"; diff --git a/docs/quickstart/allocation-scaling.md b/docs/quickstart/allocation-scaling.md index 2ef6944e..6eab4a39 100644 --- a/docs/quickstart/allocation-scaling.md +++ b/docs/quickstart/allocation-scaling.md @@ -7,7 +7,7 @@ nav_order: 4 # Allocate a game server -Allocating a GameServer will transition its state from "StandingBy" to "Active" and will unblock the "ReadyForPlayers" GSDK call. You can read [the gameserver lifecycle document](../gameserverlifecycle.md) to learn more about the lifecycle of a GameServer. +Allocating a GameServer will transition its state from "StandingBy" to "Active" and will unblock the "ReadyForPlayers" GSDK call. You can read [the gameserver lifecycle document](../gsdk/gameserverlifecycle.md) to learn more about the lifecycle of a GameServer. If you are running Thundernetes on a cloud service like Azure Kubernetes Service, you can use the following commands to allocate a game server (below is using [Windows Subsystem for Linux](https://docs.microsoft.com/windows/wsl/install)