Skip to main content

Upgrade K8s Cluster Version

Upgrade your Kubernetes cluster to a new version, including how to migrate stateless and stateful workloads.

Hyperstack Kubernetes is on-demand and does not support in-place version upgrades. To move an existing cluster to a newer Kubernetes version, deploy a new cluster on the target version and migrate your workloads to it.

The four steps below walk through the full procedure in order. Stateless workloads can be redeployed directly; stateful workloads require additional planning for cross-cluster data migration. See Step 3.

Procedure at a glance​

  1. Deploy a new cluster on the target Kubernetes version.
  2. Test your workloads in the new cluster before cutting traffic over.
  3. Migrate workloads: redeploy stateless applications; plan data migration for stateful ones.
  4. Delete the old cluster once the migration is verified.

Step 1: Deploy a new cluster on the target version​

Create a new cluster on the desired Kubernetes version. Deploy through the Deploy a New Cluster page in the Hyperstack Console or via the Create Cluster API. For step-by-step instructions, see Deploy a Kubernetes Cluster.

Current supported Kubernetes versions: 1.33.4, 1.35.1, and 1.36.1 (default).

By default, Hyperstack pre-selects the latest supported Kubernetes version for you. When a newer version becomes available, it automatically becomes the pre-selected default for new clusters. For the latest supported versions, regional availability, and the images that come pre-configured with each version, call the List Cluster Versions API.

Keep your existing cluster running while the new cluster is provisioned and validated. This avoids workload downtime and gives you a way to roll back if validation fails.

Step 2: Test workloads in the new cluster​

Redeploy your workloads to the new cluster in a non-production capacity. Verify that container images, manifests, and any cluster-level dependencies all behave correctly on the new Kubernetes version before moving any production traffic over.

Review Kubernetes deprecations

Each Kubernetes minor version may deprecate or remove APIs your manifests rely on. Before redeploying, review the Kubernetes Deprecated API Migration Guide for every minor version between your current and target Kubernetes versions.

Step 3: Migrate workloads​

Once the new cluster is validated, migrate your workloads from the old cluster to the new one. The migration mechanism depends on whether each workload is stateless or stateful.

Stateless workloads​

Stateless workloads (e.g., front-end services, stateless APIs, batch jobs that read or write only to external systems) do not retain local state between pod restarts. To migrate:

  1. Apply your existing deployment configuration to the new cluster using your usual deployment tooling.
  2. Verify pods reach the Running state and the workload is reachable.
  3. Cut traffic over from the old cluster to the new cluster using whatever mechanism fronts your services.

No data migration is required.

Stateful workloads​

Stateful workloads (e.g., databases, message queues, file-backed services, anything with persistent volumes) require a data-migration plan in addition to redeploying the workload. Persistent state on the old cluster is not automatically available to the new cluster.

The pattern below is a starting point. The right migration approach depends on your application's data shape, recovery requirements, and operational constraints. Hyperstack provides the storage, and you bring the design, tooling, and execution that fit your application.

The general pattern is:

  1. Bring the data on the old cluster to a consistent state (database dump, application-level export, etc.).
  2. Move the data to a location reachable from the new cluster, typically Object Storage.
  3. Restore the data on the new cluster according to your application's normal restore procedure.
  4. Verify data integrity end-to-end before cutting traffic over.
The Hyperstack CSI Driver does not migrate data across clusters

The Hyperstack CSI Driver creates new persistent volumes when your workload requests them. It does not provide a way to attach an existing volume's data to a new cluster, and cannot be used to carry data from one cluster to another during an upgrade. Use Object Storage or an application-level export and import instead.

Migrating data via Object Storage​

Hyperstack Object Storage is an S3-compatible service whose buckets can be reached from both the old and new clusters using standard S3 tooling. Common patterns include uploading data exports (database dumps, archives, media assets, model checkpoints, etc.) from the old cluster and restoring them on the new cluster.

How you export, move, and verify the data depends on your application's needs. Hyperstack provides the bucket and connectivity; you choose the tooling and procedure that fit your workload.

Step 4: Delete the old cluster​

Once your new cluster is serving all production workloads and you have verified data integrity, delete the old cluster. This stops billing on its VMs and public IP addresses:

  1. Confirm no workload is still reading from or writing to the old cluster.
  2. Export any cluster-level configuration you want to retain.
  3. Delete the old cluster from the Kubernetes page in the Hyperstack Console or via the Delete Cluster API. For step-by-step instructions, see Delete Cluster.
Persistent volumes are deleted with the cluster

When a cluster is deleted, persistent volumes provisioned by the Hyperstack CSI Driver on that cluster are handled according to the StorageClass's reclaimPolicy. The default csi-hyperstack StorageClass ships with reclaimPolicy: Delete, which means dynamically provisioned volumes and the data they hold are deleted along with the cluster. Any data still required by the new cluster must be migrated via Object Storage before deleting the old cluster. See Step 3.

Need help?

For questions about your migration, contact [email protected].


Back to top

On this page