Skip to content

Commit 769c22b

Browse files
jillian-maroketjillian-maroket
authored
Add description of Longhorn issue #11158 to upgrade pages (#813)
* Add Longhorn known issue & standardize headings and related issue links in v1.6 doc Signed-off-by: Jillian <jillian.maroket@suse.com> * Apply changes to v1.5 doc Signed-off-by: Jillian <jillian.maroket@suse.com> * Apply changes to v1.4 doc Signed-off-by: Jillian <jillian.maroket@suse.com> * Move horizontal rule to line between General Information and Known Issues Signed-off-by: Jillian <jillian.maroket@suse.com> * Fix admonition markup in v1.4.0-v1.4.1 Signed-off-by: Jillian <jillian.maroket@suse.com> * Align wording about component version upgrades Signed-off-by: Jillian <jillian.maroket@suse.com> * Improve wording about Harvester UI Extension version Signed-off-by: Jillian <jillian.maroket@suse.com> --------- Signed-off-by: Jillian <jillian.maroket@suse.com>
1 parent 0653f3e commit 769c22b

16 files changed

Lines changed: 382 additions & 302 deletions

‎docs/upgrade/v1-3-2-to-v1-4-0.md‎

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ title: "Upgrade from v1.3.2 to v1.4.0"
88
<link rel="canonical" href="https://docs.harvesterhci.io/v1.5/upgrade/v1-3-2-to-v1-4-0"/>
99
</head>
1010

11-
## General information
11+
## General Information
1212

