Server Migration

BadgerPanel supports migrating game servers between Daemon nodes and Orchestrator clusters. This is useful for load balancing, hardware maintenance, decommissioning nodes, or moving servers closer to their players.

How Migration Works

Server migration transfers a game server's files and configuration from one node or cluster to another. The process is managed by the panel and executed by the source and target agents.

Migration Flow

1. Admin initiates migration in the panel
2. Panel validates the target has sufficient resources
3. Source agent stops the game server (if running)
4. Source agent compresses and transfers server files to the target
5. Target agent receives and extracts the files
6. Panel updates the server's node/cluster assignment
7. Target agent starts the server
8. Source agent cleans up the old files

Downtime

Migration requires the server to be stopped during the transfer. The downtime depends on the size of the server's files and the network speed between nodes. A typical Minecraft server (1-5 GB) takes 1-5 minutes.

Prerequisites

Before migrating a server, ensure:

• Target node/cluster has sufficient resources (memory, CPU, disk, allocations)
• Network connectivity between the source and target agents is available
• The server is not currently installing -- wait for installation to complete
• Feature flag for server transfers is enabled (Admin > Settings > Feature Flags)

Migrating Between Daemon Nodes

From the Admin Panel

1. Navigate to Admin > Servers
2. Click on the server you want to migrate
3. Go to the Transfer or Migration tab
4. Select the target node from the dropdown
5. Select an available allocation on the target node
6. Click Start Migration

The panel will display the migration progress:

• Preparing transfer
• Stopping server
• Compressing files
• Transferring data
• Extracting files
• Starting server
• Cleanup complete

What Gets Transferred

Data	Transferred	Notes
Server files	Yes	All files in the server's data directory
Configuration	Yes	Server settings, startup variables, egg config
Allocations	New	A new allocation is assigned on the target node
Databases	No	Database connections remain unchanged
Backups	No	Existing backups stay in MinIO storage
Schedules	Yes	Task schedules are preserved
Subusers	Yes	Subuser permissions are preserved

Database Connectivity

If the server uses a MySQL database hosted on the old node, ensure the database is accessible from the new node's IP. You may need to update MySQL user permissions or migrate the database separately.

Allocation Changes

The server receives a new IP:port allocation on the target node. After migration:

• The old allocation is released on the source node
• A new allocation is assigned on the target node
• Players will need to connect using the new address

DNS Updates

If you use DNS records pointing to a specific node for game servers, update the DNS record to point to the new node's IP after migration.

Migrating Between Orchestrator Clusters

Server migration between Kubernetes clusters follows a similar process but uses Kubernetes-native mechanisms for data transfer.

Steps

1. Navigate to Admin > Servers
2. Click on the server
3. Go to the Transfer tab
4. Select the target cluster
5. Click Start Migration

The orchestrator handles:

• Exporting PersistentVolumeClaim data from the source cluster
• Transferring the data to the target cluster
• Creating new Kubernetes resources (Deployment, Service, PVC) on the target
• Cleaning up resources on the source cluster

Migrating Between Daemon and Orchestrator

BadgerPanel supports cross-infrastructure migration -- moving servers from Docker nodes to Kubernetes clusters and vice versa.

Daemon to Orchestrator

1. Navigate to Admin > Servers
2. Click on the server (currently on a Daemon node)
3. Go to the Transfer tab
4. Select a Kubernetes cluster as the target
5. Click Start Migration

The panel coordinates between the daemon and orchestrator:

• Daemon compresses and uploads server files
• Orchestrator creates a PVC and downloads the files
• Orchestrator creates the Deployment and Service

Orchestrator to Daemon

The reverse process:

• Orchestrator exports PVC data
• Daemon downloads and extracts the files
• Daemon creates the Docker container

Use Case

Cross-infrastructure migration is useful when transitioning from Docker to Kubernetes or when a Kubernetes cluster needs maintenance.

Bulk Migration

For decommissioning a node, you may need to migrate many servers at once.

Planning

1. Navigate to Admin > Nodes and click on the source node
2. Note the total number of servers and their resource requirements
3. Ensure target nodes have enough capacity

Executing Bulk Migrations

Currently, bulk migration is performed server-by-server through the admin interface. For large numbers of servers, use the API:

# Example: migrate a server via API
curl -X POST "https://panel.your-domain.com/api/v1/admin/servers/{server-id}/transfer" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "target_node_id": "target-node-uuid",
    "allocation_id": "allocation-uuid"
  }'

Stagger Migrations

When migrating many servers, stagger them to avoid overwhelming the network and target node. Migrate 2-3 servers at a time and verify each completes successfully before continuing.

Troubleshooting Migration

Migration Stuck at "Transferring"

Causes:

• Network connectivity issues between source and target
• Large server files taking longer than expected
• Source or target agent disconnected

Solutions:

• Check both agents are online in the admin panel
• Verify network connectivity between the nodes
• Check agent logs for transfer errors:

# On the source node
journalctl -u badgerdaemon | grep -i transfer

# On the target node
journalctl -u badgerdaemon | grep -i transfer

Migration Failed

If a migration fails:

1. The server remains on the source node in its pre-migration state
2. The source agent retains all original files
3. Any partial data on the target is cleaned up
4. The server's allocation and configuration are not changed

Check the API logs for the specific failure reason:

docker compose logs api | grep -i transfer

"Insufficient Resources" Error

The target node does not have enough free resources. Check:

• Available memory: total memory minus allocated memory
• Available disk: total disk minus allocated disk
• Available allocations: unassigned IP:port pairs

"Server Is Currently Locked"

Another operation (installation, backup, previous transfer) is in progress. Wait for it to complete before attempting migration.

Best Practices

1. Schedule during off-peak hours -- Migrations cause brief downtime. Notify affected users in advance using the Announcements feature.

2. Verify after migration -- After the migration completes, verify the server starts correctly and players can connect.

3. Update DNS -- If game servers use DNS names tied to specific nodes, update the records after migration.

4. Test with a non-production server -- Before migrating critical servers, test the migration process with a test server.

5. Back up first -- Create a backup of the server before migrating as a safety net.

Next Steps

• Troubleshooting -- General troubleshooting
• API Endpoints -- Migration via the API
• Architecture -- Understanding the distributed system