Repository: harvester/docs
Pull request #773: Update how to manually stop and start the upgrade
Author: login: w13915984028
Created: 2025-05-06T08:31:59Z | Merged: 2025-05-15T06:28:10Z

<!-- 
!IMPORTANT!
Please do not create a Pull Request without creating an issue first.
-->

#### Problem:
<!-- Explain the problem you aim to resolve in this PR. -->

1. Missing details about stop and start the upgrade manually.
2. Missing chapters about how to resume the paused managedcharts.
3. Missing details about how to create the `version` and `upgrade` object with some customized annotations.

#### Solution:
<!-- Example: When "Adding a function to do X", explain why it is necessary to have a way to do X. -->

Update them as more as possible.

#### Related Issue(s):
<!--
Use `Issue #<issue number>` or `Issue harvester/harvester#<issue number>` or `Issue (paste link of issue)`. DON'T use `Fixes #<issue number>` or `Fixes (paste link of issue)`, as it will automatically close the linked issue when the PR is merged.
-->

https://github.com/harvester/harvester/issues/8195

https://github.com/harvester/harvester/issues/8213 (for further optimization)


#### Test plan:
<!-- Describe the test plan by steps. -->

#### Additional documentation or context



Diff:
diff --git a/docs/upgrade/automatic.md b/docs/upgrade/automatic.md
index 6a7975d8d16..5cd99091f3f 100644
--- a/docs/upgrade/automatic.md
+++ b/docs/upgrade/automatic.md
@@ -89,20 +89,78 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
-    - If the cluster is in an air-gapped environment, please see [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade) section first. You can also speed up the ISO download by using the approach in that section.
-- Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
+1. Make sure to read the above `caution`.
+
+1. On the Harvester UI **Dashboard** screen, click **Upgrade**.
+
+    The **Upgrade** button appears whenever a new Harvester version that you can upgrade to becomes available.
+
+    If your environment does not have direct internet access, follow the instructions in [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade), which provides an efficient approach to downloading the Harvester ISO.
 
     ![](/img/v1.2/upgrade/upgrade_button.png)
 
