Skip to main content
A few OpenHands-specific properties may make a cluster upgrade more high-touch than usual. Sandboxes run on a Sysbox node pool. The pods in this node pool carry a zero-tolerance pod disruption budget which means that typical upgrade operations will hang indefinitely while those pods refuse eviction. This page collects general guidance that applies on any managed Kubernetes offering (GKE, EKS, AKS) or on self-managed clusters. See the information below in an advisory capacity, rather than a runbook. Upgrade in this order: control plane first, then your ordinary node pools, then the Sysbox pool. Never let nodes run ahead of the control plane. Only the sysbox node pool may need special handling

​
Control Plane

A plain upgrade is fine. Follow the usual pre-upgrade best practices for your platform, such as:
  • Review removed and deprecated APIs for the target version and confirm nothing you deploy still uses them. Most managed platforms surface this for you — GKE deprecation insights, kubectl get --raw /metrics | grep apiserver_requested_deprecated_apis, or a tool like Pluto against your manifests.
  • Move one minor version at a time and check the version skew policy of your provider before you start.
  • Expect the upgrade to be one-way. No managed platform lets you roll a control plane back, so verify on a non-production cluster first if you have one.
OpenHands itself is unaffected by a control-plane upgrade. Sandboxes keep running throughout.

​
Non-Sandbox Node Pools

Also a plain upgrade. A standard surge upgrade is appropriate here — the platform brings up new nodes, drains the old ones, and your workloads reschedule. Expect roughly the same behavior you would see when upgrading OpenHands itself: server and supporting pods restart, in-flight requests may blip, and the UI briefly reconnects. If your OpenHands deployment runs a single replica, that blip is a short outage. Scale up beforehand if you need to avoid it — see Resource Limits for replica and autoscaling settings. Running sandboxes are not affected, since they live on the Sysbox pool.

​
Sysbox Node Pool

This is the pool that needs a decision. Sandbox pods refuse eviction while they are alive, so a plain drain will not complete — the upgrade hangs rather than fails, often with no obvious signal beyond a node stuck in SchedulingDisabled. Pick a branch based on whether you can tolerate interrupting active conversations.
Simpler and needs no extra capacity, but it ends active conversations.
  1. Cordon the Sysbox nodes so no new sandboxes land on them, and lower the pool’s autoscaler ceiling if it has one.
  2. Drain the remaining sandboxes. Either wait for active conversations to finish, or end them. The upgrade will not proceed while sandbox pods are still alive, so getting to zero is the gating step — not an optimization.
  3. Confirm the pool is empty before starting:
  4. Run a plain upgrade on the pool once no sandbox pods remain.
Communicate the window to your users. From their side, an ended sandbox looks like a conversation that stopped working.

​
Pod Disruption Budgets

The sandbox disruption budget only interferes when active sandboxes are in play. Once no sandbox pods are running, it is inert and the pool upgrades like any other. That is why both branches above converge on the same thing: get the pool to zero sandboxes, by attrition or by ending them, and the rest is ordinary. If an upgrade appears to hang, check what is still holding the budget:

​
Upgrading OpenHands Itself

Cluster upgrades are independent of OpenHands releases. To upgrade the OpenHands Enterprise chart, see Install with Helm and the Release Notes. Avoid changing both at once: upgrade the cluster, verify sandboxes still launch, and only then move the application version.

​
Additional Info

Installing Sysbox

Requirements and installation for the sandbox node pool runtime.

Resource Limits

Size the application and sandbox workloads before planning capacity.