Bungeekube

Bungeecord & Velocity plugin to support Kubernetes service discovery and configuration.

How it works

The plugin utilises the Kubernetes API to search for applicable fallback servers that can be configured in the Bungeecord server that this plugin is installed on. Discovery can be done either by watching pods or headless services.

Project state

The below table should give you a quick overview of the stability and usability of this software, and whether or not you should run this in production.

Proxy software	Project phase
Velocity	Alpha
Bungeecord	In development

Installation

Below are the installation steps necessary to set up this software.

1) Proxy (Bungeecord, Velocity)

First, simply drag and drop the plugin Jar into the plugins folder.

2) RBAC permissions

Now it's time to create a new role for the proxy pod. These permissions are necessary as the plugin needs to use the Kubernetes API to search for fallback pods or headless services. The below example can be used for reference. Depending on what you configure in the plugin, either the pod or service permission can be removed. If you enable headless service scanning, then pod scanning can be disabled and the permission can be removed here, and visa versa.

---
kind: Role
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: minecraft-proxy
  namespace: minecraft
rules:
  - apiGroups:
      - ""
    resources:
      - pods
      - services
    verbs:
      - get
      - list
      - watch
---
kind: RoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: minecraft-proxy
  namespace: minecraft
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: minecraft-proxy
subjects:
- kind: ServiceAccount
  name: minecraft-proxy
  namespace: minecraft
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: minecraft-proxy
  namespace: minecraft

3) Pod or service setup

We have two options in this step. Either we can annotate our Minecraft pods, or we can set up a headless service to help us with the discovery. The difference is simply that the pod scanning setup will iterate over a set of pods and look for any which have the required annotation and expected/configured ports open. The advantage is that this setup allows the discovered fallback serves to be identified by name, but this approach will be slower on larger setups.

The second option is to use a headless service to assist this plugin in its discovery. When choosing this option, ensure you understand what the difference between a service and headless service is. The advantage of using a headless service is that discovery is faster for larger networks, but fallback servers cannot be identified by name as only IP addresses will be returned by this headless service.

Below is a simple table listing all possible annotations and their functionality.

Annotation	Description
bungeekube.dyescape.com/enabled: 'true'	Base annotation to mark services or pods applicable for discovery.
bungeekube.dyescape.com/default: 'true'	Mark the server as a default, a server which players are sent to upon initial connection.

Annotated pod

Below we have an example of a StatefulSet which complies with this plugin. Note that only the template annotations are important here. This serves purely as an example to showcase the annotation usage.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: minecraft-server
  namespace: minecraft
spec:
  selector:
    matchLabels:
      component: minecraft-server
  serviceName: minecraft-server
  template:
    metadata:
      labels:
        component: minecraft-server
        bungeekube.dyescape.com/enabled: 'true' # <--- Important!
    spec:
      containers:
      - name: minecraft-software
        image: minecraft-server:1.16.2
        imagePullPolicy: Always
        ports:
        - containerPort: 25565
          name: minecraft  # <--- Important!

Annotated headless service

Below we have an example of a compliant headless service. What's important to note here is the annotation and the clusterIP field. The annotation is used for identification in the plugin, and the clusterIP: None makes it a headless service. The below example is purely for reference.

apiVersion: v1
kind: Service
metadata:
  name: minecraft-server
  namespace: minecraft
  labels:
    bungeekube.dyescape.com/enabled: 'true' # <--- Important!
spec:
  clusterIP: None # <---
  selector:
    component: minecraft-server
  ports:
    - protocol: TCP
      port: 25565
      targetPort: 25565 

Usage

The plugin is designed to automatically find and register discovered fallback services into the running proxy instance. The configuration can be changed according to your needs and setup. See the below reference.

discovery:
  
TODO

In the spirit of Minecraft backends more suitable on cloud, this plugin also supports environment variables. Refer to the below overview for a complete list of available environment variables.

TODO