1313
An **Upgrade** button appears on the **Dashboard** screen whenever a new Harvester version that you can upgrade to becomes available. For more information, see [Start an upgrade](./automatic.md#start-an-upgrade).
1414

@@ -257,10 +257,10 @@ To prevent the issue from occurring, you can manually update the `BackingImage`
257257

258258
3. Start the upgrade process.
259259

260-
## Known issues
261-
262260
---
263261

262+
## Known Issues
263+
264264
### 1. A VM with a container disk can't be migrated which makes the upgrade stuck in pre-drain status
265265

266266
:::tip
@@ -271,11 +271,9 @@ Manually stop the VMs to continue the upgrade process.
271271

272272
When upgrading from v1.3.2 to v1.4.0, the upgrade process may become stuck if a VM with a container disk cannot be migrated. There is some limitation of live migration.
273273

274-
For more information, see [Issue #7005](https://github.com/harvester/harvester/issues/7005).
275-
276-
---
274+
Related issue: [#7005](https://github.com/harvester/harvester/issues/7005)
277275

278-
### 2. Upgrade stuck on waiting for Harvester bundle
276+
### 2. Upgrade Stuck on Waiting for Harvester Bundle
279277

280278
When upgrading from v1.3.2 to v1.4.0, the upgrade process may become stuck on waiting for the Harvester bundle to become ready. This issue is caused by a race condition when the Fleet agent (`fleet-agent`) is redeployed.
281279

@@ -323,9 +321,7 @@ kubectl delete svc longhorn-engine-manager -n longhorn-system --ignore-not-found
323321
kubectl delete svc longhorn-replica-manager -n longhorn-system --ignore-not-found=true
324322
```
325323

326-
---
327-
328-
### 3. Upgrade stuck on waiting for Fleet
324+
### 3. Upgrade Stuck on Waiting for Fleet
329325

330326
When upgrading from v1.3.2 to v1.4.0, the upgrade process may become stuck on waiting for Fleet to become ready. This issue is caused by a race condition when Rancher is redeployed.
331327

@@ -354,9 +350,8 @@ You can run the following command to fix the issue.
354350
```shell
355351
helm rollback fleet -n cattle-fleet-system <last-deployed-revision>
356352
```
357-
---
358353

359-
### 4. Upgrade will start over again unexpectedly after clicking the "Dismiss it" button
354+
### 4. Upgrade Restarts Unexpectedly After the "Dismiss it" Button is Clicked
360355

361356
When you use Rancher to upgrade Harvester, the Rancher UI displays a dialog with a button labeled "Dismiss it". Clicking this button may result in the following issues:
362357

@@ -374,5 +369,14 @@ To avoid this issue, perform either of the following actions:
374369
kubectl -n harvester-system label upgrades -l harvesterhci.io/latestUpgrade=true harvesterhci.io/read-message=true
375370
```
376371

377-
Related issue:
378-
- [[BUG] upgrade controller does not handle read-message well due to UI menu `Dismiss it` wipes upgrade CR's status](https://github.com/harvester/harvester/issues/7791)
372+
Related issue: [#7791](https://github.com/harvester/harvester/issues/7791)
373+
374+
### 5. Virtual Machines That Use Migratable RWX Volumes Restart Unexpectedly
375+
376+
A [Longhorn issue](https://github.com/longhorn/longhorn/issues/11158) causes virtual machines that use migratable [RWX volumes](https://docs.harvesterhci.io/v1.5/rancher/csi-driver/#rwx-volumes-support) to restart unexpectedly when the CSI plugin pods are restarted. This issue affects Harvester v1.4.x, v1.5.0, and v1.5.1.
377+
378+
The workaround is to disable the setting [Automatically Delete Workload Pod When The Volume Is Detached Unexpectedly](https://longhorn.io/docs/1.8.0/references/settings/#automatically-delete-workload-pod-when-the-volume-is-detached-unexpectedly) on the Longhorn UI before starting the upgrade. You must enable the setting again once the upgrade is completed.
379+
380+
The issue will be fixed in Longhorn v1.8.3, v1.9.1, and later versions. Harvester v1.6.0 will include Longhorn v1.9.1.
381+
382+
Related issues: [#8534](https://github.com/harvester/harvester/issues/8534) and [#11158](https://github.com/longhorn/longhorn/issues/11158)

‎docs/upgrade/v1-4-0-to-v1-4-1.md‎

Lines changed: 44 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ title: "Upgrade from v1.4.0 to v1.4.1"
88
<link rel="canonical" href="https://docs.harvesterhci.io/v1.5/upgrade/v1-4-0-to-v1-4-1"/>
99
</head>
1010

11-
## General information
11+
## General Information
1212

1313
An **Upgrade** button appears on the **Dashboard** screen whenever a new Harvester version that you can upgrade to becomes available. For more information, see [Start an upgrade](./automatic.md#start-an-upgrade).
1414

@@ -34,14 +34,13 @@ If `passive.img` (which represents the previously installed Harvester v1.4.0 ima
3434
# mount -o remount,ro /run/initramfs/cos-state
3535
```
3636
`passive.img` is converted to a sparse file, which should only consume 1.7G of disk space (the same as `active.img`). This ensures that each node has enough free space, preventing the upgrade process from becoming [stuck in the "Waiting Reboot" state](#3-upgrade-is-stuck-in-the-waiting-reboot-state).
37-
:::
3837

38+
:::
3939

4040
### Update Harvester UI Extension on Rancher v2.10.1
4141

4242
To import Harvester v1.4.1 clusters on Rancher v2.10.1, you must use **v1.0.3** of the Rancher UI extension for Harvester.
4343

44-
4544
1. On the Rancher UI, go to **local > Apps > Repositories**.
4645

4746
1. Locate the repository named **harvester**, and then select **⋮ > Refresh**.
@@ -61,20 +60,20 @@ To import Harvester v1.4.1 clusters on Rancher v2.10.1, you must use **v1.0.3**
6160
1. Allow some time for the extension to be updated, and then refresh the screen.
6261

6362
:::info important
63+
6464
The Rancher UI displays an error message after the extension is updated. The error message disappears when you refresh the screen.
65-
This issue, which exists in Rancher v2.10.0 and v2.10.1, will be fixed in v2.10.2.
66-
:::
6765

68-
Related issues:
69-
- [Issue #7234](https://github.com/harvester/harvester/issues/7234)
70-
- [Issue #107](https://github.com/rancher/capi-ui-extension/issues/107)
66+
This issue, which exists in Rancher v2.10.0 and v2.10.1, will be fixed in v2.10.2.
7167

68+
:::
7269

73-
## Known issues
70+
Related issues: [#7234](https://github.com/harvester/harvester/issues/7234) and [#107](https://github.com/rancher/capi-ui-extension/issues/107)
7471

7572
---
7673

77-
### 1. Upgrade is stuck in the "Pre-drained" state
74+
## Known Issues
75+
76+
### 1. Upgrade is Stuck in the "Pre-drained" State
7877

7978
The upgrade process may become stuck in the "Pre-drained" state. Kubernetes is supposed to drain the workload on the node, but some factors may cause the process to stall.
8079

@@ -133,11 +132,9 @@ A possible cause is processes related to orphan engines of the Longhorn Instance
133132
kubectl delete pdb instance-manager-d80e13f520e7b952f4b7593fc1883e2a -n longhorn-system
134133
```
135134
136-
Related issues:
137-
- [[BUG] v1.4.0 -> v1.4.1-rc1 upgrade stuck in Pre-drained and the node stay in Cordoned](https://github.com/harvester/harvester/issues/7366)
138-
- [[IMPROVEMENT] Cleanup orphaned volume runtime resources if the resources already deleted](https://github.com/longhorn/longhorn/issues/6764)
135+
Related issues: [#7366](https://github.com/harvester/harvester/issues/7366) and [#6764](https://github.com/longhorn/longhorn/issues/6764)
139136
140-
### 2. Upgrade with default StorageClass that is not harvester-longhorn
137+
### 2. Upgrade with Default StorageClass That Is Not `harvester-longhorn`
141138
142139
Harvester adds the annotation `storageclass.kubernetes.io/is-default-class: "true"` to `harvester-longhorn`, which is the original default StorageClass. When you replace `harvester-longhorn` with another StorageClass, the following occur:
143140
@@ -165,9 +162,9 @@ You can perform any of the following workarounds:
165162
166163
![Upgrade with another default storage class workaround](/img/v1.4/upgrade/upgrade-with-another-default-storage-class-workaround.png)
167164
168-
For more information, see [Issue #7375](https://github.com/harvester/harvester/issues/7375).
165+
Related issue: [#7375](https://github.com/harvester/harvester/issues/7375)
169166
170-
### 3. Upgrade is stuck in the "Waiting Reboot" state
167+
### 3. Upgrade is Stuck in the "Waiting Reboot" State
171168
172169
The upgrade process may become stuck in the "Waiting Reboot" state after the Harvester v1.4.1 image is installed on a node and a reboot is initiated. At this point, the upgrade controller observes if the Harvester v1.4.1 operating system is running.
173170
@@ -268,22 +265,24 @@ To fix the issue, perform the following steps:
268265
The ISO can be mounted either on the stuck node or on another system. You can copy the file using the `scp` command.
269266
270267
1. Access the stuck node via SSH, and then run the following commands using the root account:
271-
```
272-
# mkdir /tmp/manual-os-upgrade
273-
# mkdir /tmp/manual-os-upgrade/config
274-
# mkdir /tmp/manual-os-upgrade/rootfs
275-
# mount -o loop rootfs.squashfs /tmp/manual-os-upgrade/rootfs
276-
# cat > /tmp/manual-os-upgrade/config/config.yaml <<EOF
277-
upgrade:
278-
system:
279-
size: 3072
280-
EOF
281-
# elemental upgrade \
282-
--logfile /tmp/manual-os-upgrade/upgrade.log \
283-
--directory /tmp/manual-os-upgrade/rootfs \
284-
--config-dir /tmp/manual-os-upgrade/config \
285-
--debug
286-
```
268+
269+
```
270+
# mkdir /tmp/manual-os-upgrade
271+
# mkdir /tmp/manual-os-upgrade/config
272+
# mkdir /tmp/manual-os-upgrade/rootfs
273+
# mount -o loop rootfs.squashfs /tmp/manual-os-upgrade/rootfs
274+
# cat > /tmp/manual-os-upgrade/config/config.yaml <<EOF
275+
upgrade:
276+
system:
277+
size: 3072
278+
EOF
279+
# elemental upgrade \
280+
--logfile /tmp/manual-os-upgrade/upgrade.log \
281+
--directory /tmp/manual-os-upgrade/rootfs \
282+
--config-dir /tmp/manual-os-upgrade/config \
283+
--debug
284+
```
285+
287286
:::note
288287
289288
You must replace the sample path in the fourth line with the actual path of the copied `rootfs.squashfs`.
@@ -301,13 +300,9 @@ To fix the issue, perform the following steps:
301300
```
302301
The node should boot successfully into Harvester v1.4.1, and the upgrade should proceed as expected.
303302
303+
Related issues: [#7457](https://github.com/harvester/harvester/issues/7457), [#7493](https://github.com/harvester/harvester/issues/7493), and [#7518](https://github.com/harvester/harvester/issues/7518)
304304
305-
Related issues:
306-
- [[BUG] Stuck upgrade from 1.4.0 to 1.4.1](https://github.com/harvester/harvester/issues/7457)
307-
- [[BUG] discrepancy in default OS partition sizes when using separate data disk](https://github.com/harvester/harvester/issues/7493)
308-
- [[BUG] after initial installation, passive.img uses 3.1G of disk space, vs. active.img which only uses 1.7G](https://github.com/harvester/harvester/issues/7518)
309-
310-
### 4. Upgrade will start over again unexpectedly after clicking the "Dismiss it" button
305+
### 4. Upgrade Restarts Unexpectedly After the "Dismiss it" Button is Clicked
311306
312307
When you use Rancher to upgrade Harvester, the Rancher UI displays a dialog with a button labeled "Dismiss it". Clicking this button may result in the following issues:
313308
@@ -325,5 +320,14 @@ To avoid this issue, perform either of the following actions:
325320
kubectl -n harvester-system label upgrades -l harvesterhci.io/latestUpgrade=true harvesterhci.io/read-message=true
326321
```
327322
328-
Related issue:
329-
- [[BUG] upgrade controller does not handle read-message well due to UI menu `Dismiss it` wipes upgrade CR's status](https://github.com/harvester/harvester/issues/7791)
323+
Related issue: [#7791](https://github.com/harvester/harvester/issues/7791)
324+
325+
### 5. Virtual Machines That Use Migratable RWX Volumes Restart Unexpectedly
326+
327+
A [Longhorn issue](https://github.com/longhorn/longhorn/issues/11158) causes virtual machines that use migratable [RWX volumes](https://docs.harvesterhci.io/v1.5/rancher/csi-driver/#rwx-volumes-support) to restart unexpectedly when the CSI plugin pods are restarted. This issue affects Harvester v1.4.x, v1.5.0, and v1.5.1.
328+
329+
The workaround is to disable the setting [Automatically Delete Workload Pod When The Volume Is Detached Unexpectedly](https://longhorn.io/docs/1.8.0/references/settings/#automatically-delete-workload-pod-when-the-volume-is-detached-unexpectedly) on the Longhorn UI before starting the upgrade. You must enable the setting again once the upgrade is completed.
330+
331+
The issue will be fixed in Longhorn v1.8.3, v1.9.1, and later versions. Harvester v1.6.0 will include Longhorn v1.9.1.
332+
333+
Related issues: [#8534](https://github.com/harvester/harvester/issues/8534) and [#11158](https://github.com/longhorn/longhorn/issues/11158)

‎docs/upgrade/v1-4-1-to-v1-4-2.md‎

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ title: "Upgrade from v1.4.1 to v1.4.2"
88
<link rel="canonical" href="https://docs.harvesterhci.io/v1.5/upgrade/v1-4-1-to-v1-4-2"/>
99
</head>
1010

11-
## General information
11+
## General Information
1212

1313
An **Upgrade** button appears on the **Dashboard** screen whenever a new Harvester version that you can upgrade to becomes available. For more information, see [Start an upgrade](./automatic.md#start-an-upgrade).
1414

@@ -18,7 +18,6 @@ For air-gapped environments, see [Prepare an air-gapped upgrade](./automatic.md#
1818

1919
To import Harvester v1.4.2 clusters on Rancher v2.10.1, you must use **v1.0.3** of the Rancher UI extension for Harvester.
2020

21-
2221
1. On the Rancher UI, go to **local > Apps > Repositories**.
2322

2423
1. Locate the repository named **harvester**, and then select **⋮ > Refresh**.
@@ -38,23 +37,24 @@ To import Harvester v1.4.2 clusters on Rancher v2.10.1, you must use **v1.0.3**
3837
1. Allow some time for the extension to be updated, and then refresh the screen.
3938

4039
:::info important
40+
4141
The Rancher UI displays an error message after the extension is updated. The error message disappears when you refresh the screen.
42+
4243
This issue, which exists in Rancher v2.10.0 and v2.10.1, will be fixed in v2.10.2.
44+
4345
:::
4446

45-
Related issues:
46-
- [Issue #7234](https://github.com/harvester/harvester/issues/7234)
47-
- [Issue #107](https://github.com/rancher/capi-ui-extension/issues/107)
47+
Related issues: [#7234](https://github.com/harvester/harvester/issues/7234) and [#107](https://github.com/rancher/capi-ui-extension/issues/107)
4848

4949
### VM Backup Compatibility
5050

51-
In Harvester v1.4.2 and later versions, you may encounter certain limitations when creating and restoring [backups that involve external storage](../../versioned_docs/version-v1.4/advanced/csidriver.md#vm-backup-compatibility)
52-
53-
## Known issues
51+
In Harvester v1.4.2 and later versions, you may encounter certain limitations when creating and restoring [backups that involve external storage](../../versioned_docs/version-v1.4/advanced/csidriver.md#vm-backup-compatibility).
5452

5553
---
5654

57-
### 1. Upgrade is stuck in the "Pre-drained" state
55+
## Known Issues
56+
57+
### 1. Upgrade is Stuck in the "Pre-drained" State
5858

5959
The upgrade process may become stuck in the "Pre-drained" state. Kubernetes is supposed to drain the workload on the node, but some factors may cause the process to stall.
6060

@@ -113,9 +113,7 @@ A possible cause is processes related to orphan engines of the Longhorn Instance
113113
kubectl delete pdb instance-manager-d80e13f520e7b952f4b7593fc1883e2a -n longhorn-system
114114
```
115115
116-
Related issues:
117-
- [[BUG] v1.4.0 -> v1.4.1-rc1 upgrade stuck in Pre-drained and the node stay in Cordoned](https://github.com/harvester/harvester/issues/7366)
118-
- [[IMPROVEMENT] Cleanup orphaned volume runtime resources if the resources already deleted](https://github.com/longhorn/longhorn/issues/6764)
116+
Related issues: [#7366](https://github.com/harvester/harvester/issues/7366) and [#6764](https://github.com/longhorn/longhorn/issues/6764)
119117
120118
### 2. High CPU Usage
121119
@@ -133,10 +131,9 @@ value: '{"type":"nfs","endpoint":"nfs://longhorn-test-nfs-svc.default:/opt/backu
133131
134132
![](/img/v1.4/image/high-cpu-load-fix.png)
135133
136-
Related issues:
137-
- [[BUG] High load and use of cpu time by harvester process](https://github.com/harvester/harvester/issues/7885)
134+
Related issues: [#7885](https://github.com/harvester/harvester/issues/7885)
138135
139-
### 3. Upgrade will start over again unexpectedly after clicking the "Dismiss it" button
136+
### 3. Upgrade Restarts Unexpectedly After "Dismiss it" Button is Clicked
140137
141138
When you use Rancher to upgrade Harvester, the Rancher UI displays a dialog with a button labeled "Dismiss it". Clicking this button may result in the following issues:
142139
@@ -154,5 +151,14 @@ To avoid this issue, perform either of the following actions:
154151
kubectl -n harvester-system label upgrades -l harvesterhci.io/latestUpgrade=true harvesterhci.io/read-message=true
155152
```
156153
157-
Related issue:
158-
- [[BUG] upgrade controller does not handle read-message well due to UI menu `Dismiss it` wipes upgrade CR's status](https://github.com/harvester/harvester/issues/7791)
154+
Related issue: [#7791](https://github.com/harvester/harvester/issues/7791)
155+
156+
### 4. Virtual Machines That Use Migratable RWX Volumes Restart Unexpectedly
157+
158+
A [Longhorn issue](https://github.com/longhorn/longhorn/issues/11158) causes virtual machines that use migratable [RWX volumes](https://docs.harvesterhci.io/v1.5/rancher/csi-driver/#rwx-volumes-support) to restart unexpectedly when the CSI plugin pods are restarted. This issue affects Harvester v1.4.x, v1.5.0, and v1.5.1.
159+
160+
The workaround is to disable the setting [Automatically Delete Workload Pod When The Volume Is Detached Unexpectedly](https://longhorn.io/docs/1.8.0/references/settings/#automatically-delete-workload-pod-when-the-volume-is-detached-unexpectedly) on the Longhorn UI before starting the upgrade. You must enable the setting again once the upgrade is completed.
161+
162+
The issue will be fixed in Longhorn v1.8.3, v1.9.1, and later versions. Harvester v1.6.0 will include Longhorn v1.9.1.
163+
164+
Related issues: [#8534](https://github.com/harvester/harvester/issues/8534) and [#11158](https://github.com/longhorn/longhorn/issues/11158)

0 commit comments

Comments
 (0)