docs: add recipes for plugins, pod overrides, and proxy protocol (jer…

…emylvln#117)

* docs: add recipes for plugins, pod overrides, and proxy protocol

* docs: simplfies mdx of custom content page

docs/docs/03-recipes/01-adding-custom-content.mdx

@@ -0,0 +1,148 @@
+---
+sidebar_position: 1
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Adding custom content
+
+Proxies and servers could need custom content like maps, plugins, mods
+or any other file.
+
+## Ways of retrieving content
+
+Additional content can be retrieved in several ways, all of them could
+by used for any content.
+
+<Tabs>
+ <TabItem value="url" label="Direct URL" default>
+
+The most straightforward way of downloading files is via a direct URL.
+It is attended that the URL is a direct link to the file, without any
+authentication layer. Otherwise it should be specified directly in the
+URL, thus exposing the credentials to the public.
+
+```yaml showLineNumbers
+url: https://example.com/my-file.tar.gz
+```
+
+ </TabItem>
+
+ <TabItem value="maven" label="Maven Repository">
+
+Most useful for JAR archives, Maven repositories can be used to download
+files. The URL is composed of the repository URL, the group ID, the
+artifact ID and the version. Optionally, one can specify a secret name
+containing the credentials to use to authenticate agaisnt the repository.
+
+```yaml showLineNumbers
+urlFrom:
+ mavenRef:
+ repository: https://example.com/maven
+ groupId: com.example
+ artifactId: myplugin
+ version: '1.0.0'
+ credentialsSecretName: example-repo-secret
+```
+
+ </TabItem>
+</Tabs>
+
+## Adding plugins
+
+> Applicable to: proxies, servers
+
+Shulker can automatically download plugins from different sources and
+place them in the `plugins` folder of your proxy or server. It is
+expected to download JAR files. They should not be packed in an archive.
+
+Here is how to add two plugins, one using a direct URL, the other from
+a Maven repository.
+
+:::note
+
+While the following example is a `MinecraftServerFleet`, the same applies
+for a `ProxyFleet`.
+
+:::
+
+```yaml title="server.yaml" showLineNumbers
+apiVersion: shulkermc.io/v1alpha1
+kind: MinecraftServerFleet
+metadata:
+ name: my-server
+spec:
+ clusterRef:
+ name: my-cluster
+ replicas: 1
+ template:
+ spec:
+ config:
+ plugins:
+ - url: https://example.com/my-plugin.jar
+ - urlFrom:
+ mavenRef:
+ repository: https://example.com/maven
+ groupId: com.example
+ artifactId: myplugin
+ version: '1.0.0'
+ credentialsSecretName: example-repo-secret
+```
+
+## Adding maps
+
+> Applicable to: servers
+
+Some servers may need maps to be downloaded before the server is started.
+This may be used for ephemeral servers using the same map, like minigames.
+
+Shulker can download a tar-gzipped archive and extract it at the server
+root directory.
+
+```yaml title="server.yaml" showLineNumbers
+apiVersion: shulkermc.io/v1alpha1
+kind: MinecraftServerFleet
+metadata:
+ name: my-server
+spec:
+ clusterRef:
+ name: my-cluster
+ replicas: 1
+ template:
+ spec:
+ config:
+ world:
+ url: https://example.com/my-worlds.tar.gz
+```
+
+## Adding patches
+
+> Applicable to: proxies, servers
+
+Patches are tar-gzipped archives that are extracted at the root of the
+server, overwriting existing files. They can be used to _patch_ the server
+content. They are applied in the order specified in the configuration.
+
+```yaml title="server.yaml" showLineNumbers
+apiVersion: shulkermc.io/v1alpha1
+kind: MinecraftServerFleet
+metadata:
+ name: my-server
+spec:
+ clusterRef:
+ name: my-cluster
+ replicas: 1
+ template:
+ spec:
+ config:
+ patches:
+ - url: https://example.com/my-first-patch.tar.gz
+ - url: https://example.com/my-second-patch.tar.gz
+```
+
+## Real-world example
+
+You can find a real-world example of a `ProxyFleet` and `MinecraftServerFleet`
+with additional content by looking at the `with-custom-configuration` example
+**[from the repository](https:/jeremylvln/Shulker/tree/main/examples/with-custom-configuration)**.

docs/docs/03-recipes/enabling-proxy-protocol.md

@@ -0,0 +1,54 @@
+# Enabling Proxy Protocol
+
+Most of the time, the IP address received by your proxy will be the
+one of the cloud provider's load balancer, thus not the one of the
+connecting player.
+
+This is a problem because Shulker configures the proxies to expect
+that the connecting IP is the same than the one the player used to
+authenticate agaisn't Mojang's servers. This is one way to prevent
+spoofing attacks.
+
+The Proxy Protocol is a protocol that allows the load balancer to
+send the real IP address of the client to the underlying service, here
+the proxy. It is supported by most cloud providers.
+
+To enable it, you need to set the `proxyProtocol` option to `true` in
+the configuration of your proxy:
+
+```yaml title="proxy.yaml" showLineNumbers
+apiVersion: shulkermc.io/v1alpha1
+kind: ProxyFleet
+metadata:
+ name: proxy
+spec:
+ clusterRef:
+ name: my-cluster
+ replicas: 1
+ template:
+ spec:
+ config:
+ proxyProtocol: true
+```
+
+:::note
+
+You'll may need to set the `externalTrafficPolicy` of the Kubernetes
+Service created for the `ProxyFleet` to `Local`, to avoid having one of
+your node forwarding traffic to another.
+
+:::
+
+:::note
+
+Your cloud provider *may* also expect you of adding some annotations to
+the Service as well for them to configure properly your load balancer.
+Check out your cloud provider documentation to learn more.
+
+:::
+
+## Real-world example
+
+You can find a real-world example of a `ProxyFleet` with proxy protocol
+enabled, for Scaleway Cloud Provider, by looking at the `with-proxy-protocol`
+example **[from the repository](https:/jeremylvln/Shulker/tree/main/examples/with-proxy-protocol)**.

docs/docs/03-recipes/overriding-pod-properties.md

@@ -0,0 +1,75 @@
+# Overriding Pod properties
+
+To suit your needs, you may need to override or complete some
+properties filled to the underlying Pod. The `podOverrides`
+property of both the `ProxyFleet` and `MinecraftServerFleet`
+allows you to customize the Pod properties as you were writing
+a Pod directly (i.e. the supported sub-properties are identical
+to the Pod specification).
+
+You can find all the properties overridable by looking at the
+`shulker-crds` package of the repository:
+
+- [ProxyFleet](https:/jeremylvln/Shulker/blob/main/packages/shulker-crds/v1alpha1/proxyfleet_types.go)
+- [MinecraftServerFleet](https:/jeremylvln/Shulker/blob/main/packages/shulker-crds/v1alpha1/minecraftserverfleet_types.go)
+
+## Add environment variables
+
+Shulker already injects some environment variables that could
+be useful. But adding your own is fully supported:
+
+```yaml title="server.yaml" showLineNumbers
+apiVersion: shulkermc.io/v1alpha1
+kind: MinecraftServerFleet
+metadata:
+ name: my-server
+spec:
+ clusterRef:
+ name: my-cluster
+ replicas: 1
+ template:
+ spec:
+ podOverrides:
+ env:
+ - name: OPENMATCH_HOST
+ value: open-match-frontend.open-match.svc
+ - name: OPENMATCH_PORT
+ value: '50504'
+```
+
+## Setting custom affinities
+
+By default, Agones adds a **preferred* scheduling on nodes
+labelled with `agones.dev/role=gameserver`. However you
+may want to customize more the scheduling behavior.
+
+For instance, you may want to restrict some servers to some
+nodes:
+
+```yaml title="server.yaml" showLineNumbers
+apiVersion: shulkermc.io/v1alpha1
+kind: MinecraftServerFleet
+metadata:
+ name: my-server
+spec:
+ clusterRef:
+ name: my-cluster
+ replicas: 1
+ template:
+ spec:
+ podOverrides:
+ affinity:
+ nodeAffinity:
+ requiredDuringSchedulingIgnoredDuringExecution:
+ nodeSelectorTerms:
+ - matchExpressions:
+ - key: devops.example.com/gameserver
+ operator: In
+ values:
+ - my-server
+ tolerations:
+ - key: "devops.example.com/gameserver"
+ operator: "Equal"
+ value: "my-server"
+ effect: "NoSchedule"
+```

docs/docusaurus.config.js

@@ -55,7 +55,7 @@ const config = {
  },
  {
  type: 'doc',
- docId: 'recipes/minecraft-cluster',
+ docId: 'recipes/adding-custom-content',
  position: 'left',
  label: 'Recipes',
  },
@@ -82,7 +82,7 @@ const config = {
  },
  {
  label: 'Recipes',
- to: '/recipes/minecraft-cluster',
+ to: '/recipes/adding-custom-content',
  },
  ],
  },

