Upgrading BadgerOrchestrator

This guide covers how to upgrade the BadgerOrchestrator running in your Kubernetes cluster. Orchestrator upgrades are typically required after updating the panel to maintain protocol compatibility.

Before You Begin

Check Current Version

# Check the running orchestrator version
kubectl -n badgerpanel-system logs deployment/badgerpanel-orchestrator | head -5

Or check in the panel admin area under Admin > Clusters -- each cluster shows its running orchestrator version.

Review Release Notes

Before upgrading, check if the new version requires:

• Updated RBAC permissions (new Kubernetes API access)
• Configuration changes (new or renamed fields)
• A minimum Kubernetes version

Upgrade Process

Option A: Image Tag Update (Recommended)

If the orchestrator is deployed using a container image:

# Update the deployment to use the latest image
kubectl -n badgerpanel-system set image deployment/badgerpanel-orchestrator \
  orchestrator=badgerpanel/orchestrator:latest

# Or pin to a specific version
kubectl -n badgerpanel-system set image deployment/badgerpanel-orchestrator \
  orchestrator=badgerpanel/orchestrator:1.1.0

Kubernetes will perform a rolling update, starting a new pod with the updated image before terminating the old one.

Option B: Re-apply the Manifest

If you used the panel-generated manifest during installation:

1. Go to Admin > Clusters in the panel
2. Click on the cluster
3. Go to the Installation tab
4. Download the latest manifest (it will reference the latest orchestrator version)
5. Apply it:

kubectl apply -f orchestrator-manifest.yaml

Option C: Manual Binary Update

If you built a custom image with the orchestrator binary:

1. Download the latest binary from your panel:

# Determine architecture
# amd64 for most servers, arm64 for ARM-based clusters
curl -o orchestrator \
  "https://panel.your-domain.com/api/v1/orchestrator/download?arch=amd64"

2. Build a new container image with the updated binary
3. Push the image to your registry
4. Update the deployment:

kubectl -n badgerpanel-system set image deployment/badgerpanel-orchestrator \
  orchestrator=your-registry.com/badgerpanel-orchestrator:new-version

Monitoring the Upgrade

Watch the Rolling Update

kubectl -n badgerpanel-system rollout status deployment/badgerpanel-orchestrator

Verify the New Pod

# Check pod status
kubectl -n badgerpanel-system get pods -l app.kubernetes.io/component=orchestrator

# Check logs for successful startup
kubectl -n badgerpanel-system logs deployment/badgerpanel-orchestrator --tail 30

Verify in the Panel

After the upgrade:

1. Navigate to Admin > Clusters
2. Confirm the cluster shows as online
3. Verify the orchestrator version is updated
4. Check that cluster node and pod information is reporting correctly
5. Test creating or managing a server on the cluster

Updating RBAC Permissions

Some orchestrator upgrades may require additional Kubernetes API permissions. If the upgrade includes RBAC changes:

# Re-apply the RBAC manifests
kubectl apply -f rbac.yaml

# Or re-apply the full manifest from the panel
kubectl apply -f orchestrator-manifest.yaml

Signs that RBAC needs updating:

• Orchestrator logs show "forbidden" errors after the upgrade
• Certain operations (e.g., pod exec, node management) stop working
• The release notes mention new RBAC requirements

Rolling Back

If the upgrade causes issues, Kubernetes makes rollbacks straightforward:

# Roll back to the previous version
kubectl -n badgerpanel-system rollout undo deployment/badgerpanel-orchestrator

# Verify the rollback
kubectl -n badgerpanel-system rollout status deployment/badgerpanel-orchestrator
kubectl -n badgerpanel-system get pods

Rollback History

Kubernetes keeps a history of deployments by default. You can roll back to any previous revision:

# View revision history
kubectl -n badgerpanel-system rollout history deployment/badgerpanel-orchestrator

# Roll back to a specific revision
kubectl -n badgerpanel-system rollout undo deployment/badgerpanel-orchestrator --to-revision=2

Upgrading Multiple Clusters

If you manage multiple Kubernetes clusters with BadgerOrchestrator:

1. Upgrade one cluster first as a canary
2. Verify the upgrade works correctly
3. Upgrade remaining clusters sequentially or in parallel

# Iterate through kubeconfig contexts
for ctx in cluster-1 cluster-2 cluster-3; do
  echo "Upgrading $ctx..."
  kubectl --context $ctx -n badgerpanel-system set image \
    deployment/badgerpanel-orchestrator \
    orchestrator=badgerpanel/orchestrator:latest
done

Impact on Running Servers

During the orchestrator upgrade:

• Running game server pods are not affected -- they continue running independently
• Console streaming is briefly interrupted (reconnects automatically)
• Management operations (start, stop, restart) are unavailable during the ~10-30 second rollover
• No data loss occurs -- PersistentVolumeClaims are not affected

Zero-Downtime

Because Kubernetes performs a rolling update by default (starting the new pod before terminating the old one), the downtime window for management operations is minimal.

Next Steps

• Orchestrator Configuration -- Review configuration options
• Troubleshooting -- Common issues and solutions