Feat: update docs(CN) (#19)

* add docs quick start(zh-cn)
This commit is contained in:
ChrisLiu 2022-11-28 16:37:52 +08:00 committed by GitHub
parent ed772a2052
commit 756b72f94d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 664 additions and 3 deletions

BIN
docs/images/hot-update.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 50 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

View File

@ -0,0 +1,38 @@
## 安装Kruise
建议采用 helm v3.5+ 来安装 Kruise
```shell
# 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"
```
## 安装Kruise-Game
### 编译安装
0) 编辑Makefile更改其中{IMG}字段,将其改为自身的仓库地址
1) 编译并打包kurise-game-manager镜像
```bash
make docker-build
```
2) 将打包完成的镜像上传至镜像仓库
```bash
make docker-push
```
3) 在Kubernetes集群~/.kube/conf部署kruise-game-manager组件
```bash
make deploy
```

View File

@ -0,0 +1,173 @@
## OpenKruiseGame的伸缩特性
OKG提供游戏服状态设置的能力您可以手动/自动(服务质量功能)地设置游戏服的运维状态或删除优先级。当缩容时GameServerSet负载会根据游戏服的状态进行缩容选择缩容规则如下
1根据游戏服的opsState缩容。按顺序依次缩容opsState为`WaitToBeDeleted`、`None`、`Maintaining`的游戏服
2当opsState相同时按照DeletionPriority(删除优先级)缩容优先删除DeletionPriority大的游戏服
3当opsState与DeletionPriority都相同时优先删除名称尾部序号较大的游戏服
### 示例
部署一个副本为5的游戏服
```bash
cat <<EOF | kubectl apply -f -
apiVersion: game.kruise.io/v1alpha1
kind: GameServerSet
metadata:
name: minecraft
namespace: default
spec:
replicas: 5
updateStrategy:
rollingUpdate:
podUpdatePolicy: InPlaceIfPossible
gameServerTemplate:
spec:
containers:
- image: registry.cn-hangzhou.aliyuncs.com/acs/minecraft-demo:1.12.2
name: minecraft
EOF
```
生成5个GameServer
```bash
kubectl get gs
NAME STATE OPSSTATE DP UP
minecraft-0 Ready None 0 0
minecraft-1 Ready None 0 0
minecraft-2 Ready None 0 0
minecraft-3 Ready None 0 0
minecraft-4 Ready None 0 0
```
对minecraft-2设置删除优先级为10
```bash
kubectl edit gs minecraft-2
...
spec:
deletionPriority: 10 #初始为0调大到10
opsState: None
updatePriority: 0
...
```
手动缩容到4个副本
```bash
kubectl scale gss minecraft --replicas=4
gameserverset.game.kruise.io/minecraft scale
```
游戏服的数目最终变为4可以看到2号游戏服因为删除优先级最大所以被删除
```bash
kubectl get gs
NAME STATE OPSSTATE DP UP
minecraft-0 Ready None 0 0
minecraft-1 Ready None 0 0
minecraft-2 Deleting None 10 0
minecraft-3 Ready None 0 0
minecraft-4 Ready None 0 0
# After a while
...
kubectl get gs
NAME STATE OPSSTATE DP UP
minecraft-0 Ready None 0 0
minecraft-1 Ready None 0 0
minecraft-3 Ready None 0 0
minecraft-4 Ready None 0 0
```
设置minecraft-3的opsState为WaitToBeDeleted
```bash
kubectl edit gs minecraft-3
...
spec:
deletionPriority: 0
opsState: WaitToBeDeleted #初始为None, 将其改为WaitToBeDeleted
updatePriority: 0
...
```
手动缩容到3个副本
```bash
kubectl scale gss minecraft --replicas=3
gameserverset.game.kruise.io/minecraft scaled
```
游戏服的数目最终变为3可以看到3号游戏服因为处于WaitToBeDeleted状态所以被删除
```bash
kubectl get gs
NAME STATE OPSSTATE DP UP
minecraft-0 Ready None 0 0
minecraft-1 Ready None 0 0
minecraft-3 Deleting WaitToBeDeleted 0 0
minecraft-4 Ready None 0 0
# After a while
...
kubectl get gs
NAME STATE OPSSTATE DP UP
minecraft-0 Ready None 0 0
minecraft-1 Ready None 0 0
minecraft-4 Ready None 0 0
```
手动扩容回5个副本
```bash
kubectl scale gss minecraft --replicas=5
gameserverset.game.kruise.io/minecraft scaled
```
游戏服的数目最终变为5此时扩容出的游戏服序号为2与3
```bash
kubectl get gs
NAME STATE OPSSTATE DP UP
minecraft-0 Ready None 0 0
minecraft-1 Ready None 0 0
minecraft-2 Ready None 0 0
minecraft-3 Ready None 0 0
minecraft-4 Ready None 0 0
```
## 配置游戏服的自动伸缩
GameServerSet支持HPA您可以通过默认/自定义指标配置
### HPA示例
```yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: minecraft-hpa
spec:
scaleTargetRef:
apiVersion: game.kruise.io/v1alpha1
kind: GameServerSet
name: minecraft # GameServerSet对应名称
minReplicas: 1
maxReplicas: 10
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 50 # 示例以cpu利用率50%为计算标准
```

