diff --git a/docs/en/FAQ/FAQ.md b/docs/en/FAQ/FAQ.md new file mode 100644 index 00000000..51cb09b1 --- /dev/null +++ b/docs/en/FAQ/FAQ.md @@ -0,0 +1,16 @@ +## FAQ + +### Will a game server be deleted if a GameServer object is accidentally deleted? + +No. A game server is not deleted if a GameServer object is accidentally deleted. GameServer only records the state information about different O&M operations on a game server. If GameServer is deleted, another GameServer object that uses the default settings is created. In this case, your GameServer is recreated based on the default configurations of the game server template defined in GameServerSet. + + +### How do we better integrate the matching service and auto scaling to prevent players from being forced to log out? + +The service quality capability can be used to convert players' tasks of a game to the state of GameServer. The matching service perceives the state of GameServer and controls the number of replicas for the scale-in or scale-out. GameServerSet also determines the sequence of deletion based on the state of GameServer, thus achieving smooth logout. + + +### How do we use OpenKruiseGame in Massive Multiplayer Online Role-Playing Games (MMORPGs)? + +You can use OpenKruiseGame and KubeVela together to perform game server orchestration in complex scenarios. You can use GameServerSet to manage a single role server. + diff --git a/docs/en/getting_started/architecture.md b/docs/en/core_concepts/architecture.md similarity index 100% rename from docs/en/getting_started/architecture.md rename to docs/en/core_concepts/architecture.md diff --git a/docs/en/core_concepts/design_concept.md b/docs/en/core_concepts/design_concept.md new file mode 100644 index 00000000..87241a4e --- /dev/null +++ b/docs/en/core_concepts/design_concept.md @@ -0,0 +1,74 @@ +

+ +

+ +## Purpose of Open Source OpenKruiseGame + +I have been working on cloud-native services from Swarm to Kubernetes since 2015. The types of loads running on container clusters range from websites and API services in the early phase to transcoding and AI training later, and then to Metaverse, Web3, and graphical applications. We have witnessed how cloud-native technology is changing industries one by one. However, gaming is a very special industry. A large-scale game includes different roles such as gateways, platform servers, game servers, and matching services. Many game companies have performed cloud-native transformation on services such as platform servers and gateways. However, the containerization of game servers is relatively slow. After I talked with many game developers and O&M personnel, I have found that this situation is roughly attributable to the following key reasons: + +1. Replacing the deployment architecture of a running game server leads to an excessively high risk return ratio. +2. Some core features, such as game rolling update and merger and suspension of specified servers, are missing during cloud-native transformation of game servers. +2. We lack best practices and success stories on cloud-native transformation of game servers. + +To solve the above problems, we have joined forces with a number of game companies such as Lingxi Games, abstracted the general capabilities for cloud-native transformation of game servers, and developed the open source project OpenKruiseGame. We hope to deliver best practices on cloud-native transformation of game servers to more game developers in an open source project that is independent of all cloud vendors. We also hope that more and more game companies, studios, and developers can join the community, discussing practical problems and scenarios with others and sharing experience in cloud-native transformation of game servers. +

Liu Zhongwei, initiator of the OpenKruiseGame project, Alibaba Cloud Container Service for Kubernetes(ACK)

+ +Lingxi Games has fully embraced cloud-native architecture. In the process of cloud-native transformation, we have clearly realized that game servers are different from other Web applications, and game server management in Kubernetes clusters is very complex. The management feature provided by Kubernetes-native workloads can hardly meet the daily O&M requirements of game servers. Deployment cannot generate fix IDs and thus is not appropriate for StatefulSet features. Whereas, StatefulSet cannot perform management on specified game servers flexibly. To overcome these difficulties, we have developed Platform as a Service (PaaS), which provides game server orchestration and management features to realize efficient O&M actions such as server activation and updates. + +

Feng Moujie, head of Lingxi Games Container Cloud, Alibaba Group

