minecraft-operator

Minecraft Operator

A Kubernetes operator for managing PaperMC servers with automatic version management, plugin compatibility solving, and scheduled updates.

Note: This operator is designed for single-instance Minecraft servers. 5-10 minutes of downtime during updates is acceptable by design.

Features

• Automatic Version Management — Four update strategies (latest, auto, pin, build-pin) for both Paper and plugins
• Plugin Compatibility Solver — Constraint solver ensures all plugins work with the selected Paper version
• Scheduled Updates — Cron-based maintenance windows with graceful RCON shutdown
• Declarative Plugin Management — Plugins matched to servers via label selectors
• VolumeSnapshot Backups — Cron-scheduled and on-demand backups with RCON consistency hooks and retention policy
• Self-Managed CRDs — CRDs embedded in the operator binary, applied at startup via server-side apply
• Web UI — Built-in dashboard for monitoring servers and plugins
• Hangar Integration — Automatic plugin downloads from PaperMC Hangar repository
• Direct URL Plugins — Download plugins from any HTTPS URL with optional SHA256 checksum verification

Quick Start

Prerequisites

• Kubernetes 1.27+
• Helm 3.14+

Install the Operator

helm install minecraft-operator oci://ghcr.io/lexfrei/charts/minecraft-operator \
  --create-namespace \
  --namespace minecraft-operator-system

CRDs are embedded in the operator binary and applied automatically at startup. No separate CRD chart or kubectl apply step is needed.

Create a Minecraft Server

First, create an RCON secret:

kubectl create secret generic my-server-rcon \
  --namespace default \
  --from-literal=password="your-rcon-password"

Then apply the server manifest:

apiVersion: mc.k8s.lex.la/v1beta1
kind: PaperMCServer
metadata:
  name: my-server
  labels:
    environment: production
spec:
  updateStrategy: "auto"
  updateSchedule:
    checkCron: "0 3 * * *"
    maintenanceWindow:
      enabled: true
      cron: "0 4 * * 0"
  gracefulShutdown:
    timeout: 300s
  rcon:
    enabled: true
    passwordSecret:
      name: my-server-rcon
      key: password
  podTemplate:
    spec:
      containers:
        - name: minecraft
          resources:
            requests:
              memory: "2Gi"
            limits:
              memory: "4Gi"

Add a Plugin

apiVersion: mc.k8s.lex.la/v1beta1
kind: Plugin
metadata:
  name: essentialsx
spec:
  source:
    type: hangar
    project: "Essentials"
  updateStrategy: "latest"
  updateDelay: 168h
  instanceSelector:
    matchLabels:
      environment: production

The plugin is automatically downloaded and installed on all servers matching the label selector.

See the examples/ directory for more use cases.

Update Strategies

See Update Strategies Guide for details.

Architecture

Four controllers work together:

1. Plugin Controller — Fetches plugin metadata from Hangar or direct URLs, runs compatibility solver, updates Plugin status
2. PaperMCServer Controller — Manages StatefulSet and Service, resolves Paper version based on update strategy
3. Update Controller — Executes scheduled updates during maintenance windows with graceful RCON shutdown
4. Backup Controller — Creates VolumeSnapshots with RCON save hooks for data consistency, supports cron scheduling, manual triggers, and retention

For detailed architecture and constraint solver algorithms, see DESIGN.md.

Backups

Enable VolumeSnapshot-based backups:

spec:
  backup:
    enabled: true
    schedule: "0 */6 * * *"     # Every 6 hours
    beforeUpdate: true           # Backup before any update
    retention:
      maxCount: 10               # Keep last 10 snapshots

When RCON is enabled, the operator uses RCON hooks (save-all, save-off, save-on) to flush data to disk and disable auto-save before creating a VolumeSnapshot. Without RCON, snapshots are crash-consistent only.

Trigger a manual backup:

kubectl annotate papermcserver my-server \
  mc.k8s.lex.la/backup-now="$(date +%s)" \
  --namespace minecraft

Requirements: A CSI driver with VolumeSnapshot support must be installed in the cluster.

Helm Configuration

Key values:

crds:
  manage: true          # Apply embedded CRDs at startup (default: true)

webui:
  enabled: true         # Enable built-in Web UI (default: true)
  port: 8082

leaderElection:
  enabled: true         # Enable leader election for HA (default: true)

metrics:
  enabled: true         # Enable Prometheus metrics (default: true)
  port: 8080
  serviceMonitor:
    enabled: false      # Enable ServiceMonitor for Prometheus Operator

See charts/minecraft-operator/values.yaml for all options.

Monitoring

The operator exposes Prometheus metrics at /metrics (port 8080 by default):

• Reconciliation: duration, total count, and error count per controller
• Plugin API: request count, error count, and latency per source
• Solver: invocation count and duration per solver type
• Updates: success/failure count per server update

Enable metrics.serviceMonitor.enabled in Helm values for automatic Prometheus Operator discovery.

Web UI

Access the built-in dashboard:

kubectl port-forward svc/minecraft-operator-webui 8082:8082 \
  --namespace minecraft-operator-system

Open http://localhost:8082/ui

Development

make manifests generate   # Generate CRDs and deepcopy methods
make test                 # Run unit tests with envtest
make lint                 # Run golangci-lint
make run                  # Run operator locally against kubeconfig cluster

This project follows strict TDD methodology. See CLAUDE.md for development standards.

Links

• Documentation Site
• Changelog
• Design Document
• GitHub Issues

Contributing

Contributions are welcome. See GitHub Issues for open tasks.

License

BSD-3-Clause. See LICENSE.