View File

@ -0,0 +1,71 @@
## 功能概述
在游戏场景下游戏服脚本、场景资源等属于热更文件时常以sidecar的形式部署在pod中。
在更新这些文件时,我们往往希望不影响主程序(游戏服引擎侧)的正常运行。
然而在原生Kubernetes集群更新pod中任意容器都会导致pod重建无法满足游戏热更场景。
OKG 提供的原地升级能力可以针对性定向更新pod中某一个容器不影响整个pod的生命周期。
如下图所示蓝色部分为热更部分橘色部分为非热更部分。我们将Game Script容器从版本V1更新至版本V2后整个pod不会重建橘色部分不受到任何影响Game Engine正常平稳运行
![hot-update.png](../../images/hot-update.png)
## 使用示例
部署带有sidecar容器的游戏服使用GameServerSet作为游戏服负载pod更新策略选择原地升级
```bash
cat <<EOF | kubectl apply -f -
apiVersion: game.kruise.io/v1alpha1
kind: GameServerSet
metadata:
name: minecraft
namespace: default
spec:
replicas: 3
updateStrategy:
rollingUpdate:
podUpdatePolicy: InPlaceIfPossible
gameServerTemplate:
spec:
containers:
- image: registry.cn-hangzhou.aliyuncs.com/acs/minecraft-demo:1.12.2
name: minecraft
- image: registry.cn-hangzhou.aliyuncs.com/gs-demo/sidecar:v0.1
name: sidecar
EOF
```
生成3个GameServer以及对应的3个Pod
```bash
kubectl get gs
NAME STATE OPSSTATE DP UP
minecraft-0 Ready None 0 0
minecraft-1 Ready None 0 0
minecraft-2 Ready None 0 0
kubectl get pod
NAME READY STATUS RESTARTS AGE
minecraft-0 2/2 Running 0 13s
minecraft-1 2/2 Running 0 13s
minecraft-2 2/2 Running 0 13s
```
当产生热更需求我们希望只更新sidecar容器而不影响整个pod的生命周期此时只需更新GameServerSet对应的容器镜像版本即可
```bash
kubectl edit gss minecraft
...
- image: registry.cn-hangzhou.aliyuncs.com/gs-demo/sidecar:v0.2
name: sidecar
...
```
一段时间过后发现Pod已经更新完毕restarts次数变为1但Age并没有减少。游戏服完成了热更新
```bash
kubectl get pod
NAME READY STATUS RESTARTS AGE
minecraft-0 2/2 Running 1 (33s ago) 8m55s
minecraft-1 2/2 Running 1 (37s ago) 8m54s
minecraft-2 2/2 Running 1 (49s ago) 8m54s
```

View File

