Skip to content

Commit d6fc53c

Browse files
jillian-maroketjillian-maroket
authored
Merge pull request #245 from jillian-maroket/communityprs16
Port content from community doc PRs (1011, 1020)
2 parents 96a3cfb + 4b080ca commit d6fc53c

5 files changed

Lines changed: 304 additions & 1 deletion

File tree

‎versions/v1.8/modules/en/images/upgrade/kubevirt-not-ready.png‎

76.5 KB
Loading

‎versions/v1.8/modules/en/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@
4040
** xref:upgrades/v1-6-x-to-v1-6-y.adoc[]
4141
** xref:upgrades/v1-6-x-to-v1-7-x.adoc[]
4242
** xref:upgrades/v1-7-x-to-v1-7-y.adoc[]
43+
** xref:upgrades/v1-7-x-to-v1-8-x.adoc[]
4344
** xref:upgrades/troubleshooting.adoc[]
4445
4546
// Folder: hosts:

‎versions/v1.8/modules/en/pages/integrations/rancher/csi-driver.adoc‎

Lines changed: 165 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
= Harvester CSI Driver
2-
:revdate: 2026-06-03
2+
:revdate: 2026-06-09
33
:page-revdate: {revdate}
44

55
The Harvester Container Storage Interface (CSI) driver provides a standard CSI interface used by guest Kubernetes clusters. It connects to the {harvester-product-name} cluster and hot-plugs volumes to the virtual machines to provide native storage performance.
@@ -510,6 +510,170 @@ Starting with *v0.1.25*, the Harvester CSI Driver supports https://kubernetes.io
510510
* Harvester CSI Driver v0.1.25 or later
511511
* The CSI snapshot controller and the required manifests are properly deployed on the guest cluster. These components are deployed by default on RKE2.
512512

513+
== Volume backups
514+
515+
Starting with **v0.1.28**, the Harvester CSI Driver supports remote volume backup and restore for guest Kubernetes clusters. This feature allows you to back up a PersistentVolumeClaim (PVC) to the {harvester-product-name} backup target, and subsequently restore it to either the source guest cluster or a different guest cluster running on the same {harvester-product-name} cluster.
516+
517+
=== Prerequisites
518+
519+
* {harvester-product-name} v1.8 or later
520+
* Harvester CSI Driver v0.1.28 or later
521+
* The CSI snapshot controller, along with its required CRDs and deployment manifests, is properly deployed on the guest cluster.
522+
* A backup target is configured and ready on the {harvester-product-name} cluster.
523+
524+
To verify the status of the CSI snapshot controller and the required CRDs, run the following commands on RKE2:
525+
526+
[,shell]
527+
----
528+
$ kubectl -n kube-system get po -lapp.kubernetes.io/name=rke2-snapshot-controller
529+
NAME READY STATUS RESTARTS AGE
530+
rke2-snapshot-controller-858d65d54-nvlfq 1/1 Running 0 5d17h
531+
532+
$ kubectl get crd --show-labels | grep -i volumesnapshot
533+
volumesnapshotclasses.snapshot.storage.k8s.io 2026-04-16T23:26:24Z app.kubernetes.io/managed-by=Helm
534+
volumesnapshotcontents.snapshot.storage.k8s.io 2026-04-16T23:26:24Z app.kubernetes.io/managed-by=Helm
535+
volumesnapshots.snapshot.storage.k8s.io 2026-04-16T23:26:24Z app.kubernetes.io/managed-by=Helm
536+
----
537+
538+
=== Creating a volume backup
539+
540+
. Create a `VolumeSnapshotClass` for backups on the guest cluster.
541+
+
542+
[,yaml]
543+
----
544+
apiVersion: snapshot.storage.k8s.io/v1
545+
deletionPolicy: Delete
546+
driver: driver.harvesterhci.io
547+
kind: VolumeSnapshotClass
548+
metadata:
549+
name: harvester-backup
550+
parameters:
551+
type: backup
552+
----
553+
554+
. Create a `VolumeSnapshot` for the source PVC.
555+
+
556+
[,yaml]
557+
----
558+
apiVersion: snapshot.storage.k8s.io/v1
559+
kind: VolumeSnapshot
560+
metadata:
561+
name: snapshot-fs-vol
562+
namespace: default
563+
spec:
564+
volumeSnapshotClassName: harvester-backup
565+
source:
566+
persistentVolumeClaimName: fs-vol
567+
----
568+
569+
. Wait until the `VolumeSnapshot` becomes ready to use.
570+
+
571+
[,shell]
572+
----
573+
kubectl get volumesnapshot snapshot-fs-vol -n default
574+
----
575+
+
576+
Once the `VolumeSnapshot` is ready, a corresponding `VolumeRemoteBackup` resource is automatically generated on the underlying {harvester-product-name} cluster for restore operations.
577+
578+
. On the {harvester-product-name} cluster, retrieve a list of the generated `VolumeRemoteBackup` resources.
579+
+
580+
[,shell]
581+
----
582+
kubectl get volumeremotebackups -A
583+
----
584+
585+
=== Restoring a backup on the same guest cluster
586+
587+
. Create a new PVC and set its `spec.dataSource` to the backup `VolumeSnapshot`.
588+
+
589+
[,yaml]
590+
----
591+
apiVersion: v1
592+
kind: PersistentVolumeClaim
593+
metadata:
594+
name: restore-fs-vol
595+
namespace: default
596+
spec:
597+
accessModes:
598+
- ReadWriteOnce
599+
resources:
600+
requests:
601+
storage: 2Gi
602+
storageClassName: harvester
603+
dataSource:
604+
apiGroup: snapshot.storage.k8s.io
605+
kind: VolumeSnapshot
606+
name: snapshot-fs-vol
607+
volumeMode: Filesystem
608+
----
609+
610+
. Once the PVC is bound, mount it to a pod and verify that the restored data is intact.
611+
612+
=== Restoring a backup on a different guest cluster
613+
614+
You can restore a backup on a different guest cluster _running on the same {harvester-product-name} cluster_.
615+
616+
. On the source guest cluster, <<Creating a volume backup, create a backup>>.
617+
618+
. On the target guest cluster, create a `VolumeSnapshotContent` that points to the {harvester-product-name} backup handle in the format `backup:<VolumeRemoteBackup namespace>/<VolumeRemoteBackup name>`.
619+
+
620+
[,yaml]
621+
----
622+
apiVersion: snapshot.storage.k8s.io/v1
623+
kind: VolumeSnapshotContent
624+
metadata:
625+
name: backup-fs-vol-vsc
626+
spec:
627+
deletionPolicy: Delete
628+
driver: driver.harvesterhci.io
629+
source:
630+
snapshotHandle: backup:<VolumeRemoteBackup namespace>/<VolumeRemoteBackup name>
631+
volumeSnapshotClassName: harvester-backup
632+
volumeSnapshotRef:
633+
name: backup-fs-vol
634+
namespace: default
635+
----
636+
637+
. Create a `VolumeSnapshot` from the `VolumeSnapshotContent`.
638+
+
639+
[,yaml]
640+
----
641+
apiVersion: snapshot.storage.k8s.io/v1
642+
kind: VolumeSnapshot
643+
metadata:
644+
name: backup-fs-vol
645+
namespace: default
646+
spec:
647+
volumeSnapshotClassName: harvester-backup
648+
source:
649+
volumeSnapshotContentName: backup-fs-vol-vsc
650+
----
651+
652+
. Create a restore PVC from the `VolumeSnapshot`.
653+
+
654+
[,yaml]
655+
----
656+
apiVersion: v1
657+
kind: PersistentVolumeClaim
658+
metadata:
659+
name: restore-fs-vol
660+
namespace: default
661+
spec:
662+
accessModes:
663+
- ReadWriteOnce
664+
resources:
665+
requests:
666+
storage: 2Gi
667+
storageClassName: harvester
668+
dataSource:
669+
apiGroup: snapshot.storage.k8s.io
670+
kind: VolumeSnapshot
671+
name: backup-fs-vol
672+
volumeMode: Filesystem
673+
----
674+
675+
. Once the PVC is bound, attach it to a workload on the target guest cluster and verify that the data was restored successfully.
676+
513677
== Upgrade the CSI Driver
514678