-- Select a version to start upgrading.
+1. Select a version that you want to upgrade to.
+
+    If you require customizations, see [Customize the Version](#customize-the-version).
 
     ![](/img/v1.2/upgrade/upgrade_select_version.png)
 
-- Click the circle on the top to display the upgrade progress.
+1. Click the progress indicator (the **circle** button) to view the status of each related process.
+
     ![](/img/v1.2/upgrade/upgrade_progress.png)
 
+### Customize the Version
+
+1. Download the version file (`https://releases.rancher.com/harvester/{version}/version.yaml`).
+
+    Example:
+
+    The [Harvester v1.5.0 version file](https://releases.rancher.com/harvester/v1.5.0/version.yaml) is downloaded as `v1.5.0.yaml`.
+
+    ```
+    apiVersion: harvesterhci.io/v1beta1
+    kind: Version
+    metadata:
+      name: v1.5.0-customized # Changed, to avoid duplicated with the official version name
+      namespace: harvester-system
+    spec:
+      isoChecksum: 'df28e9bf8dc561c5c26dee535046117906581296d633eb2988e4f68390a281b6856a5a0bd2e4b5b988c695a53d0fc86e4e3965f19957682b74317109b1d2fe32'  # Don't change
+      isoURL: https://releases.rancher.com/harvester/v1.5.0/harvester-v1.5.0-amd64.iso # Official ISO path by default
+      releaseDate: '20250425'
+    ```
+
+1. Add the necessary annotations.
+
+    - [minCertsExpirationInDay Annotation](#mincertsexpirationinday-annotation)
+    - [skipGarbageCollectionThresholdCheck Annotation](skipgarbagecollectionthresholdcheck-annotation)
+
+1. Run `kubectl create -f v1.5.0.yaml` to create the version.
+
+#### minCertsExpirationInDay Annotation
+
+Harvester checks the validity period of certificates on each node. This check eliminates the possibility of certificates expiring while the upgrade is in progress. If a certificate will expire within 7 days, an error is returned.
+
+Example:
+
+`harvesterhci.io/minCertsExpirationInDay: "14"` - When this annotation is added, Harvester returns an error when it detects a certificate that will expire within 14 days.
+
+For more information, see [auto-rotate-rke2-certs](advanced/settings.md/#auto-rotate-rke2-certs).
+
+#### skipGarbageCollectionThresholdCheck Annotation
+
+Harvester checks the disk space on each node to ensure that the kubelet's image garbage collection threshold is not exceeded when the required images are loaded during upgrades.
+
+Example:
+
+`harvesterhci.io/skipGarbageCollectionThresholdCheck: true` - When this annotation is added, Harvester skips the check.
+
+:::caution
+
+Do not use this annotation in production environments. When the check is skipped, required images might be deleted, causing the upgrade to fail.
+
+:::
+
+For more information, see [Free system partition space requirement](#free-system-partition-space-requirement).
 
 ## Prepare an air-gapped upgrade
 
@@ -112,9 +170,15 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO File
+
+1. Download a Harvester ISO file from the [Releases](https://github.com/harvester/harvester/releases) page.
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+### Prepare the Version
+
+1. Download the version file (`https://releases.rancher.com/harvester/{version}/version.yaml`).
 
     - Replace `isoURL` value in the `version.yaml` file:
 
@@ -122,25 +186,40 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
         spec:
           isoChecksum: <SHA-512 checksum of the ISO>
           isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
-          releaseDate: '20220512'
+          releaseDate: '20250425'
         ```
 
     - Assume the file is hosted at `http://10.10.0.1/version.yaml`.
 
-- Log in to one of your control plane nodes.
-- Become root and create a version:
+    - If you require customizations, see [Customize the Version](#customize-the-version).
+
+1. Access one of the control plane nodes via SSH and log in using the root account.
+
+1. Create a version object.
 
     ```
     rancher@node1:~> sudo -i
     rancher@node1:~> kubectl create -f http://10.10.0.1/version.yaml
     ```
 
-- An upgrade button should show up on the Harvester GUI Dashboard page.
+### Start the Upgrade
+
+The **Upgrade** button appears on the **Dashboard** screen whenever a new Harvester version that you can upgrade to becomes available. Refresh the screen if the button does not appear.
+
+## Manually Start an Upgrade before the Harvester Official Upgrade is Available
+
+The **Upgrade** button does not appear on the UI immediately after a new Harvester version is released. If you want to upgrade your cluster before the option becomes available on the UI, follow the steps in [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade).
+
+:::tip
+
+In production environments, upgrading clusters via the Harvester UI is recommended.
+
+:::
 
 ## Free system partition space requirement
 
diff --git a/docs/upgrade/troubleshooting.md b/docs/upgrade/troubleshooting.md
index d517c233cbb..84995c5dca9 100644
--- a/docs/upgrade/troubleshooting.md
+++ b/docs/upgrade/troubleshooting.md
@@ -102,7 +102,7 @@ $ kubectl logs -n harvester-system jobs/hvst-upgrade-9gmg2-post-drain-node2
 
 :::caution
 
-Please do not start over an upgrade if the upgrade fails at this phase.
+Do not [restart the upgrade](#restart-an-upgrade) if the process fails at this point. Identify the cause first, ask help from [Community](https://github.com/harvester/harvester?tab=readme-ov-file#community) or [SUSE support](https://www.suse.com/support/) if necessary.
 
 :::
 
@@ -113,10 +113,19 @@ The Harvester controller deletes the upgrade repository VM and all files that ar
 
 ## Common operations
 
-### Start over an upgrade
+### Stop the Ongoing Upgrade
+
+:::caution
+
+If an ongoing upgrade fails or becomes stuck at [Phase 4: Upgrade nodes](#phase-4-upgrade-nodes), identify the cause first.
+
+:::
+
+You can stop the upgrade by performing the following steps:
 
 1. Log in to a control plane node.
-2. List `Upgrade` CRs in the cluster:
+
+1. List the `Upgrade` CRs in the cluster.
 
     ```
     # become root
@@ -128,13 +137,56 @@ The Harvester controller deletes the upgrade repository VM and all files that ar
     hvst-upgrade-9gmg2   10m
     ```
 
-3. Delete the Upgrade CR
+1. Delete the Upgrade CR
 
     ```
     $ kubectl delete upgrade.harvesterhci.io/hvst-upgrade-9gmg2 -n harvester-system
     ```
 
-4. Click the upgrade button in the Harvester dashboard to start an upgrade again.
+1. Resume the paused ManagedCharts.
+
+    ManagedCharts are paused to avoid a data race between the upgrade and other processes. When the upgrade is manually stopped, the ManagedCharts might not been resumed, you need to manually resume all paused ManagedCharts.
+
+    ```
+    cat > resumeallcharts.sh << 'FOE'
+    resume_all_charts() {
+
+      local patchfile="/tmp/charttmp.yaml"
+
+      cat >"$patchfile" << 'EOF'
+    spec:
+      paused: false
+    EOF
+      echo "the to-be-patched file"
+      cat "$patchfile"
+
+      local charts="harvester harvester-crd rancher-monitoring-crd rancher-logging-crd"
+
+      for chart in $charts; do
+        echo "unapuse managedchart $chart"
+        kubectl patch managedcharts.management.cattle.io $chart -n fleet-local --patch-file "$patchfile" --type merge || echo "failed, check reason"
+      done
+
+      rm "$patchfile"
+    }
+
+    resume_all_charts
+
+    FOE
+
+    chmod +x ./resumeallcharts.sh
+
+    ./resumeallcharts.sh
+
+    ```
+
+### Restart an Upgrade
+
+1. [Stop the ongoing upgrade](#stop-the-ongoing-upgrade).
+
+1. Click the **Upgrade** button on the Harvester UI **Dashboard** screen.
+
+    If you [customized the version](./automatic.md#customize-the-version), you might need to [create the version object](./automatic.md#prepare-the-version) again.
 
 ### Download upgrade logs
 
diff --git a/versioned_docs/version-v1.5/upgrade/automatic.md b/versioned_docs/version-v1.5/upgrade/automatic.md
index 6a7975d8d16..5cd99091f3f 100644
--- a/versioned_docs/version-v1.5/upgrade/automatic.md
+++ b/versioned_docs/version-v1.5/upgrade/automatic.md
@@ -89,20 +89,78 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
-    - If the cluster is in an air-gapped environment, please see [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade) section first. You can also speed up the ISO download by using the approach in that section.
-- Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
+1. Make sure to read the above `caution`.
+
+1. On the Harvester UI **Dashboard** screen, click **Upgrade**.
+
+    The **Upgrade** button appears whenever a new Harvester version that you can upgrade to becomes available.
+
+    If your environment does not have direct internet access, follow the instructions in [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade), which provides an efficient approach to downloading the Harvester ISO.
 
     ![](/img/v1.2/upgrade/upgrade_button.png)
 
-- Select a version to start upgrading.
+1. Select a version that you want to upgrade to.
+
+    If you require customizations, see [Customize the Version](#customize-the-version).
 
     ![](/img/v1.2/upgrade/upgrade_select_version.png)
 
-- Click the circle on the top to display the upgrade progress.
+1. Click the progress indicator (the **circle** button) to view the status of each related process.
+
     ![](/img/v1.2/upgrade/upgrade_progress.png)
 
+### Customize the Version
+
+1. Download the version file (`https://releases.rancher.com/harvester/{version}/version.yaml`).
+
+    Example:
+
+    The [Harvester v1.5.0 version file](https://releases.rancher.com/harvester/v1.5.0/version.yaml) is downloaded as `v1.5.0.yaml`.
+
+    ```
+    apiVersion: harvesterhci.io/v1beta1
+    kind: Version
+    metadata:
+      name: v1.5.0-customized # Changed, to avoid duplicated with the official version name
+      namespace: harvester-system
+    spec:
+      isoChecksum: 'df28e9bf8dc561c5c26dee535046117906581296d633eb2988e4f68390a281b6856a5a0bd2e4b5b988c695a53d0fc86e4e3965f19957682b74317109b1d2fe32'  # Don't change
+      isoURL: https://releases.rancher.com/harvester/v1.5.0/harvester-v1.5.0-amd64.iso # Official ISO path by default
+      releaseDate: '20250425'
+    ```
+
+1. Add the necessary annotations.
+
+    - [minCertsExpirationInDay Annotation](#mincertsexpirationinday-annotation)
+    - [skipGarbageCollectionThresholdCheck Annotation](skipgarbagecollectionthresholdcheck-annotation)
+
+1. Run `kubectl create -f v1.5.0.yaml` to create the version.
+
+#### minCertsExpirationInDay Annotation
+
+Harvester checks the validity period of certificates on each node. This check eliminates the possibility of certificates expiring while the upgrade is in progress. If a certificate will expire within 7 days, an error is returned.
+
+Example:
+
+`harvesterhci.io/minCertsExpirationInDay: "14"` - When this annotation is added, Harvester returns an error when it detects a certificate that will expire within 14 days.
+
+For more information, see [auto-rotate-rke2-certs](advanced/settings.md/#auto-rotate-rke2-certs).
+
+#### skipGarbageCollectionThresholdCheck Annotation
+
+Harvester checks the disk space on each node to ensure that the kubelet's image garbage collection threshold is not exceeded when the required images are loaded during upgrades.
+
+Example:
+
+`harvesterhci.io/skipGarbageCollectionThresholdCheck: true` - When this annotation is added, Harvester skips the check.
+
+:::caution
+
+Do not use this annotation in production environments. When the check is skipped, required images might be deleted, causing the upgrade to fail.
+
+:::
+
+For more information, see [Free system partition space requirement](#free-system-partition-space-requirement).
 
 ## Prepare an air-gapped upgrade
 
@@ -112,9 +170,15 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO File
+
+1. Download a Harvester ISO file from the [Releases](https://github.com/harvester/harvester/releases) page.
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+### Prepare the Version
+
+1. Download the version file (`https://releases.rancher.com/harvester/{version}/version.yaml`).
 
     - Replace `isoURL` value in the `version.yaml` file:
 
@@ -122,25 +186,40 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
         spec:
           isoChecksum: <SHA-512 checksum of the ISO>
           isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
-          releaseDate: '20220512'
+          releaseDate: '20250425'
         ```
 
     - Assume the file is hosted at `http://10.10.0.1/version.yaml`.
 
-- Log in to one of your control plane nodes.
-- Become root and create a version:
+    - If you require customizations, see [Customize the Version](#customize-the-version).
+
+1. Access one of the control plane nodes via SSH and log in using the root account.
+
+1. Create a version object.
 
     ```
     rancher@node1:~> sudo -i
     rancher@node1:~> kubectl create -f http://10.10.0.1/version.yaml
     ```
 
-- An upgrade button should show up on the Harvester GUI Dashboard page.
+### Start the Upgrade
+
+The **Upgrade** button appears on the **Dashboard** screen whenever a new Harvester version that you can upgrade to becomes available. Refresh the screen if the button does not appear.
+
+## Manually Start an Upgrade before the Harvester Official Upgrade is Available
+
+The **Upgrade** button does not appear on the UI immediately after a new Harvester version is released. If you want to upgrade your cluster before the option becomes available on the UI, follow the steps in [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade).
+
+:::tip
+
+In production environments, upgrading clusters via the Harvester UI is recommended.
+
+:::
 
 ## Free system partition space requirement
 
diff --git a/versioned_docs/version-v1.5/upgrade/troubleshooting.md b/versioned_docs/version-v1.5/upgrade/troubleshooting.md
index 724fbac2138..dc83a9a7479 100644
--- a/versioned_docs/version-v1.5/upgrade/troubleshooting.md
+++ b/versioned_docs/version-v1.5/upgrade/troubleshooting.md
@@ -102,7 +102,7 @@ $ kubectl logs -n harvester-system jobs/hvst-upgrade-9gmg2-post-drain-node2
 
 :::caution
 
-Please do not start over an upgrade if the upgrade fails at this phase.
+Do not [restart the upgrade](#restart-an-upgrade) if the process fails at this point. Identify the cause first, ask help from [Community](https://github.com/harvester/harvester?tab=readme-ov-file#community) or [SUSE support](https://www.suse.com/support/) if necessary.
 
 :::
 
@@ -113,10 +113,19 @@ The Harvester controller deletes the upgrade repository VM and all files that ar
 
 ## Common operations
 
-### Start over an upgrade
+### Stop the Ongoing Upgrade
+
+:::caution
+
+If an ongoing upgrade fails or becomes stuck at [Phase 4: Upgrade nodes](#phase-4-upgrade-nodes), identify the cause first.
+
+:::
+
+You can stop the upgrade by performing the following steps:
 
 1. Log in to a control plane node.
-2. List `Upgrade` CRs in the cluster:
+
+1. List the `Upgrade` CRs in the cluster.
 
     ```
     # become root
@@ -128,13 +137,56 @@ The Harvester controller deletes the upgrade repository VM and all files that ar
     hvst-upgrade-9gmg2   10m
     ```
 
-3. Delete the Upgrade CR
+1. Delete the Upgrade CR
 
     ```
     $ kubectl delete upgrade.harvesterhci.io/hvst-upgrade-9gmg2 -n harvester-system
     ```
 
-4. Click the upgrade button in the Harvester dashboard to start an upgrade again.
+1. Resume the paused ManagedCharts.
+
+    ManagedCharts are paused to avoid a data race between the upgrade and other processes. When the upgrade is manually stopped, the ManagedCharts might not been resumed, you need to manually resume all paused ManagedCharts.
+
+    ```
+    cat > resumeallcharts.sh << 'FOE'
+    resume_all_charts() {
+
+      local patchfile="/tmp/charttmp.yaml"
+
+      cat >"$patchfile" << 'EOF'
+    spec:
+      paused: false
+    EOF
+      echo "the to-be-patched file"
+      cat "$patchfile"
+
+      local charts="harvester harvester-crd rancher-monitoring-crd rancher-logging-crd"
+
+      for chart in $charts; do
+        echo "unapuse managedchart $chart"
+        kubectl patch managedcharts.management.cattle.io $chart -n fleet-local --patch-file "$patchfile" --type merge || echo "failed, check reason"
+      done
+
+      rm "$patchfile"
+    }
+
+    resume_all_charts
+
+    FOE
+
+    chmod +x ./resumeallcharts.sh
+
+    ./resumeallcharts.sh
+
+    ```
+
+### Restart an Upgrade
+
+1. [Stop the ongoing upgrade](#stop-the-ongoing-upgrade).
+
+1. Click the **Upgrade** button on the Harvester UI **Dashboard** screen.
+
+    If you [customized the version](./automatic.md#customize-the-version), you might need to [create the version object](./automatic.md#prepare-the-version) again.
 
 ### Download upgrade logs
 


Reviews:
user: login: starbops
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-06T09:25:24Z
user: login: w13915984028
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-06T15:03:20Z
user: login: w13915984028
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-06T15:03:37Z
user: login: jillian-maroket
body: Review done
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-09T09:47:46Z
user: login: w13915984028
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-12T08:34:24Z
user: login: w13915984028
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-12T09:13:54Z
user: login: w13915984028
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-12T09:17:35Z
user: login: w13915984028
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-12T09:31:38Z
user: login: starbops
body: LGTM, thank you.
state: DISMISSED
author_association: MEMBER
submitted_at: 2025-05-12T10:40:45Z
user: login: votdev
body: LGTM
state: DISMISSED
author_association: MEMBER
submitted_at: 2025-05-13T13:25:22Z
user: login: jillian-maroket
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-05-14T11:23:52Z
user: login: w13915984028
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-14T12:34:28Z
user: login: jillian-maroket
body: Thanks
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-05-15T01:44:21Z

Review comments:
diff_hunk: @@ -112,35 +112,60 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO and Version File
+
+1. Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+1. Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
 
     - Replace `isoURL` value in the `version.yaml` file:
 
         ```
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
+          annotations:
+            harvesterhci.io/skipGarbageCollectionThresholdCheck: false
path: docs/upgrade/automatic.md
user: login: starbops
body: Do we need to specify this explicitly to ensure it does not skip the check?
created_at: 2025-05-06T09:09:48Z
author_association: MEMBER
diff_hunk: @@ -112,35 +112,60 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO and Version File
+
+1. Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+1. Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
 
     - Replace `isoURL` value in the `version.yaml` file:
 
         ```
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
+          annotations:
+            harvesterhci.io/skipGarbageCollectionThresholdCheck: false
         spec:
           isoChecksum: <SHA-512 checksum of the ISO>
           isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
-          releaseDate: '20220512'
+          releaseDate: '20250425'
         ```
 
     - Assume the file is hosted at `http://10.10.0.1/version.yaml`.
 
-- Log in to one of your control plane nodes.
-- Become root and create a version:
+### Create the Version Object
+
+1. Log in to one of your control plane nodes.
+
+1. Become root and create a version:
 
     ```
     rancher@node1:~> sudo -i
     rancher@node1:~> kubectl create -f http://10.10.0.1/version.yaml
     ```
 
-- An upgrade button should show up on the Harvester GUI Dashboard page.
+### Trgger the Upgrade
+
+1. An upgrade button should show up on the Harvester GUI Dashboard page.
+
+    Refresh the web page if the button does not appear.
+
+## Manually Start an Upgrade before the Harvester Official Upgrade is Available
+
+After a new Harvester version is released, the official upgrade is not available right now, you do not see the `upgrade` button on your cluster.
+
+When you want to upgrade your cluster to the new release, follow the stpes on [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade).
path: docs/upgrade/automatic.md
user: login: starbops
body: s/stpes/steps/
created_at: 2025-05-06T09:20:51Z
author_association: MEMBER
diff_hunk: @@ -128,13 +131,54 @@ The Harvester controller deletes the upgrade repository VM and all files that ar
     hvst-upgrade-9gmg2   10m
     ```
 
-3. Delete the Upgrade CR
+1. Delete the Upgrade CR
 
     ```
     $ kubectl delete upgrade.harvesterhci.io/hvst-upgrade-9gmg2 -n harvester-system
     ```
 
-4. Click the upgrade button in the Harvester dashboard to start an upgrade again.
+1. Resume the following Managedcharts
path: docs/upgrade/troubleshooting.md
user: login: starbops
body: Though it does not harm the cluster running the script even when not doing upgrades, I think we can add more description about why they need to run this (actually, they don't need to if the previous upgrade did not get past a certain point, but I get your point).
created_at: 2025-05-06T09:25:15Z
author_association: MEMBER
diff_hunk: @@ -112,35 +112,60 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO and Version File
+
+1. Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+1. Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
 
     - Replace `isoURL` value in the `version.yaml` file:
 
         ```
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
+          annotations:
+            harvesterhci.io/skipGarbageCollectionThresholdCheck: false
path: docs/upgrade/automatic.md
user: login: w13915984028
body: There are a few options and not documented in a single place, I refactored the description.
created_at: 2025-05-06T15:03:20Z
author_association: MEMBER
diff_hunk: @@ -128,13 +131,54 @@ The Harvester controller deletes the upgrade repository VM and all files that ar
     hvst-upgrade-9gmg2   10m
     ```
 
-3. Delete the Upgrade CR
+1. Delete the Upgrade CR
 
     ```
     $ kubectl delete upgrade.harvesterhci.io/hvst-upgrade-9gmg2 -n harvester-system
     ```
 
-4. Click the upgrade button in the Harvester dashboard to start an upgrade again.
+1. Resume the following Managedcharts
path: docs/upgrade/troubleshooting.md
user: login: w13915984028
body: Updated, thanks.
created_at: 2025-05-06T15:03:37Z
author_association: MEMBER
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: Which line is this referring to? I cannot find any warnings in this document. The section below the title is the support matrix.
created_at: 2025-05-08T14:41:17Z
author_association: CONTRIBUTOR
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
+
+1. Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: The existing wording does not describe a step that the user must perform. I moved the information to the step below. Please remove this line.
created_at: 2025-05-09T05:20:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
+
+1. Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+
     - If the cluster is in an air-gapped environment, please see [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade) section first. You can also speed up the ISO download by using the approach in that section.
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: I moved the information to the step below. Please remove this line.
created_at: 2025-05-09T05:20:21Z
author_association: CONTRIBUTOR
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
+
+1. Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+
     - If the cluster is in an air-gapped environment, please see [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade) section first. You can also speed up the ISO download by using the approach in that section.
-- Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
+
+1. Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
1. On the Harvester UI **Dashboard** screen, click **Upgrade**.

  The **Upgrade** button appears whenever a new Harvester version that you can upgrade to becomes available.

  If your environment does not have direct internet access, follow the instructions in [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade), which provides an efficient approach to downloading the Harvester ISO.
```
created_at: 2025-05-09T05:20:56Z
author_association: CONTRIBUTOR
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
+
+1. Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+
     - If the cluster is in an air-gapped environment, please see [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade) section first. You can also speed up the ISO download by using the approach in that section.
-- Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
+
+1. Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
 
     ![](/img/v1.2/upgrade/upgrade_button.png)
 
-- Select a version to start upgrading.
+1. Select a version to start upgrading. If you need to customize the version, refer [customization](#customize-the-version).
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
1. Select a version that you want to upgrade to.

  If you require customizations, see [Customize the Version](#customize-the-version).
```
created_at: 2025-05-09T05:25:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
+
+1. Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+
     - If the cluster is in an air-gapped environment, please see [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade) section first. You can also speed up the ISO download by using the approach in that section.
-- Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
+
+1. Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
 
     ![](/img/v1.2/upgrade/upgrade_button.png)
 
-- Select a version to start upgrading.
+1. Select a version to start upgrading. If you need to customize the version, refer [customization](#customize-the-version).
 
     ![](/img/v1.2/upgrade/upgrade_select_version.png)
 
-- Click the circle on the top to display the upgrade progress.
+1. Click the circle on the top to display the upgrade progress.
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
1. Click the progress indicator to view the status of each related process.

```
created_at: 2025-05-09T05:25:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
+
+1. Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+
     - If the cluster is in an air-gapped environment, please see [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade) section first. You can also speed up the ISO download by using the approach in that section.
-- Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
+
+1. Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
 
     ![](/img/v1.2/upgrade/upgrade_button.png)
 
-- Select a version to start upgrading.
+1. Select a version to start upgrading. If you need to customize the version, refer [customization](#customize-the-version).
 
     ![](/img/v1.2/upgrade/upgrade_select_version.png)
 
-- Click the circle on the top to display the upgrade progress.
+1. Click the circle on the top to display the upgrade progress.
     ![](/img/v1.2/upgrade/upgrade_progress.png)
 
+### Customize the Version
+
+1. Download the version file from Harvester release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`.
+
+    Example: Harvester [v1.5.0 version file](https://releases.rancher.com/harvester/v1.5.0/version.yaml) is downloaded as `v1.5.0.yaml`.
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
1. Download the version file (`https://releases.rancher.com/harvester/{version}/version.yaml`).

    Example:
    
    The [Harvester v1.5.0 version file](https://releases.rancher.com/harvester/v1.5.0/version.yaml) is downloaded as `v1.5.0.yaml`.
```
created_at: 2025-05-09T06:00:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
+
+1. Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+
     - If the cluster is in an air-gapped environment, please see [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade) section first. You can also speed up the ISO download by using the approach in that section.
-- Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
+
+1. Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
 
     ![](/img/v1.2/upgrade/upgrade_button.png)
 
-- Select a version to start upgrading.
+1. Select a version to start upgrading. If you need to customize the version, refer [customization](#customize-the-version).
 
     ![](/img/v1.2/upgrade/upgrade_select_version.png)
 
-- Click the circle on the top to display the upgrade progress.
+1. Click the circle on the top to display the upgrade progress.
     ![](/img/v1.2/upgrade/upgrade_progress.png)
 
+### Customize the Version
+
+1. Download the version file from Harvester release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`.
+
+    Example: Harvester [v1.5.0 version file](https://releases.rancher.com/harvester/v1.5.0/version.yaml) is downloaded as `v1.5.0.yaml`.
+
+    ```
+    apiVersion: harvesterhci.io/v1beta1
+    kind: Version
+    metadata:
+      name: v1.5.0-customized # Changed, to avoid duplicated with the official version name
+      namespace: harvester-system
+    spec:
+      isoChecksum: 'df28e9bf8dc561c5c26dee535046117906581296d633eb2988e4f68390a281b6856a5a0bd2e4b5b988c695a53d0fc86e4e3965f19957682b74317109b1d2fe32'  # Don't change
+      isoURL: https://releases.rancher.com/harvester/v1.5.0/harvester-v1.5.0-amd64.iso # Official ISO path by default
+      releaseDate: '20250425'
+    ```
+
+1. Add following annotations on demand.
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
1. Add the necessary annotations.

  - [minCertsExpirationInDay Annotation](#mincertsexpirationinday-annotation)
  - [skipGarbageCollectionThresholdCheck Annotation](skipgarbagecollectionthresholdcheck-annotation)
```
created_at: 2025-05-09T06:01:18Z
author_association: CONTRIBUTOR
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
+
+1. Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+
     - If the cluster is in an air-gapped environment, please see [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade) section first. You can also speed up the ISO download by using the approach in that section.
-- Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
+
+1. Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
 
     ![](/img/v1.2/upgrade/upgrade_button.png)
 
-- Select a version to start upgrading.
+1. Select a version to start upgrading. If you need to customize the version, refer [customization](#customize-the-version).
 
     ![](/img/v1.2/upgrade/upgrade_select_version.png)
 
-- Click the circle on the top to display the upgrade progress.
+1. Click the circle on the top to display the upgrade progress.
     ![](/img/v1.2/upgrade/upgrade_progress.png)
 
+### Customize the Version
+
+1. Download the version file from Harvester release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`.
+
+    Example: Harvester [v1.5.0 version file](https://releases.rancher.com/harvester/v1.5.0/version.yaml) is downloaded as `v1.5.0.yaml`.
+
+    ```
+    apiVersion: harvesterhci.io/v1beta1
+    kind: Version
+    metadata:
+      name: v1.5.0-customized # Changed, to avoid duplicated with the official version name
+      namespace: harvester-system
+    spec:
+      isoChecksum: 'df28e9bf8dc561c5c26dee535046117906581296d633eb2988e4f68390a281b6856a5a0bd2e4b5b988c695a53d0fc86e4e3965f19957682b74317109b1d2fe32'  # Don't change
+      isoURL: https://releases.rancher.com/harvester/v1.5.0/harvester-v1.5.0-amd64.iso # Official ISO path by default
+      releaseDate: '20250425'
+    ```
+
+1. Add following annotations on demand.
+
+1. Run `kubectl create -f v1.5.0.yaml` to create the version.
+
+#### Annotation minCertsExpirationInDay
+
+Harvester checkes the cert expiration days on each node. If any of them will expire in 7 days, an error is reported. This check eliminates the chance to hit cert experiation when upgrade is running.
+
+Example: The `harvesterhci.io/minCertsExpirationInDay: "14"` sets the check upon expiration days to 14.
+
+See [auto-rotate-rke2-certs](advanced/settings.md/#auto-rotate-rke2-certs) for more information.
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
#### minCertsExpirationInDay Annotation

Harvester checks the validity period of certificates on each node. This check eliminates the possibility of certificates expiring while the upgrade is in progress. If a certificate is set to expire within 7 days, an error is returned.

Example:

`harvesterhci.io/minCertsExpirationInDay: "14"` - When this annotation is added, Harvester returns an error when it detects a certificate that is set to expire within 14 days.

For more information, see [auto-rotate-rke2-certs](advanced/settings.md/#auto-rotate-rke2-certs).
```
created_at: 2025-05-09T07:23:54Z
author_association: CONTRIBUTOR
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
+
+1. Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+
     - If the cluster is in an air-gapped environment, please see [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade) section first. You can also speed up the ISO download by using the approach in that section.
-- Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
+
+1. Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
 
     ![](/img/v1.2/upgrade/upgrade_button.png)
 
-- Select a version to start upgrading.
+1. Select a version to start upgrading. If you need to customize the version, refer [customization](#customize-the-version).
 
     ![](/img/v1.2/upgrade/upgrade_select_version.png)
 
-- Click the circle on the top to display the upgrade progress.
+1. Click the circle on the top to display the upgrade progress.
     ![](/img/v1.2/upgrade/upgrade_progress.png)
 
+### Customize the Version
+
+1. Download the version file from Harvester release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`.
+
+    Example: Harvester [v1.5.0 version file](https://releases.rancher.com/harvester/v1.5.0/version.yaml) is downloaded as `v1.5.0.yaml`.
+
+    ```
+    apiVersion: harvesterhci.io/v1beta1
+    kind: Version
+    metadata:
+      name: v1.5.0-customized # Changed, to avoid duplicated with the official version name
+      namespace: harvester-system
+    spec:
+      isoChecksum: 'df28e9bf8dc561c5c26dee535046117906581296d633eb2988e4f68390a281b6856a5a0bd2e4b5b988c695a53d0fc86e4e3965f19957682b74317109b1d2fe32'  # Don't change
+      isoURL: https://releases.rancher.com/harvester/v1.5.0/harvester-v1.5.0-amd64.iso # Official ISO path by default
+      releaseDate: '20250425'
+    ```
+
+1. Add following annotations on demand.
+
+1. Run `kubectl create -f v1.5.0.yaml` to create the version.
+
+#### Annotation minCertsExpirationInDay
+
+Harvester checkes the cert expiration days on each node. If any of them will expire in 7 days, an error is reported. This check eliminates the chance to hit cert experiation when upgrade is running.
+
+Example: The `harvesterhci.io/minCertsExpirationInDay: "14"` sets the check upon expiration days to 14.
+
+See [auto-rotate-rke2-certs](advanced/settings.md/#auto-rotate-rke2-certs) for more information.
+
+#### Annotation skipGarbageCollectionThresholdCheck
+
+Harvester checks the disk spaces on each node to ensure when upgrade preloads all the required images, it will not exceed kubelet image garbage collection threshold.
+
+Example: The `harvesterhci.io/skipGarbageCollectionThresholdCheck: true` annotation skips the check.
+
+See [Free system partition space requirement](#free-system-partition-space-requirement) for more information.
+
+:::caution
+
+When this check is skipped, the upgrade might fail due to some images are garbage collected. Do not set it in production environment.
+
+:::
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
#### skipGarbageCollectionThresholdCheck Annotation

Harvester checks the disk space on each node to ensure that the kubelet's image garbage collection threshold is not exceeded when the required images are loaded during upgrades.

Example:

`harvesterhci.io/skipGarbageCollectionThresholdCheck: true` - When this annotation is added, Harvester skips the check.

:::caution

Do not use this annotation in production environments. When the check is skipped, required images might be deleted, causing the upgrade to fail.

:::

For more information, see [Free system partition space requirement](#free-system-partition-space-requirement).
```
created_at: 2025-05-09T07:24:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -112,35 +158,60 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO File
+
+1. Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
1. Download a Harvester ISO file from the [Releases](https://github.com/harvester/harvester/releases) page.
```
created_at: 2025-05-09T08:06:10Z
author_association: CONTRIBUTOR
diff_hunk: @@ -112,35 +158,60 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO File
+
+1. Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+### Prepare the Version
+
+1. Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
1. Download the version file (`https://releases.rancher.com/harvester/{version}/version.yaml`).
```
created_at: 2025-05-09T08:06:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -112,35 +158,60 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO File
+
+1. Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+### Prepare the Version
+
+1. Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
 
     - Replace `isoURL` value in the `version.yaml` file:
 
         ```
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
         spec:
           isoChecksum: <SHA-512 checksum of the ISO>
           isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
-          releaseDate: '20220512'
+          releaseDate: '20250425'
         ```
 
     - Assume the file is hosted at `http://10.10.0.1/version.yaml`.
 
-- Log in to one of your control plane nodes.
-- Become root and create a version:
+    - If you need to customize the version, refer [customization](#customize-the-version)
+
+1. Log in to one of your control plane nodes.
+
+1. Become root and create a version object:
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
  If you require customizations, see [Customize the Version](#customize-the-version).

1. Access one of the control plane nodes via SSH and log in using the root account.

1. Create a version object.
```
created_at: 2025-05-09T08:07:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -112,35 +158,60 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO File
+
+1. Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+### Prepare the Version
+
+1. Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
 
     - Replace `isoURL` value in the `version.yaml` file:
 
         ```
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
         spec:
           isoChecksum: <SHA-512 checksum of the ISO>
           isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
-          releaseDate: '20220512'
+          releaseDate: '20250425'
         ```
 
     - Assume the file is hosted at `http://10.10.0.1/version.yaml`.
 
-- Log in to one of your control plane nodes.
-- Become root and create a version:
+    - If you need to customize the version, refer [customization](#customize-the-version)
+
+1. Log in to one of your control plane nodes.
+
+1. Become root and create a version object:
 
     ```
     rancher@node1:~> sudo -i
     rancher@node1:~> kubectl create -f http://10.10.0.1/version.yaml
     ```
 
-- An upgrade button should show up on the Harvester GUI Dashboard page.
+### Trigger the Upgrade
+
+1. An upgrade button should show up on the Harvester GUI Dashboard page.
+
+    Refresh the web page if the button does not appear.
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
### Start the Upgrade

The **Upgrade** button appears on the **Dashboard** screen whenever a new Harvester version that you can upgrade to becomes available. Refresh the screen if the button does not appear.
```
created_at: 2025-05-09T09:03:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -112,35 +158,60 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO File
+
+1. Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+### Prepare the Version
+
+1. Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
 
     - Replace `isoURL` value in the `version.yaml` file:
 
         ```
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
         spec:
           isoChecksum: <SHA-512 checksum of the ISO>
           isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
-          releaseDate: '20220512'
+          releaseDate: '20250425'
         ```
 
     - Assume the file is hosted at `http://10.10.0.1/version.yaml`.
 
-- Log in to one of your control plane nodes.
-- Become root and create a version:
+    - If you need to customize the version, refer [customization](#customize-the-version)
+
+1. Log in to one of your control plane nodes.
+
+1. Become root and create a version object:
 
     ```
     rancher@node1:~> sudo -i
     rancher@node1:~> kubectl create -f http://10.10.0.1/version.yaml
     ```
 
-- An upgrade button should show up on the Harvester GUI Dashboard page.
+### Trigger the Upgrade
+
+1. An upgrade button should show up on the Harvester GUI Dashboard page.
+
+    Refresh the web page if the button does not appear.
+
+## Manually Start an Upgrade before the Harvester Official Upgrade is Available
+
+After a new Harvester version is released, the official upgrade is not available right now, you do not see the `upgrade` button on your cluster.
+
+When you want to upgrade your cluster to the new release, follow the steps on [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade).
+
+:::caution
+
+It is recommended to wait until the official upgrade is available for production environment.
+
+:::
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
## Manual Upgrades (Not UI-Based)

The **Upgrade** button does not appear on the UI immediately after a new Harvester version is released.
If you want to upgrade your cluster before the option becomes available on the UI, follow the steps in [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade).

:::tip

In production environments, upgrading clusters via the Harvester UI is recommended.

:::
```
created_at: 2025-05-09T09:04:57Z
author_association: CONTRIBUTOR
diff_hunk: @@ -102,7 +102,7 @@ $ kubectl logs -n harvester-system jobs/hvst-upgrade-9gmg2-post-drain-node2
 
 :::caution
 
-Please do not start over an upgrade if the upgrade fails at this phase.
+Please do not [Start over an Upgrade](#start-over-an-upgrade) if the upgrade fails at this phase.
path: docs/upgrade/troubleshooting.md
user: login: jillian-maroket
body: ```suggestion
Do not [restart the upgrade](#restart-an-upgrade) if the process fails at this point.
```
created_at: 2025-05-09T09:09:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -102,7 +102,7 @@ $ kubectl logs -n harvester-system jobs/hvst-upgrade-9gmg2-post-drain-node2
 
 :::caution
 
-Please do not start over an upgrade if the upgrade fails at this phase.
+Please do not [Start over an Upgrade](#start-over-an-upgrade) if the upgrade fails at this phase.
path: docs/upgrade/troubleshooting.md
user: login: jillian-maroket
body: What are the consequences of restarting the upgrade at this point? What should the user do instead of restarting?
created_at: 2025-05-09T09:10:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -113,10 +113,19 @@ The Harvester controller deletes the upgrade repository VM and all files that ar
 
 ## Common operations
 
-### Start over an upgrade
+### Stop the Current Upgrade
+
+:::caution
+
+If the current upgrade fails/is stucking at [Phase 4: Upgrade nodes](#phase-4-upgrade-nodes), check the reason first.
+
+:::
+
+When the current upgrade hits issues or is stucking, run below steps to stop the upgrade.
path: docs/upgrade/troubleshooting.md
user: login: jillian-maroket
body: ```suggestion
## Stop an Ongoing Upgrade

:::caution

If an ongoing upgrade fails or becomes stuck at [Phase 4: Upgrade nodes](#phase-4-upgrade-nodes), identify the cause first.

:::

You can stop the upgrade by performing the following steps:
```
created_at: 2025-05-09T09:28:00Z
author_association: CONTRIBUTOR
diff_hunk: @@ -113,10 +113,19 @@ The Harvester controller deletes the upgrade repository VM and all files that ar
 
 ## Common operations
 
-### Start over an upgrade
+### Stop the Current Upgrade
+
+:::caution
+
+If the current upgrade fails/is stucking at [Phase 4: Upgrade nodes](#phase-4-upgrade-nodes), check the reason first.
+
+:::
+
+When the current upgrade hits issues or is stucking, run below steps to stop the upgrade.
 
 1. Log in to a control plane node.
-2. List `Upgrade` CRs in the cluster:
+
+1. List `Upgrade` CRs in the cluster:
path: docs/upgrade/troubleshooting.md
user: login: jillian-maroket
body: ```suggestion
1. List the `Upgrade` CRs in the cluster.
```
created_at: 2025-05-09T09:40:57Z
author_association: CONTRIBUTOR
diff_hunk: @@ -128,13 +137,56 @@ The Harvester controller deletes the upgrade repository VM and all files that ar
     hvst-upgrade-9gmg2   10m
     ```
 
-3. Delete the Upgrade CR
+1. Delete the Upgrade CR
 
     ```
     $ kubectl delete upgrade.harvesterhci.io/hvst-upgrade-9gmg2 -n harvester-system
     ```
 
-4. Click the upgrade button in the Harvester dashboard to start an upgrade again.
+1. Resume the following Managedcharts
path: docs/upgrade/troubleshooting.md
user: login: jillian-maroket
body: ```suggestion
1. Resume the paused ManagedCharts.
```
created_at: 2025-05-09T09:45:07Z
author_association: CONTRIBUTOR
diff_hunk: @@ -128,13 +137,56 @@ The Harvester controller deletes the upgrade repository VM and all files that ar
     hvst-upgrade-9gmg2   10m
     ```
 
-3. Delete the Upgrade CR
+1. Delete the Upgrade CR
 
     ```
     $ kubectl delete upgrade.harvesterhci.io/hvst-upgrade-9gmg2 -n harvester-system
     ```
 
-4. Click the upgrade button in the Harvester dashboard to start an upgrade again.
+1. Resume the following Managedcharts
+
+    The upgrade pauses the managedchart to avoid data race between upgrade and others. When those managedcharts have been paused and later the upgrade is stopped, it is essential to resume them.
path: docs/upgrade/troubleshooting.md
user: login: jillian-maroket
body: ```suggestion
  ManagedCharts are paused to avoid a data race between the upgrade and other processes. You must manually resume all paused ManagedCharts.
```
created_at: 2025-05-09T09:46:00Z
author_association: CONTRIBUTOR
diff_hunk: @@ -128,13 +137,56 @@ The Harvester controller deletes the upgrade repository VM and all files that ar
     hvst-upgrade-9gmg2   10m
     ```
 
-3. Delete the Upgrade CR
+1. Delete the Upgrade CR
 
     ```
     $ kubectl delete upgrade.harvesterhci.io/hvst-upgrade-9gmg2 -n harvester-system
     ```
 
-4. Click the upgrade button in the Harvester dashboard to start an upgrade again.
+1. Resume the following Managedcharts
+
+    The upgrade pauses the managedchart to avoid data race between upgrade and others. When those managedcharts have been paused and later the upgrade is stopped, it is essential to resume them.
+
+    ```
+    cat > resumeallcharts.sh << 'FOE'
+    resume_all_charts() {
+
+      local patchfile="/tmp/charttmp.yaml"
+
+      cat >"$patchfile" << 'EOF'
+    spec:
+      paused: false
+    EOF
+      echo "the to-be-patched file"
+      cat "$patchfile"
+
+      local charts="harvester harvester-crd rancher-monitoring-crd rancher-logging-crd"
+
+      for chart in $charts; do
+        echo "unapuse managedchart $chart"
+        kubectl patch managedcharts.management.cattle.io $chart -n fleet-local --patch-file "$patchfile" --type merge || echo "failed, check reason"
+      done
+
+      rm "$patchfile"
+    }
+
+    resume_all_charts
+
+    FOE
+
+    chmod +x ./resumeallcharts.sh
+
+    ./resumeallcharts.sh
+
+    ```
+
+### Start over an Upgrade
+
+1. [Stop the Current upgrade](#stop-the-current-upgrade)
+
+1. Click the upgrade button in the Harvester dashboard to start an upgrade again.
+
+    If you [Customize the Version](./automatic.md#customize-the-version) manually, you might need to [create the version object](./automatic.md#prepare-the-version) again.
path: docs/upgrade/troubleshooting.md
user: login: jillian-maroket
body: ```suggestion
### Restart an Upgrade

1. [Stop the ongoing upgrade](#stop-the-current-upgrade).

1. Click the **Upgrade** button on the Harvester UI **Dashboard** screen.

  If you [customized the version](./automatic.md#customize-the-version), you might need to [create the version object](./automatic.md#prepare-the-version) again.
```
created_at: 2025-05-09T09:46:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
path: docs/upgrade/automatic.md
user: login: w13915984028
body: I guess now they are those `caution`s under https://docs.harvesterhci.io/v1.4/upgrade/index#start-an-upgrade, I will update the link to it.
created_at: 2025-05-12T08:34:24Z
author_association: MEMBER
diff_hunk: @@ -89,20 +89,66 @@ Check out the available [`upgrade-config` setting](../advanced/settings.md#upgra
 
 :::
 
-- Make sure to read the Warning paragraph at the top of this document first.
-- Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+1. Make sure to read the Warning paragraph at the top of this document first.
+
+1. Harvester checks if there are new upgradable versions periodically. If there are new versions, an upgrade button shows up on the Dashboard page.
+
     - If the cluster is in an air-gapped environment, please see [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade) section first. You can also speed up the ISO download by using the approach in that section.
-- Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
+
+1. Navigate to Harvester GUI and click the upgrade button on the Dashboard page.
 
     ![](/img/v1.2/upgrade/upgrade_button.png)
 
-- Select a version to start upgrading.
+1. Select a version to start upgrading. If you need to customize the version, refer [customization](#customize-the-version).
 
     ![](/img/v1.2/upgrade/upgrade_select_version.png)
 
-- Click the circle on the top to display the upgrade progress.
+1. Click the circle on the top to display the upgrade progress.
     ![](/img/v1.2/upgrade/upgrade_progress.png)
 
+### Customize the Version
+
+1. Download the version file from Harvester release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`.
+
+    Example: Harvester [v1.5.0 version file](https://releases.rancher.com/harvester/v1.5.0/version.yaml) is downloaded as `v1.5.0.yaml`.
+
+    ```
+    apiVersion: harvesterhci.io/v1beta1
+    kind: Version
+    metadata:
+      name: v1.5.0-customized # Changed, to avoid duplicated with the official version name
+      namespace: harvester-system
+    spec:
+      isoChecksum: 'df28e9bf8dc561c5c26dee535046117906581296d633eb2988e4f68390a281b6856a5a0bd2e4b5b988c695a53d0fc86e4e3965f19957682b74317109b1d2fe32'  # Don't change
+      isoURL: https://releases.rancher.com/harvester/v1.5.0/harvester-v1.5.0-amd64.iso # Official ISO path by default
+      releaseDate: '20250425'
+    ```
+
+1. Add following annotations on demand.
+
+1. Run `kubectl create -f v1.5.0.yaml` to create the version.
+
+#### Annotation minCertsExpirationInDay
+
+Harvester checkes the cert expiration days on each node. If any of them will expire in 7 days, an error is reported. This check eliminates the chance to hit cert experiation when upgrade is running.
+
+Example: The `harvesterhci.io/minCertsExpirationInDay: "14"` sets the check upon expiration days to 14.
+
+See [auto-rotate-rke2-certs](advanced/settings.md/#auto-rotate-rke2-certs) for more information.
path: docs/upgrade/automatic.md
user: login: w13915984028
body: I keep `will expire in 14 days` instead of `that is set to expire`.

The expire concept is as such: When a cert is set to expire in e.g. `30 days` and is updated `today`, then the system will count down, after 30 days, it is out-dated;   the annotation will guide the script to check all the certs, to compute the `remaining alive days`, if it is less than e.g. `14 days`, then report error.
created_at: 2025-05-12T09:13:54Z
author_association: MEMBER
diff_hunk: @@ -112,35 +158,60 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO File
+
+1. Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+### Prepare the Version
+
+1. Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
 
     - Replace `isoURL` value in the `version.yaml` file:
 
         ```
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
         spec:
           isoChecksum: <SHA-512 checksum of the ISO>
           isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
-          releaseDate: '20220512'
+          releaseDate: '20250425'
         ```
 
     - Assume the file is hosted at `http://10.10.0.1/version.yaml`.
 
-- Log in to one of your control plane nodes.
-- Become root and create a version:
+    - If you need to customize the version, refer [customization](#customize-the-version)
+
+1. Log in to one of your control plane nodes.
+
+1. Become root and create a version object:
 
     ```
     rancher@node1:~> sudo -i
     rancher@node1:~> kubectl create -f http://10.10.0.1/version.yaml
     ```
 
-- An upgrade button should show up on the Harvester GUI Dashboard page.
+### Trigger the Upgrade
+
+1. An upgrade button should show up on the Harvester GUI Dashboard page.
+
+    Refresh the web page if the button does not appear.
+
+## Manually Start an Upgrade before the Harvester Official Upgrade is Available
+
+After a new Harvester version is released, the official upgrade is not available right now, you do not see the `upgrade` button on your cluster.
+
+When you want to upgrade your cluster to the new release, follow the steps on [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade).
+
+:::caution
+
+It is recommended to wait until the official upgrade is available for production environment.
+
+:::
path: docs/upgrade/automatic.md
user: login: w13915984028
body: The `upgrade` action itself, is still UI-based, user clicks the `upgrade` button to start the upgrade and click the `circle` to view the progress.

The only difference is, the `upgrade` button does not appear, user needs to manually `create the version object`, and after that, all are same.

I keep the title unchanged for now.
created_at: 2025-05-12T09:17:35Z
author_association: MEMBER
diff_hunk: @@ -102,7 +102,7 @@ $ kubectl logs -n harvester-system jobs/hvst-upgrade-9gmg2-post-drain-node2
 
 :::caution
 
-Please do not start over an upgrade if the upgrade fails at this phase.
+Please do not [Start over an Upgrade](#start-over-an-upgrade) if the upgrade fails at this phase.
path: docs/upgrade/troubleshooting.md
user: login: w13915984028
body: Updated on https://github.com/harvester/docs/pull/773/commits/e6d39a583cbad5ba8e62ba9289174a28d16305b9, not sure the best answer, please take a new look, thanks.
created_at: 2025-05-12T09:31:38Z
author_association: MEMBER
diff_hunk: @@ -112,35 +158,60 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO File
+
+1. Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+### Prepare the Version
+
+1. Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
 
     - Replace `isoURL` value in the `version.yaml` file:
 
         ```
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
         spec:
           isoChecksum: <SHA-512 checksum of the ISO>
           isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
-          releaseDate: '20220512'
+          releaseDate: '20250425'
         ```
 
     - Assume the file is hosted at `http://10.10.0.1/version.yaml`.
 
-- Log in to one of your control plane nodes.
-- Become root and create a version:
+    - If you need to customize the version, refer [customization](#customize-the-version)
+
+1. Log in to one of your control plane nodes.
+
+1. Become root and create a version object:
 
     ```
     rancher@node1:~> sudo -i
     rancher@node1:~> kubectl create -f http://10.10.0.1/version.yaml
     ```
 
-- An upgrade button should show up on the Harvester GUI Dashboard page.
+### Trigger the Upgrade
+
+1. An upgrade button should show up on the Harvester GUI Dashboard page.
+
+    Refresh the web page if the button does not appear.
+
+## Manually Start an Upgrade before the Harvester Official Upgrade is Available
+
+After a new Harvester version is released, the official upgrade is not available right now, you do not see the `upgrade` button on your cluster.
+
+When you want to upgrade your cluster to the new release, follow the steps on [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade).
+
+:::caution
+
+It is recommended to wait until the official upgrade is available for production environment.
+
+:::
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: You can keep the original title, but please use the suggested wording.
created_at: 2025-05-14T11:21:37Z
author_association: CONTRIBUTOR
diff_hunk: @@ -112,35 +170,58 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO File
+
+1. Download a Harvester ISO file from the [Releases](https://github.com/harvester/harvester/releases) page.
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+### Prepare the Version
+
+1. Download the version file (`https://releases.rancher.com/harvester/{version}/version.yaml`).
 
     - Replace `isoURL` value in the `version.yaml` file:
 
         ```
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
         spec:
           isoChecksum: <SHA-512 checksum of the ISO>
           isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
-          releaseDate: '20220512'
+          releaseDate: '20250425'
         ```
 
     - Assume the file is hosted at `http://10.10.0.1/version.yaml`.
 
-- Log in to one of your control plane nodes.
-- Become root and create a version:
+    - If you require customizations, see [Customize the Version](#customize-the-version).
+
+1. Access one of the control plane nodes via SSH and log in using the root account.
+
+1. Create a version object.
 
     ```
     rancher@node1:~> sudo -i
     rancher@node1:~> kubectl create -f http://10.10.0.1/version.yaml
     ```
 
-- An upgrade button should show up on the Harvester GUI Dashboard page.
+### Start the Upgrade
+
+The **Upgrade** button appears on the **Dashboard** screen whenever a new Harvester version that you can upgrade to becomes available. Refresh the screen if the button does not appear.
+
+## Manually Start an Upgrade before the Harvester Official Upgrade is Available
+
+After a new Harvester version is released, the official upgrade is not available right now, you do not see the `upgrade` button on your cluster.
+
+When you want to upgrade your cluster to the new release, follow the steps on [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade).
+
+:::caution
+
+It is recommended to wait until the official upgrade is available for production environment.
+
+:::
path: docs/upgrade/automatic.md
user: login: jillian-maroket
body: ```suggestion
The **Upgrade** button does not appear on the UI immediately after a new Harvester version is released. If you want to upgrade your cluster before the option becomes available on the UI, follow the steps in [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade).

:::tip

In production environments, upgrading clusters via the Harvester UI is recommended.

:::
```
created_at: 2025-05-14T11:22:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -112,35 +170,58 @@ Make sure to check [Upgrade support matrix](#upgrade-support-matrix) section fir
 
 :::
 
-- Download a Harvester ISO file from [release pages](https://github.com/harvester/harvester/releases).
-- Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
-- Download the version file from release pages, for example, `https://releases.rancher.com/harvester/{version}/version.yaml`
+### Prepare the ISO File
+
+1. Download a Harvester ISO file from the [Releases](https://github.com/harvester/harvester/releases) page.
+
+1. Save the ISO to a local HTTP server. Assume the file is hosted at `http://10.10.0.1/harvester.iso`.
+
+### Prepare the Version
+
+1. Download the version file (`https://releases.rancher.com/harvester/{version}/version.yaml`).
 
     - Replace `isoURL` value in the `version.yaml` file:
 
         ```
         apiVersion: harvesterhci.io/v1beta1
         kind: Version
         metadata:
-          name: v1.0.2
+          name: v1.5.0
           namespace: harvester-system
         spec:
           isoChecksum: <SHA-512 checksum of the ISO>
           isoURL: http://10.10.0.1/harvester.iso  # change to local ISO URL
-          releaseDate: '20220512'
+          releaseDate: '20250425'
         ```
 
     - Assume the file is hosted at `http://10.10.0.1/version.yaml`.
 
-- Log in to one of your control plane nodes.
-- Become root and create a version:
+    - If you require customizations, see [Customize the Version](#customize-the-version).
+
+1. Access one of the control plane nodes via SSH and log in using the root account.
+
+1. Create a version object.
 
     ```
     rancher@node1:~> sudo -i
     rancher@node1:~> kubectl create -f http://10.10.0.1/version.yaml
     ```
 
-- An upgrade button should show up on the Harvester GUI Dashboard page.
+### Start the Upgrade
+
+The **Upgrade** button appears on the **Dashboard** screen whenever a new Harvester version that you can upgrade to becomes available. Refresh the screen if the button does not appear.
+
+## Manually Start an Upgrade before the Harvester Official Upgrade is Available
+
+After a new Harvester version is released, the official upgrade is not available right now, you do not see the `upgrade` button on your cluster.
+
+When you want to upgrade your cluster to the new release, follow the steps on [Prepare an air-gapped upgrade](#prepare-an-air-gapped-upgrade).
+
+:::caution
+
+It is recommended to wait until the official upgrade is available for production environment.
+
+:::
path: docs/upgrade/automatic.md
user: login: w13915984028
body: It is updated, and the commits are squashed now. thanks.
created_at: 2025-05-14T12:34:28Z
author_association: MEMBER

PR comments:
user: login: w13915984028
created_at: 2025-05-06T08:42:34Z
body: The changed doc will be copied to other versioned path after the main review is done.
author_association: MEMBER
user: login: github-actions[bot]
created_at: 2025-05-06T08:54:25Z
body: <!-- deploy-comment -->

|  Name | Link |
|:-:|------------------------|
|<span aria-hidden="true">🔨</span> Latest commit | 5e9baa144be087afba5c144dca172ae54c9c0c3c |
|<span aria-hidden="true">😎</span> Deploy Preview | https://682492dbd477308ba679305c--harvester-preview.netlify.app |

author_association: NONE
user: login: w13915984028
created_at: 2025-05-14T09:22:55Z
body: @jillian-maroket This PR is ready for final merge, please check if you have remaining comments, I will squash the commits in last minute, thanks.
author_association: MEMBER