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