515679
[NOTE]

‎versions/v1.8/modules/en/pages/upgrades/upgrades.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ The following table outlines the supported upgrade paths.
2020
|===
2121
| Installed Version | Supported Upgrade Versions
2222

23+
| v1.7.x
24+
| xref:upgrades/v1-7-x-to-v1-8-x.adoc[v1.8.x]
25+
2326
| v1.7.x
2427
| xref:upgrades/v1-7-x-to-v1-7-y.adoc[v1.7.y] (_y_ is greater than _x_)
2528

‎versions/v1.8/modules/en/pages/upgrades/v1-7-x-to-v1-8-x.adoc‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
= Upgrade from v1.7.x to v1.8.x
2+
:revdate: 2026-06-09
3+
:page-revdate: {revdate}
4+
5+
== General information
6+
7+
An *Upgrade* button appears on the *Dashboard* screen whenever a new {harvester-product-name} version that you can upgrade to becomes available. For more information, see xref:upgrades/upgrades.adoc#_start_an_upgrade[Start an upgrade].
8+
9+
Clusters running v1.7.x can upgrade to v1.8.x directly because {harvester-product-name} allows a maximum of one minor version upgrade for underlying components. {harvester-product-name} v1.7.0 and v1.7.1 use the same minor version of RKE2 (v1.34), while {harvester-product-name} v1.8.0 uses the next minor version (v1.35). For more information, see xref:upgrades/upgrades.adoc#_upgrade_paths[Upgrade paths].
10+
11+
For information about upgrading {harvester-product-name} in air-gapped environments, see xref:upgrades/upgrades.adoc#_prepare_an_air_gapped_upgrade[Prepare an air-gapped upgrade].
12+
13+
[CAUTION]
14+
====
15+
Support for legacy BIOS booting is removed in v1.8.0. Existing {harvester-product-name} clusters that use this boot mode will continue to function, but upgrading to later versions may require re-installation in UEFI mode. To avoid issues and disruptions, use UEFI in new installations.
16+
====
17+
18+
=== Update the Harvester UI Extension on {rancher-product-name} v2.14
19+
20+
You must use a compatible version (v1.8.x) of the Harvester UI Extension to import {harvester-product-name} v1.8.x clusters on {rancher-short-name} v2.14.
21+
22+
. On the {rancher-short-name} UI, go to *local -> Apps -> Repositories*.
23+
24+
. Locate the repository named *harvester*, and then select *⋮ -> Refresh*.
25+
26+
. Go to the *Extensions* screen.
27+
28+
. Locate the extension named *Harvester*, and then click *Update*.
29+
30+
. Select a compatible version, and then click *Update*.
31+
32+
. Allow some time for the extension to be updated, and then refresh the screen.
33+
34+
== Known issues
35+
36+
=== Virtual machines fail to migrate with "KubeVirt is not ready" error
37+
38+
After upgrading to v1.8.x, virtual machines may fail to migrate with the error message "KubeVirt is not ready". This issue occurs due to a race condition where a `virt-handler` pod is created without the annotations KubeVirt needs to determine whether the pod is up-to-date.
39+
40+
image::upgrade/kubevirt-not-ready.png["KubeVirt is not ready" error message]
41+
42+
The KubeVirt operator continuously waits for the outdated `virt-handler` pod to terminate, preventing the KubeVirt custom resource from reaching the "Available" state. This blocks subsequent virtual machine operations, including live migration.
43+
44+
[NOTE]
45+
====
46+
This issue has been observed in three-node clusters with one witness node, but it may also occur in other deployment configurations.
47+
====
48+
49+
==== Identifying the issue
50+
51+
. Check the status of the KubeVirt custom resource.
52+
+
53+
[,bash]
54+
----
55+
kubectl get kubevirt/kubevirt -n harvester-system -o yaml | yq '.status.conditions'
56+
----
57+
+
58+
If your environment is affected, the `Available` condition will be set to `False` with the reason `DeploymentInProgress`.
59+
+
60+
[,yaml]
61+
----
62+
- lastProbeTime: "2026-04-18T17:42:39Z"
63+
lastTransitionTime: "2026-04-18T17:42:39Z"
64+
message: Deploying version 1.7.0-150700.3.16.2 with registry registry.suse.com/suse/sles/15.7
65+
reason: DeploymentInProgress
66+
status: "False"
67+
type: Available
68+
----
69+
70+
. Check the `virt-operator` logs.
71+
+
72+
[,bash]
73+
----
74+
kubectl logs deployment/virt-operator -n harvester-system --tail 10 | grep waiting
75+
----
76+
+
77+
The logs will contain messages indicating that the DaemonSet is waiting for outdated pods to terminate.
78+
+
79+
[,shell]
80+
----
81+
{"component":"virt-operator","level":"info","msg":"DaemonSet virt-handler waiting for out of date pods to terminate.","pos":"readycheck.go:63","timestamp":"2026-04-20T02:19:14.503468Z"}
82+
----
83+
84+
. Identify the affected `virt-handler` pod by checking which instance lacks the required KubeVirt annotations.
85+
+
86+
[,bash]
87+
----
88+
kubectl get pods -n harvester-system -l kubevirt.io=virt-handler -o json | \
89+
jq -r '.items[] | "\(.metadata.name):\n" + ((.metadata.annotations // {}) | to_entries | map(select(.key | startswith("kubevirt.io/install-strategy-"))) | map(" \(.key): \(.value)") | join("\n")) + "\n"'
90+
----
91+
+
92+
The output displays the KubeVirt `install-strategy` annotations for each pod. The affected pod will lack these listed annotations entirely.
93+
+
94+
[,shell]
95+
----
96+
virt-handler-64r9v:
97+
kubevirt.io/install-strategy-identifier: 9890638436fb4150e2046eff9f500bc4f18812f8
98+
kubevirt.io/install-strategy-registry: registry.suse.com/suse/sles/15.7
99+
kubevirt.io/install-strategy-version: 1.7.0-150700.3.16.2
100+
101+
virt-handler-wzmdv:
102+
103+
----
104+
105+
==== Workaround
106+
107+
. Delete the affected `virt-handler` pod (for example, `virt-handler-wzmdv`).
108+
+
109+
[,bash]
110+
----
111+
kubectl delete pod virt-handler-wzmdv -n harvester-system
112+
----
113+
114+
. Wait for the pod to be recreated with the correct annotations, and then verify that the KubeVirt custom resource transitions to the `Available` state.
115+
+
116+
[,bash]
117+
----
118+
kubectl get kubevirt/kubevirt -n harvester-system -o yaml | yq '.status.conditions[] | select(.type == "Available")'
119+
----
120+
+
121+
The `Available` condition should be set to `True`.
122+
+
123+
[,yaml]
124+
----
125+
- lastProbeTime: "2026-04-18T17:45:00Z"
126+
lastTransitionTime: "2026-04-18T17:45:00Z"
127+
message: All components ready
128+
reason: AllComponentsReady
129+
status: "True"
130+
type: Available
131+
----
132+
133+
. Verify that virtual machine operations resume normal functionality.
134+
135+
Related issue: https://github.com/harvester/harvester/issues/10447[#10447]

0 commit comments

Comments
 (0)