homelab/cluster/applications/minecraft/deployment.yaml

---
# PaperMC Minecraft Server — Journey Into Imagination
#
# Image: itzg/minecraft-server:2026.7.0
# PaperMC version: 26.2 (build 62, latest stable as of 2026-07-19; requires Java 25)
# NOTE: 26.x series uses PaperMC's independent versioning (not Minecraft version-based).
#       Plugin ecosystem is still catching up — verify plugin compat before adding new ones.
#
# itzg image documentation: https://docker-minecraft-server.readthedocs.io
apiVersion: apps/v1
kind: Deployment
metadata:
  name: papermc
  namespace: minecraft
  labels:
    app.kubernetes.io/name: minecraft
    app.kubernetes.io/component: papermc
    app.kubernetes.io/version: "26.2"
spec:
  replicas: 1
  # Recreate strategy — Minecraft server requires exclusive access to world data.
  # RollingUpdate WILL cause world corruption if both pods mount the PVC simultaneously.
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app.kubernetes.io/name: minecraft
      app.kubernetes.io/component: papermc
  template:
    metadata:
      labels:
        app.kubernetes.io/name: minecraft
        app.kubernetes.io/component: papermc
        app.kubernetes.io/version: "26.2"
    spec:
      securityContext:
        runAsNonRoot: false  # itzg image requires root for some setup steps
        fsGroup: 1000
      containers:
        - name: papermc
          # Pinned tag — never use :latest in production
          image: itzg/minecraft-server:2026.7.0
          imagePullPolicy: IfNotPresent
          ports:
            - name: minecraft
              containerPort: 25565
              protocol: TCP
            - name: rcon
              containerPort: 25575
              protocol: TCP
            - name: metrics
              containerPort: 9225
              protocol: TCP
          env:
            - name: EULA
              value: "TRUE"
            - name: TYPE
              value: "PAPER"
            - name: VERSION
              value: "26.2"
            # Server settings from ConfigMap
            - name: MOTD
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: MOTD
            - name: SERVER_NAME
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: SERVER_NAME
            - name: GAMEMODE
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: GAMEMODE
            - name: DIFFICULTY
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: DIFFICULTY
            - name: PVP
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: PVP
            - name: MAX_PLAYERS
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: MAX_PLAYERS
            - name: ALLOW_FLIGHT
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: ALLOW_FLIGHT
            - name: SPAWN_PROTECTION
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: SPAWN_PROTECTION
            - name: SEED
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: SEED
            - name: ONLINE_MODE
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: ONLINE_MODE
            - name: WHITE_LIST
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: WHITE_LIST
            - name: ENFORCE_WHITELIST
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: ENFORCE_WHITELIST
            - name: MAX_TICK_TIME
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: MAX_TICK_TIME
            - name: ENABLE_RCON
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: ENABLE_RCON
            - name: RCON_PORT
              valueFrom:
                configMapKeyRef:
                  name: papermc-config
                  key: RCON_PORT
            # RCON password from Secret
            - name: RCON_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: papermc-rcon
                  key: rcon-password
          volumeMounts:
            - name: world-data
              mountPath: /data
          resources:
            requests:
              cpu: "1"
              memory: "2Gi"
            limits:
              cpu: "4"
              memory: "6Gi"
          # Startup probe — give the server time to download PaperMC jar on first boot
          startupProbe:
            tcpSocket:
              port: minecraft
            initialDelaySeconds: 30
            periodSeconds: 10
            failureThreshold: 30  # 5 minutes total
          # Liveness probe — restart if the TCP port goes away
          livenessProbe:
            tcpSocket:
              port: minecraft
            initialDelaySeconds: 0
            periodSeconds: 30
            failureThreshold: 3
          # Readiness probe — only route traffic when server is accepting connections
          readinessProbe:
            tcpSocket:
              port: minecraft
            initialDelaySeconds: 0
            periodSeconds: 10
            failureThreshold: 3
      volumes:
        - name: world-data
          persistentVolumeClaim:
            claimName: papermc-world-data