Importing an Existing World into Your Minecraft Kubernetes Server

Overview

This article walks through restoring an existing Minecraft world and plugin configurations from a backup into your Kubernetes server. You will install plugins first to ensure proper config recognition, then restore world data and plugin configurations from your backup.


Tip:	Having trouble? See v0.12.2 for what your setup should look like after completing this article.

Before You Begin

Prerequisites

Minecraft Paper Server completed

Why This Approach


Note:	Minecraft automatically upgrades worlds when loaded on a newer server version. Downgrading (newer world → older server) is not supported and may corrupt the world.

Phase 1: Install plugins before restoring world data so plugin configs are recognized.

Phase 2: Restore worlds and plugin data.

Add Plugins Configuration

HelmRelease (Plugins)

Add rcon.enabled under minecraftServer:

minecraftServer:
  # ... existing settings ...
  rcon:
    enabled: true

Add plugin configuration to extraEnv:

extraEnv:
  JVM_XX_OPTS: '...' # existing flags
  # BentoBox Classic Skyblock bundle (extracts with correct folder structure)
  MODPACK: 'https://download.bentobox.world/api/generate?downloads=%5B%22BSkyBlock%22%2C%22Challenges%22%2C%22Level%22%2C%22Warps%22%2C%22ControlPanel%22%2C%22DimensionalTrees%22%2C%22Biomes%22%2C%22Bank%22%5D'
  # Plugins from Modrinth (auto-updated)
  MODRINTH_PROJECTS: |
    paper:viaversion
  # Plugins via direct URLs (Geyser/DirectionHUD not on Modrinth for Paper 1.21.11)
  PLUGINS: |
    https://download.geysermc.org/v2/projects/geyser/versions/latest/builds/latest/downloads/spigot
    https://download.geysermc.org/v2/projects/floodgate/versions/latest/builds/latest/downloads/spigot
    https://hangarcdn.papermc.io/plugins/other/DirectionHUD/versions/1.8.1.2%2B1.21.7/PAPER/directionhud-paper-1.8.1.2%2B1.21.7.jar
  REMOVE_OLD_MODS: 'TRUE'

Deploy Plugins

Commit Changes

git add k8s/apps/minecraft/helmrelease.yaml
git commit -m "feat(minecraft): add plugins configuration"
git push

Reconcile Flux

flux reconcile source git flux-system && flux reconcile kustomization sync

Verify Plugins

Plugin Files

# Wait for HelmRelease to be ready
flux get helmreleases -n minecraft -w

# Wait for pod to be running (2/2 containers)
kubectl get pods -n minecraft -w

# Check main plugins
kubectl exec -n minecraft deploy/minecraft -- ls /data/plugins/

# Check BentoBox addons
kubectl exec -n minecraft deploy/minecraft -- ls /data/plugins/BentoBox/addons/

# Check all plugins enabled successfully
kubectl exec -n minecraft deploy/minecraft -- cat /data/logs/latest.log | grep -iE "(Enabling|Done)" | head -30

Expected:

Main plugins: BentoBox, floodgate, ViaVersion, DirectionHUD, Geyser-Spigot
BentoBox addons: BSkyBlock, Challenges, Level, Warps, ControlPanel, DimensionalTrees, Biomes, Bank
"Done (XXs)! For help, type help" at the end

Test Plugins In-Game

Connect to the server, then check logs for your username:

kubectl logs -n minecraft -l app=minecraft -c minecraft --tail=10 | grep -i "joined"

Make yourself an operator (via rcon):

kubectl exec -it -n minecraft deploy/minecraft -- rcon-cli "op <your-username>"

Verify plugins work (in-game):

/island - Opens BentoBox island menu
/bsb challenges - Opens challenges admin (select "Import Template", confirm with yes)
/hud - DirectionHUD settings
/dest add "test" - Save a destination

Check console for any errors:

kubectl logs -n minecraft -l app=minecraft -c minecraft --tail=20

Once plugins are verified, proceed to restore world data.

Restore World Data

Backup Current Server

Optional but recommended before restoring.

POD=$(kubectl get pod -n minecraft -l app=minecraft -o jsonpath='{.items[0].metadata.name}')
mkdir -p ~/minecraft-backup-current
kubectl cp minecraft/$POD:/data ~/minecraft-backup-current/

Extract Backup

mkdir -p ~/minecraft-restore
tar -xzf /path/to/server-backup.tar.gz -C ~/minecraft-restore
ls ~/minecraft-restore/

Upload Worlds

What gets restored:

World data (world, world_nether, world_the_end)
BentoBox island worlds (bskyblock_world, bskyblock_world_nether, bskyblock_world_the_end)


Note:	Any `.jar` files in the backup will be overwritten on restart by the chart's MODPACK/PLUGINS config.

POD=$(kubectl get pod -n minecraft -l app=minecraft -o jsonpath='{.items[0].metadata.name}')

for world in world world_nether world_the_end bskyblock_world bskyblock_world_nether bskyblock_world_the_end; do
  kubectl exec -n minecraft $POD -- rm -rf /data/$world
  kubectl cp ~/minecraft-restore/$world minecraft/$POD:/data/$world
  echo "Copied $world"
done

Restore Plugin Configs

for dir in ~/minecraft-restore/plugins/*/; do
  dirname=$(basename "$dir")
  kubectl cp "$dir" minecraft/$POD:/data/plugins/$dirname
  echo "Copied plugins/$dirname"
done

Verify Uploads

# Check worlds uploaded
kubectl exec -n minecraft $POD -- ls /data/ | grep world

# Check BentoBox Players (compare count with backup)
ls ~/minecraft-restore/plugins/BentoBox/database/Players/
kubectl exec -n minecraft $POD -- ls /data/plugins/BentoBox/database/Players/

# If files missing, copy individually:
# kubectl cp ~/minecraft-restore/plugins/BentoBox/database/Players/<uuid>.json minecraft/$POD:/data/plugins/BentoBox/database/Players/

Restart Server

kubectl rollout restart deployment -n minecraft minecraft
kubectl get pods -n minecraft -w

Verify Restore

kubectl logs -n minecraft -l app=minecraft -c minecraft | grep -iE "(bentobox|Done)" | tail -10

Next Steps

With your world imported, add Bedrock support for cross-platform play.

See: Minecraft Bedrock Support