Skip to content

Deploying with Kubernetes

This guide will show you how to deploy BlueDragon using Kubernetes.

  • A running Kubernetes cluster (v1.26+)
  • Helm v3+ installed and configured
  • kubectl installed and configured

Before running any BlueDragon images, you need to push them to your own container registry.

If you’re using microk8s, you can install the built-in registry with microk8s enable registry. Your base registry URL will be the IP address of your cluster on port 32000. You may also be able to use localhost. For more information, see the registry plugin documentation.

If you’re using minikube, see their official documentation on registries.

You can also create a registry outside of your cluster and configure it for use within the cluster. For more information, see the official documentation.

There are many ways to deploy MongoDB on Kubernetes. In production, we recommend using the MongoDB Community Operator, which can be installed via Helm by running:

Terminal window
helm repo add mongodb https://mongodb.github.io/helm-charts
helm repo update
helm install community-operator mongodb/community-operator

Then, you can create a MongoDB ReplicaSet by applying some YAML to your cluster in the default namespace:

apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata:
name: mongodb-instance
spec:
members: 1
type: ReplicaSet
version: "8.0.4"
security:
authentication:
modes: ["SCRAM"]
users:
- name: bluedragon
db: admin
passwordSecretRef:
name: mongodb-bluedragon-password
roles:
- name: readWrite
db: bluedragon
- name: readWrite
db: luckperms
scramCredentialsSecretName: bluedragon
additionalMongodConfig:
storage.wiredTiger.engineConfig.journalCompressor: zlib
---
apiVersion: v1
kind: Secret
metadata:
name: mongodb-bluedragon-password
type: Opaque
stringData:
password: <your MongoDB password>

Replace <your MongoDB password> with the password you want to use for your MongoDB user. Then, save the file and apply it to your cluster.

After a few minutes, the operator should create a secret in the default namespace called mongodb-instance-admin-bluedragon. It will contain a key called connectionString.standard, which other services will use to connect.

Create a Deployment and a Service for LuckPerms:

apiVersion: apps/v1
kind: Deployment
metadata:
name: luckperms
spec:
selector:
matchLabels:
app: luckperms
replicas: 1
template:
metadata:
labels:
app: luckperms
spec:
containers:
- name: luckperms
image: ghcr.io/luckperms/rest-api
env:
- name: LUCKPERMS_STORAGE_METHOD
value: "mongodb"
- name: LUCKPERMS_DATA_MONGODB_CONNECTION_URI
valueFrom:
# Populate the environment variable using the MongoDB operator's autogenerated secret
secretKeyRef:
name: mongodb-instance-admin-bluedragon
key: connectionString.standard
optional: false
- name: LUCKPERMS_DATA_DATABASE
value: "luckperms"
- name: LUCKPERMS_SYNC_MINUTES
value: "5"
resources:
requests:
cpu: 128m
memory: 128Mi
limits:
cpu: 256m
memory: 256Mi
---
apiVersion: v1
kind: Service
metadata:
name: luckperms # This name is used for DNS lookups in other pods
labels:
name: luckperms
spec:
selector:
app: luckperms
ports:
- protocol: TCP
port: 8080
targetPort: 8080

Apply this file to your cluster to deploy LuckPerms in the default namespace under the hostname luckperms.

