diff --git a/docs/docs/02-getting-started/01-prerequisites.md b/docs/docs/02-getting-started/01-prerequisites.md index 46edf0a6..ae0cda13 100644 --- a/docs/docs/02-getting-started/01-prerequisites.md +++ b/docs/docs/02-getting-started/01-prerequisites.md @@ -11,11 +11,11 @@ the following criterias: :::note -By default, any **ProxyDeployment** created will create automatically -a Kubernetes Service with the `LoadBalancer` kind. For this behavior -to work properly, your cloud provider should support load balancer -provisionning. While this is a non-issue for almost all cloud providers, -it may be one if you are self-provisionning your own Kubernetes Cluster. +By default, any `ProxyFleet` will create automatically a Kubernetes Service +of `LoadBalancer` kind. For this behavior to work properly, your cloud provider +should support load balancer provisioning. While this is a non-issue for +almost all cloud providers, it may be one if you are self-provisioning your +own Kubernetes Cluster. ::: @@ -31,12 +31,34 @@ prevent some pods to schedule properly. All Shulker components should be installed in the same namespace, `shulker-system` by default. -## Third-party softwares +## Mandatory softwares -In addition to a working Kubernetes Cluster, **[cert-manager](https://cert-manager.io/)** -is also required to be installed. It will be used to generate self-signed -certificates for internal use (mostly to secure internal communication -with Kubernetes's controle plane). +### Cert-Manager + +Cert-Manager will be used to generate self-signed certificates for internal +use (mostly to secure internal communication between Shulker components and +Kubernetes's control plane). + +- Website: https://cert-manager.io/ +- Installation guide: https://cert-manager.io/docs/installation/ + +### Agones + +Shulker delegates the management of game servers (proxies and servers) to +Agones. + +- Website: https://agones.dev/site/ +- Installation guide: https://agones.dev/site/docs/installation/ + +:::warning + +Watch out that while Shulker does not need heavy scaling to handle +production workload, Agones sure does. Please consider your needs when +installing and configuring Agones. + +::: + +## Optional softwares **[Prometheus](https://github.com/prometheus-operator/prometheus-operator)** metrics are also exposed by some components. Monitor manifests can be diff --git a/docs/docs/02-getting-started/03-your-first-cluster.mdx b/docs/docs/02-getting-started/03-your-first-cluster.mdx index de277a99..684fce35 100644 --- a/docs/docs/02-getting-started/03-your-first-cluster.mdx +++ b/docs/docs/02-getting-started/03-your-first-cluster.mdx @@ -43,10 +43,9 @@ for the _main course_. ## A _drizzle_ of Proxy For the players to be able to connect to our Minecraft Cluster, we need -at least one **Proxy**. While we could directly create a **Proxy** resource, -we will create a **ProxyDeployment** instead. It will handle replication -among other things, but more importantly, it will create and bind a -**Kubernetes Service** for us, with the `LoadBalancer` type by default. +at least one **Proxy**. So let's create a `ProxyFleet`. It will handle +replication among other things, but more importantly, it will create and +bind a **Kubernetes Service** for us, with the `LoadBalancer` type by default. :::note @@ -101,7 +100,7 @@ no player, it will shutdown itself, otherwise it will wait. It is important to note that a new Proxy is automatically created when one enters the **Drain** mode, to ensure the availability of the -**ProxyDeployment**. +**ProxyFleet**. ::: @@ -129,7 +128,8 @@ error: By default, the Shulker Agent will try to connect the player to the first -server with the `limbo` tag. Because there is no server currently running +server with the `lobby` tag. If none are found the agent will try to fallback +on a server with the `limbo` tag. Because there is no server currently running in the cluster, there is no other choice than kicking the player. ## A _pinch_ of MinecraftServer @@ -173,12 +173,13 @@ arrive on the server you just created: Pay attention to the `tags` field of the MinecraftServer resource you just created. The Shulker Agent will connect the player to the first server it -finds with the `limbo` tag. It is optional to provide tags to servers. They -could, however, be retrieved using Shulker's Proxy API. +finds with the `lobby` tag. If none, it will try to fallback on one with the +`limbo` tag. It is optional to provide tags to servers. They could, however, +be retrieved using Shulker's Proxy API. ::: -**Congratulations!** You have successfuly creatd your first Minecraft Cluster using Shulker! +**Congratulations!** You have successfully created your first Minecraft Cluster using Shulker! ## Cleaning everything up diff --git a/docs/docs/architecture.mdx b/docs/docs/architecture.mdx index 3bb81a94..812f3fdf 100644 --- a/docs/docs/architecture.mdx +++ b/docs/docs/architecture.mdx @@ -19,37 +19,28 @@ import ThemedImage from '@theme/ThemedImage'; A **Shulker Cluster** is composed of three main _entities_: -1. The **Cluster**, represented by the **MinecraftCluster** CRD (in purple +1. The **Cluster**, represented by the `MinecraftCluster` CRD (in purple in the diagram above) is the primary entity defining some global settings of the cluster. At least one is mandatory as most CRDs will requires you to provide the name of the **Cluster** to attach to. -2. The **Proxy**, represented by the **Proxy** CRD (in orange in the diagram +2. The **Proxy**, represented by the `ProxyFleet` CRD (in orange in the diagram above) is an entrypoint for the players to connect to. A proxy will initiate connections to the **Servers**. -3. The **Server**, represented by the **MinecraftServer** CRD (in green in the +3. The **Server**, represented by the `MinecraftServerFleet` CRD (in green in the diagram above) is a Minecraft Server by itself. They are ephemeral and don't have any persistent storage. They should be destroyed and created on demand. -If you pay close attention to the **Proxies** and **MinecraftServers**, you'll -see that each resource represent only one entity under the hood. This means that -one **Proxy** CRD equals to everything needed to run only one proxy ; simplified -as most as possible, this means that one CRD equals to one **Kubernetes Pod**. - -By design, these two resources are ephemeral. Once their associated **Kubernetes -Pod** is unscheduled (either because it exited successfully or not), they are -themselves destroyed. This is to ensure the velocity and scalability of your -Shulker Cluster. - -They are "grouped" alternatives to single proxies and servers named -**ProxyDeployment** and **MinecraftServerDeployment**. Like **Kubernetes Deployments**, -these CRDs will ensure that, at a given time, there is always a fixed number -of available replicas. +You'll notice the responsability of launching the actual containers is delegated +to **[Agones](https://agones.dev/site/)**. Agones is a Kubernetes Controller +created and maintained by Google whose objective if to _Host, Run and Scale +dedicated game servers on Kubernetes_. Shulker rely on Agones to handle the +scheduling and resiliency part while handling itself the Agones recipes. ## What is exactly a Cluster? -A Cluster (meaning the **MinecraftCluster** CRD), is the root entity of a Minecraft +A **Cluster** (meaning the `MinecraftCluster` CRD), is the root entity of a Minecraft Network: every proxy and server needs one to attach to. It could define global settings multiple sub-entities may need. @@ -66,7 +57,7 @@ for the same resource (if two clusters want to have the same secret name, for in :::note -Currently, the **MinecraftCluster** do not do much things, however it is planned +Currently, the `MinecraftCluster` do not do much things, however it is planned in the future to let it manage a **Limbo mechanism**. A Limbo is a piece of software emulating a Minecraft Server without any game logic. Its only purpose is to keep the player connected to the Network while having an almost-zero performance impact. @@ -95,7 +86,7 @@ have informed proxies to remove them for their list. Shulker, through Kubernetes, knows every proxy and every server along with their availability. Supported by a plugin agent to be installed on every proxy, the proxies -will have their server list updated immediately upon every event occuring in the +will have their server list updated immediately upon every event occurring in the Kubernetes Cluster. :::caution @@ -114,7 +105,7 @@ anything from the game mode to the map to download on startup, like you would do manually by managing all the servers yourself. In the background, we use the Docker images of **[itzg](https://github.com/itzg)**, -an open-source developper which has developed Docker images for Minecraft proxies +an open-source developer which has developed Docker images for Minecraft proxies and servers. These images will handle automatically the software download (like fetching automatically your favorite Bukkit or BungeeCord version) while the configuration is solely managed by Shulker. diff --git a/docs/static/img/basics/basics-dark.excalidraw.png b/docs/static/img/basics/basics-dark.excalidraw.png index fdab4d10..c8101615 100644 Binary files a/docs/static/img/basics/basics-dark.excalidraw.png and b/docs/static/img/basics/basics-dark.excalidraw.png differ diff --git a/docs/static/img/basics/basics.excalidraw.png b/docs/static/img/basics/basics.excalidraw.png index df1c854f..c01ee66f 100644 Binary files a/docs/static/img/basics/basics.excalidraw.png and b/docs/static/img/basics/basics.excalidraw.png differ diff --git a/examples/getting-started/minecraftserver.yaml b/examples/getting-started/minecraftserver.yaml index b985eab8..2df91d6b 100644 --- a/examples/getting-started/minecraftserver.yaml +++ b/examples/getting-started/minecraftserver.yaml @@ -1,5 +1,5 @@ apiVersion: shulkermc.io/v1alpha1 -kind: MinecraftServerDeployment +kind: MinecraftServerFleet metadata: name: limbo spec: diff --git a/examples/getting-started/proxy.yaml b/examples/getting-started/proxy.yaml index 38eb2d5a..5073e0a5 100644 --- a/examples/getting-started/proxy.yaml +++ b/examples/getting-started/proxy.yaml @@ -1,5 +1,5 @@ apiVersion: shulkermc.io/v1alpha1 -kind: ProxyDeployment +kind: ProxyFleet metadata: name: public spec: