Andrew Mercer
on this page

24.1 How upgrades work

Harvester upgrades the entire stack as one unit — OS, RKE2, Rancher, KubeVirt, Longhorn, Harvester components:

  1. A Version object (auto-fetched online or created manually with the ISO URL) announces an available upgrade.
  2. Pre-flight checks: all nodes ready, Longhorn volumes healthy (no degraded volumes), free disk space, no stuck migrations.
  3. The upgrade repo VM/pod serves the new ISO content inside the cluster.
  4. Cluster components upgrade (Rancher, Harvester charts).
  5. Nodes upgrade one by one: put into maintenance (VMs live-migrate), OS image written to the passive partition (A/B), reboot, rejoin.
  6. Post-upgrade cleanup.

24.2 Upgrade discipline

  • Read the upgrade notes for every hop. Only certain source→target paths are supported (typically from the previous minor's latest patch). You may need intermediate hops.
  • Stop or prepare non-migratable VMs (passthrough, local LVM) — they block node draining.
  • Ensure backups are current.
  • Check Rancher compatibility before upgrading Harvester (and vice-versa).
  • Have enough spare capacity to evacuate one node's VMs.
  • Upgrade guest clusters' Harvester CSI/CCM charts when advised.
  • Watch progress: kubectl -n harvester-system get upgrades.harvesterhci.io -o yaml and the upgrade pods' logs.

24.3 Air-gapped upgrade

Download the ISO, host it on an internal HTTP server, and create a Version:

apiVersion: harvesterhci.io/v1beta1
kind: Version
metadata:
  name: v1.9.0
  namespace: harvester-system
spec:
  isoURL: http://repo.internal.example.net/harvester/harvester-v1.9.0-amd64.iso
  isoChecksum: "<sha512 from release>"
  releaseDate: "2026-09-16"

Then click Upgrade in the UI.

← Observability · Index · Air-gapped deployments →