Apply this manifest to your cluster to install Puffin and give it the necessary permissions to watch game server pods and the game server Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
name: puffin
spec:
selector:
matchLabels:
app: puffin
replicas: 1
template:
metadata:
labels:
app: puffin
spec:
# This ServiceAccount is used to allow Puffin to use the Kubernetes API for certain resources
serviceAccountName: puffin-service-account
containers:
- name: puffin
image: <your registry url>/bluedragonmc/puffin:latest
env:
- name: PUFFIN_WORLD_FOLDER
value: /data/worlds
- name: PUFFIN_MONGO_CONNECTION_STRING
valueFrom:
# Populate the environment variable using the MongoDB operator's autogenerated secret
secretKeyRef:
name: mongodb-instance-admin-bluedragon
key: connectionString.standard
optional: false
- name: PUFFIN_TRANSFER_TTL_SECONDS
value: "60"
- name: PUFFIN_DESTINATION_TTL_SECONDS
value: "60"
volumeMounts:
- name: worlds-volume
mountPath: /data/worlds
resources:
requests:
memory: "128Mi"
cpu: 128m
limits:
memory: "1024Mi"
cpu: "1000m"
volumes:
- name: worlds-volume
hostPath:
path: /data/worlds/
type: DirectoryOrCreate
---
apiVersion: v1
kind: Service
metadata:
name: puffin # This name is used for DNS lookups in other pods
labels:
name: puffin
spec:
selector:
app: puffin
ports:
- protocol: TCP
name: grpc
port: 50051
targetPort: 50051
- protocol: TCP
name: ws
port: 8080
targetPort: 8080
- protocol: TCP
name: map-service
port: 8082
targetPort: 8082
---
apiVersion: v1
kind: ServiceAccount
metadata:
name: puffin-service-account
---
# Allow Puffin to get, list, and watch pods and game server Deployments
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: puffin-cluster-role
labels:
app: puffin
rules:
- apiGroups:
- ""
resources:
- pods
verbs:
- get
- list
- watch
- apiGroups:
- "apps"
resources:
- deployments
verbs:
- get
- list
- watch
---
# Bind the ClusterRole to the ServiceAccount that the Puffin Deployment uses
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1
metadata:
name: puffin-cluster-role-binding
roleRef:
kind: ClusterRole
name: puffin-cluster-role
apiGroup: rbac.authorization.k8s.io
subjects:
- kind: ServiceAccount
name: puffin-service-account

Replace <your registry url> with your Docker registry and apply the YAML to your cluster.

apiVersion: apps/v1
kind: Deployment
metadata:
name: proxy
spec:
selector:
matchLabels:
app: proxy
replicas: 1
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
# A proxy can remain up for up to two hours while its players drain.
progressDeadlineSeconds: 21600
template:
metadata:
labels:
app: proxy
spec:
# Two-hour player-facing countdown plus a 90-second shutdown buffer.
terminationGracePeriodSeconds: 7290
containers:
- name: proxy
image: <your registry url>/bluedragonmc/komodo:latest
ports:
- name: minecraft
containerPort: 25565
protocol: TCP
- name: health
containerPort: 8081
protocol: TCP
volumeMounts:
- name: config-volume
mountPath: /proxy/config/
env:
- name: KOMODO_HEALTH_PORT
value: "8081"
- name: KOMODO_HEALTH_TIMEOUT_MS
value: "1000"
- name: KOMODO_SHUTDOWN_COUNTDOWN_SECONDS
value: "7200"
- name: KOMODO_COUNTDOWN_HIDDEN_SECONDS
value: "3600"
- name: KOMODO_DRAIN_QUIESCENCE_MS
value: "15000"
- name: KOMODO_TRANSFER_HOST
value: "bluedragonmc.com"
- name: KOMODO_TRANSFER_PORT
value: "25565"
- name: PUFFIN_VELOCITY_SECRET
valueFrom:
secretKeyRef:
name: proxy-forwarding-secret
key: secret
optional: false
- name: LUCKPERMS_STORAGE_METHOD
value: "mongodb"
- name: LUCKPERMS_DATA_MONGODB_CONNECTION_URI
valueFrom:
secretKeyRef:
name: mongodb-instance-admin-bluedragon
key: connectionString.standard
optional: false
- name: LUCKPERMS_DATA_DATABASE
value: "luckperms"
startupProbe:
httpGet:
path: /ready
port: health
periodSeconds: 2
failureThreshold: 300
timeoutSeconds: 2
readinessProbe:
httpGet:
path: /ready
port: health
periodSeconds: 2
failureThreshold: 2
timeoutSeconds: 1
livenessProbe:
httpGet:
path: /health
port: health
periodSeconds: 5
failureThreshold: 6
timeoutSeconds: 2
lifecycle:
preStop:
httpGet:
path: /drain
port: health
volumes:
- name: config-volume
configMap:
name: proxy-config
items:
- key: proxy-config.properties
path: proxy-config.properties
---
# This NodePort exposes the proxy to the internet on port 30000.
# If you are using a cloud provider or MetalLB, the NodePort can
# be switched out for a LoadBalancer.
apiVersion: v1
kind: Service
metadata:
name: proxy # This name is used for DNS lookups in other pods
spec:
type: NodePort
selector:
app: proxy
ports:
- protocol: TCP
port: 25565
targetPort: 25565
nodePort: 30000
---
# This ConfigMap is mounted into the proxy pod at /proxy/config/proxy-config.properties
apiVersion: v1
kind: ConfigMap
metadata:
name: proxy-config
data:
proxy-config.properties: |
motd.line_1.text=<bold><gradient:#4EB2F4:#3336f4>BlueDragon</gradient></bold> <gray>[<green>26.3<gray>]
motd.line_1.center=true
motd.line_2.text=
motd.line_2.center=true