examples/with-custom-configuration/cluster.yaml

@@ -0,0 +1,5 @@
+apiVersion: shulkermc.io/v1alpha1
+kind: MinecraftCluster
+metadata:
+ name: getting-started
+spec: {}

examples/with-custom-configuration/kustomization.yaml

@@ -0,0 +1,4 @@
+resources:
+- cluster.yaml
+- proxy.yaml
+- minecraftserver.yaml

examples/with-custom-configuration/minecraftserver.yaml

@@ -0,0 +1,31 @@
+apiVersion: shulkermc.io/v1alpha1
+kind: MinecraftServerFleet
+metadata:
+ name: limbo
+spec:
+ clusterRef:
+ name: getting-started
+ replicas: 1
+ template:
+ spec:
+ tags:
+ - limbo
+ version:
+ channel: Paper
+ name: '1.19.3'
+ config:
+ world:
+ url: https://example.com/my-world.tar.gz
+ plugins:
+ - urlFrom:
+ mavenRef:
+ repository: https://example.com/maven
+ groupId: com.example
+ artifactId: myplugin
+ version: '1.0.0'
+ credentialsSecretName: example-repo-secret
+ patches:
+ - url: https://example.com/add-config-to-myplugin.tar.gz
+ - url: https://example.com/add-something-after.tar.gz
+ - url: https://example.com/remove-everything-at-the-end.tar.gz
+ maxPlayers: 100