@ -0,0 +1,41 @@
您可以使用GameServerSet进行游戏服的部署一个简单的部署案例如下
```bash
cat <<EOF | kubectl apply -f -
apiVersion: game.kruise.io/v1alpha1
kind: GameServerSet
metadata:
name: minecraft
namespace: default
spec:
replicas: 3
updateStrategy:
rollingUpdate:
podUpdatePolicy: InPlaceIfPossible
gameServerTemplate:
spec:
containers:
- image: registry.cn-hangzhou.aliyuncs.com/acs/minecraft-demo:1.12.2
name: minecraft
EOF
```
当前GameServerSet创建完成后由于指定的副本数为3故在集群中将会出现3个GameServer以及对应的3个Pod
```bash
kubectl get gss
NAME AGE
minecraft 9s
kubectl get gs
NAME STATE OPSSTATE DP UP
minecraft-0 Ready None 0 0
minecraft-1 Ready None 0 0
minecraft-2 Ready None 0 0
kubectl get pod
NAME READY STATUS RESTARTS AGE
minecraft-0 1/1 Running 0 10s
minecraft-1 1/1 Running 0 10s
minecraft-2 1/1 Running 0 10s
```

View File

@ -0,0 +1,83 @@
## 功能概述
OKG 提供了原地升级([热更新](../快速开始/游戏服热更新.md))、批量更新、按优先级更新等多种更新策略。
用户可设置GameServer的更新优先级配合partition参数实现在实际生产场景下把控更新范围、更新顺序、更新节奏。
如下图所示提高序号为1的游戏服优先级同时设置partition为2则会优先更新1号游戏服随后更改partition为0则会再更新其余游戏服。详情可参考使用示例。
![update-priority.png](../../images/update-priority.png)
## 使用示例
本示例中将一组游戏服分成两批次更新,模拟灰度更新,逐步验证的场景。
此时GameServerSet下有3个游戏服副本
```shell
kubectl get gs
NAME STATE OPSSTATE DP UP
gs-demo-0 Ready None 0 0
gs-demo-1 Ready None 0 0
gs-demo-2 Ready None 0 0
```
设置更新优先级将3号游戏服优先级调大
```shell
kubectl edit gs gs-demo-1
...
spec:
deletionPriority: 0
opsState: None
updatePriority: 10 #初始为0调大成10
...
```
接下来设置 GameServerSet partition、以及即将更新的新镜像
```shell
kubectl edit gss gs-demo
...
image: gameserver:latest # 更新镜像
name: gameserver
...
updateStrategy:
rollingUpdate:
maxUnavailable: 5
partition: 2 # 设置保留的游戏服数目这里只更新一个所以要保留余下2个
podUpdatePolicy: InPlaceIfPossible
...
```
此时只有gs-demo-3将会更新:
```shell
kubectl get gs
NAME STATE OPSSTATE DP UP
gs-demo-0 Ready None 0 0
gs-demo-1 Updating None 0 10
gs-demo-2 Ready None 0 0
# 一段时间过后
...
kubectl get gs
NAME STATE OPSSTATE DP UP
gs-demo-0 Ready None 0 0
gs-demo-1 Ready None 0 10
gs-demo-2 Ready None 0 0
```
待gs-demo-3验证通过后更新其余游戏服
```shell
kubectl edit gss gs-demo
...
updateStrategy:
rollingUpdate:
maxUnavailable: 5
partition: 0 # 设置保留的游戏服数目将其设置为0更新余下全部
podUpdatePolicy: InPlaceIfPossible
...
```

View File

@ -0,0 +1,128 @@
## 功能概述
如[OKG设计理念](../核心概念/OpenKruiseGame的设计理念.md)中提到的,游戏服接入层网络是游戏开发者非常关注的问题。
非网关架构下游戏开发者需要考虑如何暴露游戏服的外部IP端口供玩家连接访问。
在不同场景下往往需要不同的网络产品而有时网络产品由云厂商提供。OKG 的 Cloud Provider & Network Plugin 源于此而诞生。
OKG 会集成不同云提供商的不同网络插件用户可通过GameServerSet设置游戏服的网络参数并在生成的GameServer中查看网络状态信息极大降低了游戏服接入网络的复杂度。
## 使用示例
### HostPort
OKG支持在原生Kubernetes集群使用HostPort游戏服网络使用游戏服所在宿主机暴露外部IP及端口转发至游戏服内部端口中。使用方式如下。
部署一个带有network的GameServerSet
```
cat <<EOF | kubectl apply -f -
apiVersion: game.kruise.io/v1alpha1
kind: GameServerSet
metadata:
name: gs-hostport
namespace: default
spec:
replicas: 1
updateStrategy:
rollingUpdate:
podUpdatePolicy: InPlaceIfPossible
network:
networkType: HostPortNetwork
networkConf:
#网络配置以k-v键值对的形式传入由网络插件指定。不同网络插件有着不同的网络配置
- name: ContainerPorts
#ContainerPorts对应的值格式如下{containerName}:{port1}/{protocol1},{port2}/{protocol2},...
value: "gameserver:80"
gameServerTemplate:
spec:
containers:
- image: registry.cn-hangzhou.aliyuncs.com/gs-demo/gameserver:network
name: gameserver
EOF
```
生成的GameServer中通过networkStatus字段查看游戏服网络信息
```shell
networkStatus:
createTime: "2022-11-23T10:57:01Z"
currentNetworkState: Ready
desiredNetworkState: Ready
externalAddresses:
- ip: 48.98.98.8
ports:
- name: gameserver-80
port: 8211
protocol: TCP
internalAddresses:
- ip: 172.16.0.8
ports:
- name: gameserver-80
port: 80
protocol: TCP
lastTransitionTime: "2022-11-23T10:57:01Z"
networkType: HostPortNetwork
```
访问 48.98.98.8:8211 即可
### Ali-NatGw
OKG支持阿里云下NAT网关模型使用NATGW的外部IP与端口暴露服务流量最终将转发至Pod之中。使用方式如下
```shell
cat <<EOF | kubectl apply -f -
apiVersion: game.kruise.io/v1alpha1
kind: GameServerSet
metadata:
name: gs-natgw
namespace: default
spec:
replicas: 1
updateStrategy:
rollingUpdate:
podUpdatePolicy: InPlaceIfPossible
network:
networkType: Ali-NatGw
networkConf:
- name: Ports
#暴露的端口,格式如下 {port1},{port2}...
value: "80"
- name: Protocol
#使用的协议默认为TCP
value: "TCP"
# - name: Fixed
# 是否固定映射关系默认不固定pod删除后会生成新的外部IP及端口
# value: true
gameServerTemplate:
spec:
containers:
- image: registry.cn-hangzhou.aliyuncs.com/gs-demo/gameserver:network
name: gameserver
EOF
```
生成的GameServer中通过networkStatus字段查看游戏服网络信息
```shell
networkStatus:
createTime: "2022-11-23T11:21:34Z"
currentNetworkState: Ready
desiredNetworkState: Ready
externalAddresses:
- ip: 47.97.227.137
ports:
- name: "80"
port: "512"
protocol: TCP
internalAddresses:
- ip: 172.16.0.189
ports:
- name: "80"
port: "80"
protocol: TCP
lastTransitionTime: "2022-11-23T11:21:34Z"
networkType: Ali-NatGw
```
访问 47.97.227.137:512 即可

View File

@ -0,0 +1,127 @@
## 功能概述
由于游戏是有状态服务,很多时候游戏服是以一种 "富容器" 的形态存在于Pod之中多个进程在Pod中统一管理。
然而,每个进程重要性却有所不同,对于"轻量级进程"错误的情况用户并不希望将整个pod删除重建像k8s原生的liveness probe并不能很好地满足这种需求过于僵化的模式与游戏场景并不适配。
OKG 认为游戏服的服务质量水平应该交由游戏开发者定义,开发者可以根据不同游戏服状态去设置对应的处理动作。自定义服务质量功能是探测+动作的组合,通过这种方式帮助用户自动化地处理各类游戏服状态问题。
## 使用示例
### 游戏服空闲设置即将下线
部署一个带有自定义服务质量的GameServerSet
```shell
cat <<EOF | kubectl apply -f -
apiVersion: game.kruise.io/v1alpha1
kind: GameServerSet
metadata:
name: minecraft
namespace: default
spec:
replicas: 3
gameServerTemplate:
spec:
containers:
- image: registry.cn-hangzhou.aliyuncs.com/gs-demo/gameserver:idle
name: minecraft
updateStrategy:
rollingUpdate:
podUpdatePolicy: InPlaceIfPossible
maxUnavailable: 100%
serviceQualities: # 设置了一个idle的服务质量
- name: idle
containerName: minecraft
permanent: false
#与原生probe类似,本例使用执行脚本的方式探测游戏服是否空闲,不存在玩家
exec:
command: ["bash", "./idle.sh"]
serviceQualityAction:
#不存在玩家标记该游戏服运维状态为WaitToBeDeleted
- state: true
opsState: WaitToBeDeleted
#存在玩家标记该游戏服运维状态为None
- state: false
opsState: None
EOF
```
部署完成后,由于还未导入玩家,故所有游戏服都为空闲状态,可以任意被删除:
```shell
kubectl get gs
NAME STATE OPSSTATE DP UP
minecraft-0 Ready WaitToBeDeleted 0 0
minecraft-1 Ready WaitToBeDeleted 0 0
minecraft-2 Ready WaitToBeDeleted 0 0
```
当有玩家进入游戏服minecraft-1则游戏服的运维状态发生变化
```shell
kubectl get gs
NAME STATE OPSSTATE DP UP
minecraft-0 Ready WaitToBeDeleted 0 0
minecraft-1 Ready None 0 0
minecraft-2 Ready WaitToBeDeleted 0 0
```
此时若发生缩容游戏服minecraft-1将得到保护避免优先删除。
### 游戏服状态异常设置维护中
部署一个带有自定义服务质量的GameServerSet
```shell
cat <<EOF | kubectl apply -f -
apiVersion: game.kruise.io/v1alpha1
kind: GameServerSet
metadata:
name: demo-gs
namespace: default
spec:
replicas: 3
gameServerTemplate:
spec:
containers:
- image: registry.cn-hangzhou.aliyuncs.com/gs-demo/gameserver:healthy
name: minecraft
updateStrategy:
rollingUpdate:
podUpdatePolicy: InPlaceIfPossible
maxUnavailable: 100%
serviceQualities: # 设置了一个idle的服务质量
- name: idle
containerName: minecraft
permanent: false
#与原生probe类似,本例使用执行脚本的方式探测游戏服是否健康
exec:
command: ["bash", "./healthy.sh"]
serviceQualityAction:
#探测健康标记该游戏服运维状态为None
- state: true
opsState: None
#探测不健康标记该游戏服运维状态为Maintaining
- state: false
opsState: Maintaining
EOF
```
部署完成后由于一切正常故所有游戏服都为None
```shell
kubectl get gs
NAME STATE OPSSTATE DP UP
demo-gs-0 Ready None 0 0
demo-gs-1 Ready None 0 0
demo-gs-2 Ready None 0 0
```
模拟demo-gs-0某进程宕机游戏服变为Maintaining状态
```shell
kubectl get gs
NAME STATE OPSSTATE DP UP
demo-gs-0 Ready Maintaining 0 0
demo-gs-1 Ready None 0 0
demo-gs-2 Ready None 0 0
```
此时gameserver controller会发出 GameServer demo-gs-0 Warning 的 event配合[kube-event项目](https://github.com/AliyunContainerService/kube-eventer)可实现异常通知:
![](../../images/warning-ding.png)
此外OKG 未来会集成游戏服自动排障/恢复工具,进一步丰富游戏服的自动化运维能力。

View File

@ -56,9 +56,9 @@ OpenKruiseGameOKG具有如下核心能力
### 进行下一步
* 查看快速开始安装并体验OpenKruiseGame。
* 查看开发指南为OpenKruiseGame(OKG)提交代码。
* 提交<a href="docs/中文/开发者手册/如何贡献代码.md">Issue</a>给OpenKruiseGame提建议或者讨论游戏云原生化的最佳实践。
* 查看[快速开始](./快速开始)安装并体验OpenKruiseGame。
* 查看[开发指南](./开发者手册/如何贡献代码.md)为OpenKruiseGame(OKG)提交代码。
* 提交[Issue](https://github.com/openkruise/kruise-game/issues)给OpenKruiseGame提建议或者讨论游戏云原生化的最佳实践。
* 加入钉钉群44862615在线和OpenKruiseGame(OKG)的核心贡献者讨论。
* 发送E-mail联系我们。邮箱地址zhongwei.lzw@alibaba-inc.com。