Replace <your registry url> with your Docker registry, and apply the YAML to your cluster.

Game servers run in a Deployment named server. Puffin discovers the pods by the app=server label, so keep the Deployment name and label unless you also change Puffin’s PUFFIN_GAMESERVER_DEPLOYMENT_NAME and PUFFIN_GAMESERVER_LABEL_SELECTOR settings.

apiVersion: apps/v1
kind: Deployment
metadata:
name: server
labels:
app: server
spec:
replicas: 2
selector:
matchLabels:
app: server
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
# A draining server can stay up for up to two hours while players drain.
progressDeadlineSeconds: 21600
template:
metadata:
labels:
app: server
spec:
# Two-hour player-facing countdown plus a 90-second shutdown buffer.
terminationGracePeriodSeconds: 7290
containers:
- name: server
# This image should be based on the image built in the
# "Building Container Images" guide, and should include your minigame JARs.
image: <your registry url>/bluedragonmc/server-full:latest
imagePullPolicy: IfNotPresent
ports:
- name: minecraft
containerPort: 25565
protocol: TCP
- name: grpc
containerPort: 50051
protocol: TCP
- name: health
containerPort: 8081
protocol: TCP
env:
- name: BLUEDRAGON_SERVER_NAME
valueFrom:
fieldRef:
fieldPath: metadata.name
- name: BLUEDRAGON_HEALTH_PORT
value: "8081"
- name: BLUEDRAGON_SHUTDOWN_COUNTDOWN_SECONDS
value: "7200"
- name: BLUEDRAGON_COUNTDOWN_HIDDEN_SECONDS
value: "3600"
- name: BLUEDRAGON_TICK_TIMEOUT_MS
value: "100"
- name: BLUEDRAGON_DRAIN_QUIESCENCE_MS
value: "15000"
- name: BLUEDRAGON_LOBBY_TRANSFER_TIMEOUT_MS
value: "30000"
- name: PUFFIN_VELOCITY_SECRET
valueFrom:
secretKeyRef:
name: proxy-forwarding-secret
key: secret
optional: false
- name: BLUEDRAGON_MONGO_CONNECTION_STRING
valueFrom:
secretKeyRef:
name: mongodb-instance-admin-bluedragon
key: connectionString.standard
optional: false
startupProbe:
httpGet:
path: /ready
port: health
periodSeconds: 2
failureThreshold: 300
timeoutSeconds: 2
readinessProbe:
httpGet:
path: /ready
port: health
periodSeconds: 2
failureThreshold: 2
timeoutSeconds: 1
livenessProbe:
httpGet:
path: /health
port: health
periodSeconds: 5
failureThreshold: 6
timeoutSeconds: 2
lifecycle:
preStop:
httpGet:
path: /drain
port: health
resources:
requests:
memory: "1024Mi"
cpu: "500m"
limits:
memory: "1024Mi"
cpu: "2000m"
volumeMounts:
- name: data-volume
mountPath: /data/worlds
subPath: /worlds
- name: data-volume
mountPath: /server/songs
subPath: /songs
volumes:
- name: data-volume
hostPath:
path: /data/
type: DirectoryOrCreate

Replace <your registry url> with your Docker registry, and apply the YAML to your cluster.

You can scale the game server Deployment by running:

Terminal window
kubectl scale deployment server --replicas=10 # 10 is the number of game server instances you want to run

Congratulations, you’ve successfully deployed BlueDragon on Kubernetes!

You should be able to connect to the server on port 30000. If the port is not forwarded, then you can temporarily use kubectl as a proxy:

Terminal window
kubectl port-forward svc/proxy 30000:25565

Then, connect to the server on localhost:30000.