examples/with-custom-configuration/proxy.yaml

@@ -0,0 +1,30 @@
+apiVersion: shulkermc.io/v1alpha1
+kind: ProxyFleet
+metadata:
+ name: public
+spec:
+ clusterRef:
+ name: getting-started
+ replicas: 1
+ service:
+ type: LoadBalancer
+ externalTrafficPolicy: Local
+ template:
+ spec:
+ version:
+ channel: Velocity
+ name: latest
+ config:
+ plugins:
+ - urlFrom:
+ mavenRef:
+ repository: https://example.com/maven
+ groupId: com.example
+ artifactId: myplugin
+ version: '1.0.0'
+ credentialsSecretName: example-repo-secret
+ patches:
+ - url: https://example.com/add-config-to-myplugin.tar.gz
+ - url: https://example.com/add-something-after.tar.gz
+ - url: https://example.com/remove-everything-at-the-end.tar.gz
+ maxPlayers: 100

examples/with-proxy-protocol/cluster.yaml

@@ -0,0 +1,5 @@
+apiVersion: shulkermc.io/v1alpha1
+kind: MinecraftCluster
+metadata:
+ name: getting-started
+spec: {}

examples/with-proxy-protocol/kustomization.yaml

@@ -0,0 +1,3 @@
+resources:
+- cluster.yaml
+- proxy.yaml