docs: add pages about helm and matchmaking

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,

docs/src/guide/addons/matchmaking.md

@@ -0,0 +1,147 @@
+# Matchmaking <Badge type="danger" text="alpha" />
+
+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]
+```

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.
+
+:::
+
+##

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:/jeremylvln/Shulker/tree/main/kube/helm)
+folder of the repository.
+
+To install Shulker using Helm:
 
 ```bash
 $ git clone https:/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:/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
+```

docs/src/sdk/index.md

@@ -0,0 +1,3 @@
+# API & SDK Reference
+
+Soon :)