+ +As a large-scale game distribution platform, Bilibili has a large number of internal and external game projects with a heterogeneous architecture, and these projects need to be managed and maintained. In the context of reducing cost and enhancing efficiency, it is imperative to migrate game projects from traditional virtual machines to Kubernetes. However, the native Kubernetes is relatively weak in the face of scenarios such as game rolling updates, multi-environment management, abstraction of partition servers for roll server games, and service access to Internet traffic. A low-cost and efficient cross-cloud solution is required to improve the preceding situation. OpenKruiseGame is developed based on OpenKruise and provides features such as fixed ID and in-place upgrade which are appealing to gaming scenarios. This offers an alternative choice for the containerization of game servers. + +

Li Ning, head of Game O&M Team, Bilibili

+ + +When you try to perform cloud-native transformation of game servers, take network conditions as your primary concern. As game servers are migrated from virtual machines to containers, fixed IP addresses are required to ensure that the machine IP-based O&M method works in Kubernetes. The external service mode also becomes more complex, because it is no longer as simple as exposing ports on virtual machines. Besides, the state of each process of a game server in the pod can hardly be perceived. The recreation policy of native Kubernetes affects the game stability. Therefore, a specific perception policy is required for you to take different actions for different detection results. + +

Sheng Hao, head of Game Cloud Platform, Guanying Mutual Entertainment

+ +## Why is OpenKruiseGame a workload? + +

+ +

+ + +The key to cloud-native transformation of game servers is to address two concerns: lifecycle management and O&M management of game servers. Kubernetes has built-in general workload models such as Deployment, StatefulSet, and Job. However, the management of game server states is more fine-grained and more precise. For example, for game servers, a rolling update mechanism is required to ensure a shorter game interruption, and in-place updates are required to ensure that the network-based metadata information remains unchanged. A mechanism to ensure logouts occur only in zero-player game servers during auto scaling and the capability to allow to manually perform O&M, diagnosis, and isolation on game servers are required. The preceding requirements cannot be met by using only the built-in workloads of Kubernetes. + +The workloads in Kubernetes also act as an important hub for seamless integration with infrastructure. For example, you can use the Annotations fields to implement automatic connection of the monitoring system and log system to applications, use the nodeSelector field to schedule underlying resources and bind applications to these resources, and use the labels fields to record metadata information such as groups so as to replace the traditional Configuration Management Database (CMDB) system. Therefore, custom workloads are suitable for different types of applications in Kubernetes. OpenKruiseGame is a Kubernetes workload that is designed for gaming scenarios and allows developers to perform better lifecycle management and O&M management of game servers. Moreover, developers can make advantages of capabilities of cloud products by using OpenKruiseGame without the need to develop any additional code. + +## Design concept of OpenKruiseGame + +OpenKruiseGame consists of only two CustomResourceDefinition (CRD) objects: GameServerSet and GameServer. The design concept of OpenKruiseGame is based on state control, which divides different responsibilities into different workloads for control. + +* GameServerSet (lifecycle management) + Refers to the abstraction of lifecycle management for a group of game servers. It is mainly used for lifecycle control such as replica number management and game server launch. + +* GameServer (management and O&M operations on specified game servers) + Refers to the abstraction of O&M and management operations on a specified game server. It is mainly used for O&M and management operations such as update sequence control, state control of the game server, and network changes of the game server. + +After understanding the design concept of OpenKruiseGame, you can quickly draw some interesting inferences. Here are some examples: + +* Will a game server be deleted if a GameServer object is accidentally deleted? + +No. A game server is not deleted if a GameServer object is accidentally deleted. GameServer only records the state information about different O&M operations on a game server. If GameServer is deleted, another GameServer object that uses the default settings is created. In this case, your GameServer is recreated based on the default configurations of the game server template defined in GameServerSet. + +* How do we better integrate the matching service and auto scaling to prevent players from being forced to log out? + +The service quality capability can be used to convert players' tasks of a game to the state of GameServer. The matching service perceives the state of GameServer and controls the number of replicas for the scale-in or scale-out. GameServerSet also determines the sequence of deletion based on the state of GameServer, thus achieving smooth logout. + +## Deployment architecture of OpenKruiseGame + +

+ +

