From 1374e2f8a04859ae0ff14aaa177c69f4341c2207 Mon Sep 17 00:00:00 2001 From: Samuel Vasconcelos Date: Tue, 14 Apr 2026 20:27:52 -0300 Subject: [PATCH 1/3] add VM stuck in PreparingRepo when node subnet overlaps known issue Signed-off-by: Samuel Vasconcelos --- docs/upgrade/v1-6-x-to-v1-7-x.md | 55 ++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/upgrade/v1-6-x-to-v1-7-x.md b/docs/upgrade/v1-6-x-to-v1-7-x.md index dd2e8d9d64b..f5f8bfb4d31 100644 --- a/docs/upgrade/v1-6-x-to-v1-7-x.md +++ b/docs/upgrade/v1-6-x-to-v1-7-x.md @@ -293,3 +293,58 @@ Example: To clear the message, restart the affected virtual machines at your next scheduled maintenance window. Related issue: [#9751](https://github.com/harvester/harvester/issues/9751) + +### 5. Upgrade may get stuck in PreparingRepo when node subnet overlaps with KubeVirt default masquerade CIDR + +The upgrade process may become stuck in the `PreparingRepo` phase when the node network overlaps with KubeVirt’s default masquerade CIDR (`10.0.2.0/24`). In this situation, the upgrade repository VM (`upgrade-repo-hvst-*`) is running but not reachable from other nodes. + +This issue occurs because KubeVirt uses `10.0.2.0/24` as the default internal network for virtual machines when `VMNetworkCIDR` is not explicitly configured. If the Harvester nodes are also using this subnet, a routing conflict occurs between the VM guest network and the host network. + +You may encounter the following symptoms: + + ``` + $ kubectl -n harvester-system get vm + NAME AGE STATUS READY + upgrade-repo-hvst-upgrade-xxxxx XXm Running False + ``` + +The readiness probe fails with timeout errors: + + ``` + Readiness probe failed: Get "http://:80/harvester-iso/harvester-release.yaml": + context deadline exceeded (Client.Timeout exceeded while awaiting headers) + ``` + +To address the issue, perform the following steps: + + 1. Edit the upgrade repo VM and change the network interface from masquerade to bridge. + + ``` + $ kubectl edit vm upgrade-repo- -n harvester-system + ``` + + Locate the interfaces section: + + ``` + interfaces: + - masquerade: {} + model: virtio + name: default + ``` + + Change it to: + + ``` + interfaces: + - bridge: {} + model: virtio + name: default + ``` + + 2. Restart the virtual machine: + + ``` + $ virtctl stop upgrade-repo- -n harvester-system + $ virtctl start upgrade-repo- -n harvester-system + ``` + \ No newline at end of file From 1102fce67681435eb41dfe4dd8b5e50bfe1205d3 Mon Sep 17 00:00:00 2001 From: Samuel Vasconcelos Date: Tue, 14 Apr 2026 20:41:09 -0300 Subject: [PATCH 2/3] apply suggestions Signed-off-by: Samuel Vasconcelos --- docs/upgrade/v1-6-x-to-v1-7-x.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/upgrade/v1-6-x-to-v1-7-x.md b/docs/upgrade/v1-6-x-to-v1-7-x.md index f5f8bfb4d31..f83ca23df83 100644 --- a/docs/upgrade/v1-6-x-to-v1-7-x.md +++ b/docs/upgrade/v1-6-x-to-v1-7-x.md @@ -296,7 +296,7 @@ Related issue: [#9751](https://github.com/harvester/harvester/issues/9751) ### 5. Upgrade may get stuck in PreparingRepo when node subnet overlaps with KubeVirt default masquerade CIDR -The upgrade process may become stuck in the `PreparingRepo` phase when the node network overlaps with KubeVirt’s default masquerade CIDR (`10.0.2.0/24`). In this situation, the upgrade repository VM (`upgrade-repo-hvst-*`) is running but not reachable from other nodes. +The upgrade process may become stuck in the `PreparingRepo` phase when the node network overlaps with KubeVirt’s default masquerade CIDR (`10.0.2.0/24`). In this situation, the upgrade repository VM (`upgrade-repo-hvst-xxxx`) is running but not reachable from other nodes. This issue occurs because KubeVirt uses `10.0.2.0/24` as the default internal network for virtual machines when `VMNetworkCIDR` is not explicitly configured. If the Harvester nodes are also using this subnet, a routing conflict occurs between the VM guest network and the host network. @@ -305,7 +305,7 @@ You may encounter the following symptoms: ``` $ kubectl -n harvester-system get vm NAME AGE STATUS READY - upgrade-repo-hvst-upgrade-xxxxx XXm Running False + upgrade-repo-hvst-xxxx XXm Running False ``` The readiness probe fails with timeout errors: @@ -343,8 +343,8 @@ To address the issue, perform the following steps: 2. Restart the virtual machine: - ``` - $ virtctl stop upgrade-repo- -n harvester-system - $ virtctl start upgrade-repo- -n harvester-system - ``` + ``` + $ virtctl stop upgrade-repo- -n harvester-system + $ virtctl start upgrade-repo- -n harvester-system + ``` \ No newline at end of file From 168027ae8490be3ec11c29e171b7f2a06436ad00 Mon Sep 17 00:00:00 2001 From: Samuel Vasconcelos Date: Wed, 15 Apr 2026 11:36:32 -0300 Subject: [PATCH 3/3] apply suggestions Signed-off-by: Samuel Vasconcelos --- .../version-v1.7/upgrade/v1-6-x-to-v1-7-x.md | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/versioned_docs/version-v1.7/upgrade/v1-6-x-to-v1-7-x.md b/versioned_docs/version-v1.7/upgrade/v1-6-x-to-v1-7-x.md index dd2e8d9d64b..ddd44d0453c 100644 --- a/versioned_docs/version-v1.7/upgrade/v1-6-x-to-v1-7-x.md +++ b/versioned_docs/version-v1.7/upgrade/v1-6-x-to-v1-7-x.md @@ -293,3 +293,57 @@ Example: To clear the message, restart the affected virtual machines at your next scheduled maintenance window. Related issue: [#9751](https://github.com/harvester/harvester/issues/9751) + +### 5. Upgrade may get stuck in PreparingRepo when node subnet overlaps with KubeVirt default masquerade CIDR + +The upgrade process may become stuck in the `PreparingRepo` phase when the node network overlaps with KubeVirt’s default masquerade CIDR (`10.0.2.0/24`). In this situation, the upgrade repository VM (`upgrade-repo-hvst-xxxx`) is running but not reachable from other nodes. + +This issue occurs because KubeVirt uses `10.0.2.0/24` as the default internal network for virtual machines when `VMNetworkCIDR` is not explicitly configured. If the Harvester nodes are also using this subnet, a routing conflict occurs between the VM guest network and the host network. + +You may encounter the following symptoms: + + ``` + $ kubectl -n harvester-system get vm + NAME AGE STATUS READY + upgrade-repo-hvst-xxxx XXm Running False + ``` + +The readiness probe fails with timeout errors: + + ``` + Readiness probe failed: Get "http://:80/harvester-iso/harvester-release.yaml": + context deadline exceeded (Client.Timeout exceeded while awaiting headers) + ``` + +To address the issue, perform the following steps: + + 1. Edit the upgrade repo VM and change the network interface from masquerade to bridge. + + ``` + $ kubectl edit vm upgrade-repo- -n harvester-system + ``` + + Locate the interfaces section: + + ``` + interfaces: + - masquerade: {} + model: virtio + name: default + ``` + + Change it to: + + ``` + interfaces: + - bridge: {} + model: virtio + name: default + ``` + + 2. Restart the virtual machine: + + ``` + $ virtctl stop upgrade-repo- -n harvester-system + $ virtctl start upgrade-repo- -n harvester-system + ```