diff --git a/docs/src/.vitepress/config.mts b/docs/src/.vitepress/config.mts index f8d2255e..b52a42c7 100644 --- a/docs/src/.vitepress/config.mts +++ b/docs/src/.vitepress/config.mts @@ -10,55 +10,70 @@ const description = const renderTitle = (title: string) => titleTemplate.replace(':title', title); -const sidebar = { - '/guide/': [ - { - text: 'Introduction', - items: [ - { text: 'What is Shulker?', link: '/guide/' }, - { text: 'Architecture', link: '/guide/architecture' }, - ], - }, - { - text: 'Getting Started', - items: [ - { - text: 'Prerequisites', - link: '/guide/getting-started/prerequisites', - }, - { - text: 'Installation', - link: '/guide/getting-started/installation', - }, - { - text: 'Your First Cluster', - link: '/guide/getting-started/your-first-cluster', - }, - ], - }, - { - text: 'Recipes', - items: [ - { - text: 'Adding custom content', - link: '/guide/recipes/adding-custom-content', - }, - { - text: 'Enabling proxy protocol', - link: '/guide/recipes/enabling-proxy-protocol', - }, - { - text: 'Overriding pod properties', - link: '/guide/recipes/overriding-pod-properties', - }, - { - text: 'Defining network administrators', - link: '/guide/recipes/defining-network-administrators', - }, - ], - }, - ], -} satisfies DefaultTheme.SidebarMulti; +const sidebar = [ + { + text: 'Introduction', + items: [ + { text: 'What is Shulker?', link: '/guide/' }, + { text: 'Architecture', link: '/guide/architecture' }, + ], + }, + { + text: 'Getting Started', + items: [ + { + text: 'Prerequisites', + link: '/guide/getting-started/prerequisites', + }, + { + text: 'Installation', + link: '/guide/getting-started/installation', + }, + { + text: 'Your First Cluster', + link: '/guide/getting-started/your-first-cluster', + }, + ], + }, + { + text: 'Recipes', + items: [ + { + text: 'Adding custom content', + link: '/guide/recipes/adding-custom-content', + }, + { + text: 'Enabling proxy protocol', + link: '/guide/recipes/enabling-proxy-protocol', + }, + { + text: 'Overriding pod properties', + link: '/guide/recipes/overriding-pod-properties', + }, + { + text: 'Defining network administrators', + link: '/guide/recipes/defining-network-administrators', + }, + ], + }, + { + text: 'Addons', + items: [ + { + text: 'What are addons?', + link: '/guide/addons/what-are-addons', + }, + { + text: 'Matchmaking (alpha)', + link: '/guide/addons/matchmaking', + }, + ], + }, + { + text: 'API & SDK Reference', + link: '/sdk/', + }, +] satisfies DefaultTheme.Sidebar; export default defineConfig({ title: 'Shulker', @@ -140,9 +155,10 @@ export default defineConfig({ socialLinks: [{ icon: 'github', link: repositoryUrl }], nav: [ - { text: 'Getting Started', link: sidebar['/guide/'][1].items[0].link }, + { text: 'Getting Started', link: '/guide/getting-started/prerequisites' }, { text: 'Guide', link: '/guide/' }, - { text: 'Recipes', link: sidebar['/guide/'][2].items[0].link }, + { text: 'Recipes', link: '/guide/recipes/adding-custom-content' }, + { text: 'Addons', link: '/guide/addons/what-are-addons' }, ], sidebar, diff --git a/docs/src/guide/addons/matchmaking.md b/docs/src/guide/addons/matchmaking.md new file mode 100644 index 00000000..fe87cca2 --- /dev/null +++ b/docs/src/guide/addons/matchmaking.md @@ -0,0 +1,147 @@ +# Matchmaking + +Shulker Matchmaking is an addon for Shulker providing queuing +capabilities to your `MinecraftServerFleets`. Players will be able +to join **matchmaking queues**. + +This addon makes use of [Open Match](https://open-match.dev/site/), a match +making system created by Google meant to be scalable and deeply configurable. + +It will allow you to define `MatchmakingQueues` that associate a `MinecraftServerFleet` +with a **matchmaking function** (an algorithm that groups queued players +to form matches). While you'll be able to create your own match making +algorithms to fit your needs, the addon provides basic algorithm sufficient +for most use-cases: + +- A **Batch** algorithm, to group players _as they go_, without distinction. + This makes easy for you to create a queue and provision servers when they + are needed +- A **Elo** algorithm, which will group players depending on a _global score_ + that you'll have to define and implement + +:::warning + +The Elo algorithm is planned but is not available for now. + +::: + +While manipulating Open Match directly to handle the queues is possible, +Shulker Matchmaking makes it really easy by providing an SDK to be used in +your plugins. After installing and scaling Open Match depending on your needs, +you should forget about it. + +:::tip + +This documentation will make use of the terms used by Open Match, it is advised +for you to read the Open Match's documentation prior to the use of this addon: + +https://open-match.dev/site/docs/guides/matchmaker/ + +::: + +## Installation + +Shulker Matchmaking requires [Open Match](https://open-match.dev/site/) to be +installed on your Kubernetes cluster. You may need to tune its configuration +to fit your needs, especially if you require high-availabiilty of your matchmaking +system. + +The addon can be enabled using the Helm chart, by toggling the `enabled` flag +in the `values.yaml` file: + +```yaml +shulker-addon-matchmaking: + enabled: true +``` + +This will create two deployments: + +- One named `director` that will read your `MatchmakingQueues`, poll Open Match + for queued players at a fixed interval and finally will create and assign + the servers +- One named `mmf` _(for Match Making Function)_ that exposes the built-in + algorithms for you to use out-of-the-box + +:::warning + +While the first one cannot be scaled for now (this is a limitation that could +be removed later on after a stabilization period), the `mmf` deployment **can** +and **should** as it will be highly sollicitated if you have a large number +of `MatchmakingQueues`. This is done by manipulating the Helm values. + +::: + +## Usage + +### Creating a `MatchmakingQueue` + +A `MatchmakingQueue` is a Kubernetes resource describing the shape of the +matches to create. It associates a `MinecraftServerFleet` and a matchmaking +function. It also specifies the size boundaries of the matches to create: + +```yaml +apiVersion: matchmaking.shulkermc.io/v1alpha1 +kind: MatchmakingQueue +metadata: + name: free-for-all +spec: + targetFleetRef: + name: free-for-all + mmf: + builtIn: + type: Batch + minPlayers: 8 + maxPlayers: 12 +``` + +The previous manifests describes a `MatchmakingQueue` that: + +- targets a `MinecraftServerFleet` named `free-for-all` +- groups the players using the built-in `Batch` algorithm +- creates matches of 12 players at most +- allows creation of partial matches for at least 8 players + +:::tip + +The `minPlayers` field is optional and can be ommited. When defined, +the built-in matchmaking functions will allow the creation of _partial matches_, +using the **backfills** machanism of Open Match (see Open Match's documentation for +more information). + +Otherwise, a _full match_ will only be created when there are at lease `maxPlayers` +players in the queue. + +::: + +### Creating in-game tickets + +TODO. + +## Recipes + +### Available built-in matchmaking functions + +| Name | Description | +| --------- | ------------------------------------------------------------------------------------ | +| **Batch** | Groups the players as they go, without any discriminator | +| **Elo** | Groups the players depending on an integer score and their waiting time in the queue | + +### Using a custom matchmaking function + +You can create your own matchmaking function by exposing a gRPC server compliant with +Open Match's specification. After deploying it in your Kubernetes cluster, you can refer +to it in your `MatchmakingQueue`: + +```yaml +apiVersion: matchmaking.shulkermc.io/v1alpha1 +kind: MatchmakingQueue +metadata: + name: free-for-all +spec: + targetFleetRef: + name: free-for-all + mmf: // [!code focus] + provided: // [!code focus] + host: my-mmf // [!code focus] + port: 9876 // [!code focus] +``` diff --git a/docs/src/guide/addons/what-are-addons.md b/docs/src/guide/addons/what-are-addons.md new file mode 100644 index 00000000..1c401ba1 --- /dev/null +++ b/docs/src/guide/addons/what-are-addons.md @@ -0,0 +1,27 @@ +# Addons + +While Shulker has strong and well defined objectives to solve, Shulker +is also present in every part of your Minecraft infrastructure: at the +Kubernetes level of course, by administrating the different resources, but +also in your proxies and servers thanks to the built-in agent plugins. + +This makes Shulker capable of providing additional features that are not +strictly required for your Minecraft cluster to operate, but are not easy +to implement by yourself. + +Shulker's **addons** are optional and opt-in components that can provide +additional functionalities to your Minecraft clusters. They are not meant +for everyone but for those who are interested in these specific features. + +:::warning + +It is important to note that Shulker is an infrastructure management tool +before all. This means that some addons may need further work from you +(deployment of required infrastructure, plugin development, etc...). + +Providing a ready-to-use SDK will be preferred for you to manipulate +addons allowing third-party manipulation, but will be not required. + +::: + +## diff --git a/docs/src/guide/getting-started/installation.md b/docs/src/guide/getting-started/installation.md index c69a841f..42310ff7 100644 --- a/docs/src/guide/getting-started/installation.md +++ b/docs/src/guide/getting-started/installation.md @@ -4,32 +4,46 @@ Shulker is composed of multiple components, some of them being optional. By design, only the **Shulker Operator** is required to be installed as it contains the core logic. -## Shulker Operator +## Using Helm -The **Shulker Operator** can be installed using **Kustomize**: +If you need to fine-tune Shulker and its different components, +an exhaustive Helm chart is provided. The default configuration +is enough to get started. + +The Helm Chart is available in the [`kube/helm`](https://github.com/jeremylvln/Shulker/tree/main/kube/helm) +folder of the repository. + +To install Shulker using Helm: ```bash $ git clone https://github.com/jeremylvln/Shulker -$ kubectl apply -k Shulker/kube/overlays/stable -n shulker-system +$ cd Shulker/kube/helm +$ helm install -n shulker-system . ``` -:::tip +## Using pre-rendered manifests -If Prometheus is installed (along with its custom CRDs), you -would prefer selecting the `stable-with-prometheus` overlay which -will create appropriate `ServiceMonitor`s resources. +Pre-rendered manifests for common uses are provided and are +generated for the Helm charts. It allows you to test Shulker +in your cluster without hassle. -::: +The manifests are available in the [`kube/manifests`](https://github.com/jeremylvln/Shulker/tree/main/kube/manifests) +folder of the repository. -After this, a `shulker-operator` Pod should be scheduled and -work immediately. +There are 4 pre-rendered variants available: -:::info +- `stable.yaml`: a default configuration as you would render + the Helm chart without modifying the values +- `stable-with-prometheus.yaml`: the same default configuration + with Prometheus support, including `ServiceMonitor` for the + different components +- `next.yaml`: the same configuration as for `stable.yaml`, with + the images tagged to `next` to quickly test the future release +- `next-with-prometheus.yaml`: the combination of `next.yaml` with + Prometheus support -The operator Pod requires a certificate from cert-manager to -be provisioned, it may take some seconds/minutes to generate. -If the certificate is still not available after some minutes, -check your cert-manager logs. There is no special configuration -expected, a default installation should work out of the box. +You can apply them directly with `kubectl`: -::: +```bash +$ kubectl apply -f stable.yaml -n shulker-system +``` diff --git a/docs/src/sdk/index.md b/docs/src/sdk/index.md new file mode 100644 index 00000000..974d13f9 --- /dev/null +++ b/docs/src/sdk/index.md @@ -0,0 +1,3 @@ +# API & SDK Reference + +Soon :)