+The deployment model of OpenKruiseGame consists of three parts: + +1. OpenKruiseGame controller + It performs lifecycle management of GameServerSet and GameServer. OpenKruiseGame controller has a built-in Cloud Provider module to adapt to the differences of different cloud service providers in scenarios such as network plug-ins. This allows OpenKruiseGame to universally deploy a set of codes for all scenarios. + +2. OpenKruise controller + It performs lifecycle management of pods. It is a dependent component of OpenKruiseGame and the OpenKruiseGame users and developers do not need to manage the controller. + +3. OpenKruiseGame O&M console [to be built] + It provides the O&M console and APIs for developers who want to use OpenKruiseGame in a visualized way. It allows you to perform lifecycle management and orchestration on game servers. diff --git a/docs/en/developer_manuals/contribution.md b/docs/en/developer_manuals/contribution.md new file mode 100644 index 00000000..3e07bc57 --- /dev/null +++ b/docs/en/developer_manuals/contribution.md @@ -0,0 +1,29 @@ +## Contribute to OpenKruiseGame +Welcome to the OpenKruiseGame community. Feel free to offer assistance, report issues, improve document quality, fix bugs, or introduce new features. See below for details about how to submit content to OpenKruiseGame. + +## Submit issues and participate in scenario-based discussions +OpenKruiseGame is a very open community. Feel free to submit various types of issues. The following list shows the issue types: +* bug report +* feature request +* performance issues +* feature proposal +* feature design +* help wanted +* doc incomplete +* test improvement +* any questions on project + + +When you submit an issue, make sure that you have performed data masking to ensure the confidentiality of your information such as AccessKey. +## Contribute to codes and documents +Actions that can offer help to OpenKruiseGame are worth encouraging. You can submit what you expect to fix in a pull request. +* If you find a spelling error, fix it. +* If you find a code error, fix it. +* If you find the missing unit tests, fix the issue. +* If you find a document incomplete or with errors, update it. + +## Need additional help +If you need help on other types of problems during cloud-native transformation of game servers, email us for further help. Email: zhongwei.lzw@alibaba-inc.com + +## Become a core contributor to OpenKruiseGame +You are also very welcome to participate in OpenKruiseGame meetings to jointly determine the future development of OpenKruiseGame. As a sub-project of OpenKruise, OpenKruiseGame is also discussed in our bi-weekly meetings when we discuss about OpenKruise. For more information, see Schedule. \ No newline at end of file diff --git a/docs/en/getting_started/deploy_gameservers.md b/docs/en/getting_started/deploy_gameservers.md new file mode 100644 index 00000000..ccd73737 --- /dev/null +++ b/docs/en/getting_started/deploy_gameservers.md @@ -0,0 +1,41 @@ +You can use GameServerSet to deploy game servers. A simple deployment case is as follows: + +```bash +cat <= 1.16 -## Install manually +## Install Kruise -### 0. Edit Makefile, changing {IMG} +We recommend that you use Helm V3.5 or later to install Kruise. -### 1. Build docker image with the kruise-game controller manager. ```shell -make docker-build +# Firstly add openkruise charts repository if you haven't do this. +$ helm repo add openkruise https://openkruise.github.io/charts/ + +# [Optional] +$ helm repo update + +# Install the latest version. +$ helm install kruise openkruise/kruise --version 1.3.0 --set featureGates="PodProbeMarkerGate=true" ``` -### 2. Push docker image with the kruise-game controller manager. +## Install Kruise-Game + +### Method 1: Helm + ```shell -make docker-push +$ helm install kruise-game openkruise/kruise-game --version 0.2.0 ``` -### 3. Deploy kruise-game controller manager to the K8s cluster. -```shell -make deploy +### Method 2: Compile & Deploy with Yaml + +0) Edit Makefile. Change the value of the IMG field to the repository address of Makefile. + +1) Compile and package the images of kruise-game-manager. + +```bash +make docker-build ``` -## Uninstall manually -```shell -make undeploy +2) Upload the packaged image to the image repository. + +```bash +make docker-push ``` +3) Deploy the kruise-game-manager component in a Kubernetes cluster (~/.kube/conf). + +```bash +make deploy +``` diff --git a/docs/en/getting_started/introduction.md b/docs/en/getting_started/introduction.md deleted file mode 100644 index 794935f0..00000000 --- a/docs/en/getting_started/introduction.md +++ /dev/null @@ -1,39 +0,0 @@ -# Introduction - -## What is Kruise-Game? -Kruise-Game is a subproject of OpenKruise, to solve the problem of game server landing in Kubernetes. - -OpenKruiseGame logo - -Kruise-Game utilizes the features of [Kruise](https://github.com/openkruise/kruise), including: -- In-Place Update -- Update sequence -- Ordinals reserve(skip) -- Pod probe marker -- … - -## Why is Kruise-Game? -Game servers are stateful services, and there are differences in the operation and maintenance of each game server, which also increases with time. In Kubernetes, general workloads manages a batch of game servers according to pod templates, which cannot take into account the differences in game server status. Batch management and directional management are in conflict in k8s. **Kruise-Game** was born to resolve that. Kruise-Game contains two CRDs, GameServer and GameServerSet: - -- `GameServer` is responsible for the management of game server status. Users can customize the game server status to reflect the differences between game servers; -- `GameServerSet` is responsible for batch management of game servers. Users can customize update/reduction strategies according to the status of game servers. - -## Features -- Game server status management - - Mark game servers status without effecting to its lifecycle -- Flexible scaling/deletion mechanism - - Support scaling down by user-defined status & priority - - Support specifying game server to delete directly -- Flexible update mechanism - - Support hot update (in-place update) - - Support updating game server by user-defined priority - - Can control the range of the game servers to be updated - - Can control the pace of the entire update process -- Custom service quality - - Support probing game servers‘ containers and mark game servers status automatically - -## What's Next -Here are some recommended next steps: - -- Start to [Install kruise-game](installation.md). -- Learn Kruise-Game's [Basic Usage](../tutorials/basic_usage.md). \ No newline at end of file diff --git a/docs/en/introduction.md b/docs/en/introduction.md new file mode 100644 index 00000000..5213e7e6 --- /dev/null +++ b/docs/en/introduction.md @@ -0,0 +1,64 @@ +## kruise-game +[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html) +[![Go Report Card](https://goreportcard.com/badge/github.com/openkruise/kruise-game)](https://goreportcard.com/report/github.com/openkruise/kruise) +[![codecov](https://codecov.io/gh/openkruise/kruise-game/branch/master/graph/badge.svg)](https://codecov.io/gh/openkruise/kruise-game) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](./CODE_OF_CONDUCT.md) + +English | [Chinese](../中文/说明文档.md) +### Overview + +OpenKruiseGame (OKG) is a multicloud-oriented, open source Kubernetes workload specialized for game servers. It is a sub-project of the open source workload project OpenKruise of the Cloud Native Computing Foundation (CNCF) in the gaming field. OpenKruiseGame makes the cloud-native transformation of game servers easier, faster, and stabler. + +

