📝 Add README.md and README-JP.md

README-JP.md

@@ -0,0 +1,148 @@
+# Kuvel
+## 概要
+Kubernetesクラスター内のMinecraftサーバーを監視し、Velocityに自動で反映するVelocity Plugin
+
+## 機能
+* Kubernetesクラスターの中にあるMinecraftのPodを監視し、自動でVelocityに登録/登録解除する
+* LoadBalancerサーバーを作成し、そのサーバーに参加しようとしたプレイヤーを配下のサーバーに振り分ける
+* Redisを使用して、複数のVelocityで名前を同期する
+
+## 導入
+Pluginは [Releases](https://github.com/AzisabaNetwork/Kuvel/releases/latest) からダウンロードできます。 `Kuvel.jar` をダウンロードしVelocityに導入してください。
+
+Kuvelがサーバーを監視するためには、Kubernetesに対して権限を要求しなければなりません。VelocityのPodに対してPodとReplicaSetのget/list/watchを許可してください
+```yml
+ apiVersion: v1
+ kind: ServiceAccount
+ metadata:
+   name: velocity-account
+   namespace: default
+ ---
+ apiVersion: rbac.authorization.k8s.io/v1
+ kind: ClusterRoleBinding
+ metadata:
+   name: velocity-clusterrolebiding
+ roleRef:
+   apiGroup: rbac.authorization.k8s.io
+   kind: ClusterRole
+   name: view
+ subjects:
+ - kind: ServiceAccount
+   name: velocity-account
+   namespace: default
+ ```
+ ```yml
+# VelocityのPodに対して ServiceAccount を設定する
+apiVersion: apps/v1
+kind: ...
+# 略
+spec:
+  serviceAccountName: velocity-account
+# 略
+ ```
+
+## MinecraftサーバーのServiceDiscoveryを設定する
+PodがMinecraftサーバーであることをKuvelに示すには、Kubernetesのラベル機能を使用します
+|Label名|値|
+|:---:|:---:|
+|minecraftServiceDiscovery|true / false|
+|minecraftServerName|Velocityに登録したいサーバー名|
+
+### Podの場合
+```yml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: test-server
+  labels:
+    minecraftServiceDiscovery: "true" # KuvelがMinecraftサーバーを見つけるために必要
+    minecraftServerName: "test-server" # Kuvelがサーバーの命名をするために必要
+spec:
+  containers:
+  - name: test-server
+    image: itzg/minecraft-server:java8
+    ports:
+    - containerPort: 25565
+```
+
+### Deploymentの場合
+```yml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: test-server-deployment
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: test-server-deployment
+  template:
+    metadata:
+      labels:
+        app: test-server-deployment
+        minecraftServiceDiscovery: "true" # KuvelがMinecraftサーバーを見つけるために必要
+        minecraftServerName: "test-server" # Kuvelがサーバーの命名をするために必要
+    spec:
+      containers:
+        - name: test-server
+          image: itzg/minecraft-server:java8
+          ports:
+            - containerPort: 25565
+```
+
+どちらも`test-server` という名前でサーバーが登録されます。
+
+ただし、同じ名前が指定されたサーバーが2つ以上ある場合は、サーバー名の後ろに番号が付与されていきます。具体的にはサーバー名が `test-server` と指定されたPodが2つある場合、片方は `test-server`、もう片方は `test-server-1` となります。
+
+## ロードバランサー
+Lobby等の並列化可能なサーバーにおいて、出来る限り人数を分散したいことがあります。その時にKuvelのLoadBalancer機能が役に立ちます
+```yml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: lobby-deployment
+  labels:
+    minecraftServiceDiscovery: "true"
+    minecraftServerName: "lobby"
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: lobby-deployment
+  template:
+    metadata:
+      labels:
+        app: lobby-deployment
+        minecraftServiceDiscovery: "true"
+        minecraftServerName: "lobby"
+    spec:
+      containers:
+        - name: lobby
+          image: itzg/minecraft-server:java8
+          ports:
+            - containerPort: 25565
+```
+Deploymentに対してLabelを適用することで、KuvelのLoadBalancer機能を有効化することができます。KuvelのLoadBalancerは以下の機能を有しています
+
+1. ReplicaSet配下のPodに対し、ランダムに接続先を振り分けて転送する
+2. KubernetesのReplicaSetと同期し、自動で転送先を登録/登録解除する
+
+これを用いることにより、`/server lobby` を実行したときに `lobby-1`, `lobby-2`, `lobby-3`の中からランダムに接続するといった仕組みを実装できます
+
+## 複数Velocityでサーバー名を同期する
+Kubernetesクラスター内ではPodがほぼ同時に作成されることがある等の理由により、まれにVelocityによってサーバーの登録名が違うといった事が起こりえます。Velocityを並列化している環境では、この現象は致命的な問題を引き起こします。Kuvelはそれを回避するため、Redisによるサーバー名同期を実現しています。
+
+この機能を有効化するには、config.ymlで`redis.enable`を`true`に設定するだけです。Kuvelはキー名が `kuvel:` から始まるキーを使用します。
+```yml
+redis:
+  enable: true # trueにすることによりRedisによるサーバー名同期が有効化されます
+  group-name: "production" # Redisサーバーが同じかつgroup-nameが同じサーバー間でのみ名前同期が行われます
+  connection:
+    hostname: "localhost"
+    port: 6379
+    username: "root"
+    password: "password"
+```
+
+## ライセンス
+[GNU General Public License v3.0](LICENSE)

README.md

@@ -0,0 +1,154 @@
+# Kuvel
+## Overview
+Kuvel, A service discovery plugin for Velocity. It will automatically discover Minecraft servers and register/unregister them in Velocity.
+
+## Features
+
+* Monitor Minecraft pods in a Kubernetes cluster and automatically register/unregister them with Velocity
+* Create a LoadBalancer server and distribute players trying to join to the linked servers.
+* Synchronize server names across multiple Velocity servers using Redis
+
+## Installing
+
+The Plugin can be downloaded from [Releases](https://github.com/AzisabaNetwork/Kuvel/releases/latest). Download `Kuvel.jar` and install it into Velocity.
+
+In order for Kuvel to monitor the server, you must request permission from Kubernetes to allow Velocity pods discovery Minecraft servers. For Velocity pods, please allow get/list/watch to Pods and ReplicaSets.
+```yml
+ apiVersion: v1
+ kind: ServiceAccount
+ metadata:
+   name: velocity-account
+   namespace: default
+ ---
+ apiVersion: rbac.authorization.k8s.io/v1
+ kind: ClusterRoleBinding
+ metadata:
+   name: velocity-clusterrolebiding
+ roleRef:
+   apiGroup: rbac.authorization.k8s.io
+   kind: ClusterRole
+   name: view
+ subjects:
+ - kind: ServiceAccount
+   name: velocity-account
+   namespace: default
+ ```
+ ```yml
+# Apply ServiceAccount to the Velocity pod
+apiVersion: apps/v1
+kind: ...
+# ...
+spec:
+  serviceAccountName: velocity-account
+# ...
+ ```
+
+## Enable Service Discovery on the Minecraft Servers
+To tell Kuvel that the pod is a Minecraft server, use Label feature of Kubernetes.
+|Label Name| Value |
+|:---:|:---:|
+|minecraftServiceDiscovery|true / false|
+|minecraftServerName|Name of the server you wish to register with Velocity|
+
+### Pod
+```yml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: test-server
+  labels:
+    minecraftServiceDiscovery: "true" # Required for Kuvel to detect Minecraft servers.
+    minecraftServerName: "test-server" # Required for Kuvel to name the server
+spec:
+  containers:
+  - name: test-server
+    image: itzg/minecraft-server:java8
+    ports:
+    - containerPort: 25565
+```
+
+### Deployment
+```yml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: test-server-deployment
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: test-server-deployment
+  template:
+    metadata:
+      labels:
+        app: test-server-deployment
+        minecraftServiceDiscovery: "true" # Required for Kuvel to detect Minecraft servers.
+        minecraftServerName: "test-server" # Required for Kuvel to name the server
+    spec:
+      containers:
+        - name: test-server
+          image: itzg/minecraft-server:java8
+          ports:
+            - containerPort: 25565
+```
+
+In both cases, the server is registered under the name `test-server`.
+
+However, if there are two or more servers with the same name, a number will be assigned after the server name. Specifically, if there are two pods with the server name `test-server`, one will be `test-server` and the other will be `test-server-1`.
+
+## Load Balancer
+
+On parallelizable servers such as Lobby, it is sometimes desirable to distribute the number of players as much as possible. This is where Kuvel's LoadBalancer feature comes in handy.
+
+```yml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: lobby-deployment
+  labels:
+    minecraftServiceDiscovery: "true"
+    minecraftServerName: "lobby"
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: lobby-deployment
+  template:
+    metadata:
+      labels:
+        app: lobby-deployment
+        minecraftServiceDiscovery: "true"
+        minecraftServerName: "lobby"
+    spec:
+      containers:
+        - name: lobby
+          image: itzg/minecraft-server:java8
+          ports:
+            - containerPort: 25565
+```
+
+By applying a Label to a Deployment, Kuvel's LoadBalancer feature can be activated.
+
+1. Distribute players who try to join the Load Balancer server to the pods under ReplicaSet.
+2. Synchronize with Kubernetes ReplicaSet and automatically register/unregister forwarding destinations
+
+Using this, you can implement a mechanism to randomly connect to `lobby-1`, `lobby-2`, or `lobby-3` when `/server lobby` is invoked.
+
+## Synchronize Server Names in Multi Velocity Environment
+
+In a Kubernetes cluster, pods can be created at almost the same time, and this can cause a fatal problem in a parallel Velocity environment because it is possible that different Velocity servers have different registration names. Kuvel provides name synchronization using Redis to avoid this problem.
+
+To enable this feature, simply set `redis.enable` to `true` in config.yml. Kuvel uses keys whose key name begins with `kuvel:`.
+```yml
+redis:
+  enable: true # Setting it to true enables server name synchronization using Redis
+  group-name: "production" # Name synchronization is performed only between servers with the same Redis server and the same group-name
+  connection:
+    hostname: "localhost"
+    port: 6379
+    username: "root"
+    password: "password"
+```
+
+## License
+[GNU General Public License v3.0](LICENSE)