+ +

+ +### What is OpenKruiseGame? +OpenKruiseGame is a custom Kubernetes workload designed specially for game server scenarios. It simplifies the cloud-native transformation of game servers. Compared with the built-in workloads of Kubernetes, such as Deployment and StatefulSet, OpenKruiseGame provides common game server management features, such as hot update, in-place update, and management of specified game servers. + +In addition, OpenKruiseGame connects game servers to cloud service providers, matchmaking services, and O&M platforms. It automatically integrates features such as logging, monitoring, network, storage, elasticity, and matching by using low-code or zero-code technologies during the cloud-native transformation of game servers. With the consistent delivery standard of Kubernetes, OpenKruiseGame implements centralized management of clusters on multiple clouds and hybrid clouds. + +OpenKruiseGame is a fully open source project. It allows developers to customize workloads and build the release and O&M platforms for game servers by using custom development. OpenKruiseGame can use Kubernetes templates or call APIs to use or extend features. It can also connect to delivery systems, such as KubeVela, to implement the orchestration and full lifecycle management of game servers on a GUI. + +### Why is OpenKruiseGame needed? + +Kubernetes is an application delivery and O&M standard in the cloud-native era. The capabilities of Kubernetes such as declarative resource management, auto scaling, and consistent delivery in a multi-cloud environment can provide support for game server scenarios that cover fast server activation, cost control, version management, and global reach. However, certain features of game servers make it difficult to adapt game servers for Kubernetes. For example: + +* Hot update or hot reload + +To ensure a better game experience for players, many game servers are updated by using hot update or hot reload. However, for various workloads of Kubernetes, the lifecycle of pods is consistent with that of images. When an image is published, pods are recreated. When pods are recreated, issues may occur such as interruptions to player battles and changes in the network metadata of player servers. + +* O&M for specified game servers + +Game servers are stateful in most scenarios. For example, when a player versus player (PVP) game is updated or goes offline, only game servers without online active players can be changed; when game servers for a player versus environment (PVE) game are suspended or merged, you can perform operations on game servers with specific IDs. + +* Network models suitable for games + +The network models in Kubernetes are implemented by declaring Services. In most cases, the network models are applicable to stateless scenarios. For network-sensitive game servers, a solution with high-performance gateways, fixed IP addresses and ports, or lossless direct connections is more suitable for actual business scenarios. + +* Game server orchestration + +The architecture of game servers has become increasingly complex. The player servers for many massive multiplayer online role-playing games (MMORPGs) are combinations of game servers with different features and purposes, such as a gateway server responsible for network access, a central server for running the game engine, and a policy server responsible for game scripts and gameplay. Different game servers have different capacities and management policies. Hence, it is difficult to describe and quickly deliver all the game servers by using a single workload type. + +The preceding challenges make it difficult to implement cloud-native transformation of game servers. OpenKruiseGame is aimed to abstract the common requirements of the gaming industry, and use the semantic method to make the cloud-native transformation of various game servers simple, efficient, and secure. + +### List of core features + +OpenKruiseGame has the following core features: + +* Hot update based on images and hot reload of configurations +* Update, deletion, and isolation of specified game servers +* Multiple built-in network models (fixed IP address and port, lossless direct connection, and global acceleration) +* Auto scaling +* Automated O&M (service quality) +* Independent of cloud service providers +* Complex game server orchestration + +### What to do next + +* Install and use OpenKruiseGame. For more information, see [Getting Started](./getting_started). +* Submit code for OpenKruiseGame. For more information, see [Developer Guide](./developer_manuals/contribution.md). +* Submit [issues](https://github.com/openkruise/kruise-game/issues) to offer suggestions for OpenKruiseGame or discuss the best practices of cloud-native transformation of games. +* Join the DingTalk group (ID: 44862615) to have a discussion with core contributors to OpenKruiseGame. +* Contact us by email at zhongwei.lzw@alibaba-inc.com. + diff --git a/docs/en/tutorials/basic_usage.md b/docs/en/user_manuals/basic_usage.md similarity index 100% rename from docs/en/tutorials/basic_usage.md rename to docs/en/user_manuals/basic_usage.md diff --git a/docs/en/user_manuals/network.md b/docs/en/user_manuals/network.md new file mode 100644 index 00000000..4094e7f1 --- /dev/null +++ b/docs/en/user_manuals/network.md @@ -0,0 +1,294 @@ +## Feature overview + +As mentioned in [Design concept of OpenKruiseGame](../core_concepts/design_concept.md), the access network of game servers is the main concern of game developers. +For a non-gateway architecture, game developers need to consider how to expose external IP addresses and ports of game servers for access by players. +Different network products are usually required for access in different scenarios, and the network products may be provided by different cloud service providers. This increases the complexity of the access network. Cloud Provider & Network Plugin of OpenKruiseGame is designed to resolve this issue. +OpenKruiseGame integrates different network plugins of different cloud service providers. You can use GameServerSet to set network parameters for game servers. Moreover, you can view network status information in the generated GameServer. This significantly reduces the complexity of the access network of game servers. + +## Example + +### HostPort + +OpenKruiseGame allows game servers to use the HostPort network in native Kubernetes clusters. The host where game servers are located exposes its external IP address and ports by using which Internet traffic is forwarded to the internal ports of the game servers. The following example shows the details: + +Deploy the GameServerSet object that contains the network field. + +``` +cat <English | 中文 +[英文](../en/introduction.md) | 中文 ### 概览 OpenKruiseGame(OKG)是一个面向多云的开源游戏服Kubernetes工作负载,是CNCF工作负载开源项目OpenKruise在游戏领域的子项目,让游戏服的云原生化变得更加简单、快速、稳定。