Update free system space requirement (#765)

w13915984028 · web-flow · commit c351674f01fa · 2025-05-06T09:49:12.000+02:00
* Update free system space requirement

Signed-off-by: Jian Wang &lt;jian.wang@suse.com&gt;

* Address comments and add a caution

Signed-off-by: Jian Wang &lt;jian.wang@suse.com&gt;

---------

Signed-off-by: Jian Wang &lt;jian.wang@suse.com&gt;
diff --git a/docs/install/requirements.md b/docs/install/requirements.md
@@ -26,7 +26,7 @@ Harvester nodes have the following hardware requirements and recommendations for
 | :--- | :--- | :--- |
 | CPU | ARM64 or x86_64 (with hardware-assisted virtualization); 8 cores minimum | ARM64 or x86_64 (with hardware-assisted virtualization); 16 cores minimum |
 | Memory | 32 GB minimum | 64 GB minimum |
-| Disk capacity	| 250 GB minimum (180 GB minimum when using multiple disks) | 500 GB minimum |
+| Disk capacity	| 250 GB minimum (180 GB minimum when using multiple disks) | 500 GB minimum, 1 TB or more recommended |
 | Disk performance | 5,000+ random IOPS per disk (SSD/NVMe); management node storage must meet [etcd](https://www.suse.com/support/kb/doc/?id=000020100) speed requirements. Only local disks and hardware RAID are supported. | 5,000+ random IOPS per disk (SSD/NVMe); management node storage must meet [etcd](https://www.suse.com/support/kb/doc/?id=000020100) speed requirements. Only local disks and hardware RAID are supported. |
 | Network card count | Management cluster network: 1 NIC required, 2 NICs recommended; VM workload network: 1 NIC required, at least 2 NICs recommended (does not apply to the [witness node](../advanced/witness.md)) | Management cluster network: 1 NIC required, 2 NICs recommended; VM workload network: 1 NIC required, at least 2 NICs recommended (does not apply to the [witness node](../advanced/witness.md)) |
 | Network card speed | 1 Gbps Ethernet minimum | 10 Gbps Ethernet minimum |
@@ -39,6 +39,7 @@ Harvester nodes have the following hardware requirements and recommendations for
 - Each node must have a unique `product_uuid` (fetched from `/sys/class/dmi/id/product_uuid`) to prevent errors from occurring during VM live migration and other operations. For more information, see [Issue #4025](https://github.com/harvester/harvester/issues/4025).
 - Harvester has a [built-in management cluster network](../networking/clusternetwork.md#built-in-cluster-network) (`mgmt`). To achieve high availability and the best performance in production environments, use at least two NICs in each node to set up a bonded NIC for the management network (see step 6 in [ISO Installation](../install/iso-install.md#installation-steps)). You can also create [custom cluster networks](../networking/clusternetwork.md#custom-cluster-network) for VM workloads. Each custom cluster network requires at least two additional NICs to set up a bonded NIC in every involved node of the Harvester cluster. The [witness node](../advanced/witness.md) does not require additional NICs. For more information, see [Cluster Network](../networking/clusternetwork.md#concepts).
 - During testing, you can use only one NIC for the [built-in management cluster network](../networking/clusternetwork.md#built-in-cluster-network) (`mgmt`), and for testing the [VM network](../networking/harvester-network.md#create-a-vm-network) that is also carried by `mgmt`. High availability and optimal performance are not guaranteed.
+- If the disk only meets the minimum required capacity, you may encounter issues related to the [free system partition space requirement](../upgrade/automatic.md#free-system-partition-space-requirement) during upgrades.
 :::
 
 ### CPU Specifications
diff --git a/docs/upgrade/automatic.md b/docs/upgrade/automatic.md
@@ -175,6 +175,28 @@ Setting a smaller value than the pre-defined value may cause the upgrade to fail
 
 :::
 
+The following sections describe solutions for issues related to this requirement.
+
+### Free System Partition Space Manually
+
+Harvester attempts to remove unnecessary container images after an upgrade is completed. However, this automatic image cleanup may not be performed for various reasons. You can use [this script](https://github.com/harvester/upgrade-helpers/blob/main/bin/harv-purge-images.sh) to manually remove images. For more information, see issue [#6620](https://github.com/harvester/harvester/issues/6620).
+
+### Set Up a Private Container Registry and Skip Image Preloading
+
+The system partition might still lack free space even after you remove images. To address this, set up a private container registry for both current and new images, and configure the setting [`upgrade-config`](advanced/settings.md#upgrade-config) with following value:
+
+```
+{"imagePreloadOption":{"strategy":{"type":"skip"}}, "restoreVM": false}
+```
+
+Harvester skips the upgrade image preloading process. When the deployments on the nodes are upgraded, the container runtime loads the images stored in the private container registry.
+
+:::caution
+
+Do not rely on the public container registry. Note any potential internet service interruptions and how close you are to reaching your [Docker Hub rate limit](https://www.docker.com/increase-rate-limits/). Failure to download any of the required images may cause the upgrade to fail and may leave the cluster in a middle state.
+
+:::
+
 ## VM Backup Compatibility
 
 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)
diff --git a/versioned_docs/version-v1.4/install/requirements.md b/versioned_docs/version-v1.4/install/requirements.md
@@ -26,7 +26,7 @@ Harvester nodes have the following hardware requirements and recommendations for
 | :--- | :--- | :--- |
 | CPU | ARM64 or x86_64 (with hardware-assisted virtualization); 8 cores minimum | ARM64 or x86_64 (with hardware-assisted virtualization); 16 cores minimum |
 | Memory | 32 GB minimum | 64 GB minimum |
-| Disk capacity	| 250 GB minimum (180 GB minimum when using multiple disks) | 500 GB minimum |
+| Disk capacity	| 250 GB minimum (180 GB minimum when using multiple disks) | 500 GB minimum, 1 TB or more recommended |
 | Disk performance | 5,000+ random IOPS per disk (SSD/NVMe); management node storage must meet [etcd](https://www.suse.com/support/kb/doc/?id=000020100) speed requirements. Only local disks and hardware RAID are supported. | 5,000+ random IOPS per disk (SSD/NVMe); management node storage must meet [etcd](https://www.suse.com/support/kb/doc/?id=000020100) speed requirements. Only local disks and hardware RAID are supported. |
 | Network card count | Management cluster network: 1 NIC required, 2 NICs recommended; VM workload network: 1 NIC required, at least 2 NICs recommended (does not apply to the [witness node](../advanced/witness.md)) | Management cluster network: 1 NIC required, 2 NICs recommended; VM workload network: 1 NIC required, at least 2 NICs recommended (does not apply to the [witness node](../advanced/witness.md)) |
 | Network card speed | 1 Gbps Ethernet minimum | 10 Gbps Ethernet minimum |
@@ -38,6 +38,7 @@ Harvester nodes have the following hardware requirements and recommendations for
 - Each node must have a unique `product_uuid` (fetched from `/sys/class/dmi/id/product_uuid`) to prevent errors from occurring during VM live migration and other operations. For more information, see [Issue #4025](https://github.com/harvester/harvester/issues/4025).
 - Harvester has a [built-in management cluster network](../networking/clusternetwork.md#built-in-cluster-network) (`mgmt`). To achieve high availability and the best performance in production environments, use at least two NICs in each node to set up a bonded NIC for the management network (see step 6 in [ISO Installation](../install/iso-install.md#installation-steps)). You can also create [custom cluster networks](../networking/clusternetwork.md#custom-cluster-network) for VM workloads. Each custom cluster network requires at least two additional NICs to set up a bonded NIC in every involved node of the Harvester cluster. The [witness node](../advanced/witness.md) does not require additional NICs. For more information, see [Cluster Network](../networking/clusternetwork.md#concepts).
 - During testing, you can use only one NIC for the [built-in management cluster network](../networking/clusternetwork.md#built-in-cluster-network) (`mgmt`), and for testing the [VM network](../networking/harvester-network.md#create-a-vm-network) that is also carried by `mgmt`. High availability and optimal performance are not guaranteed.
+- If the disk only meets the minimum required capacity, you may encounter issues related to the [free system partition space requirement](../upgrade/automatic.md#free-system-partition-space-requirement) during upgrades.
 :::
 
 ### CPU Specifications
diff --git a/versioned_docs/version-v1.4/upgrade/automatic.md b/versioned_docs/version-v1.4/upgrade/automatic.md
@@ -174,6 +174,28 @@ Setting a smaller value than the pre-defined value may cause the upgrade to fail
 
 :::
 
+The following sections describe solutions for issues related to this requirement.
+
+### Free System Partition Space Manually
+
+Harvester attempts to remove unnecessary container images after an upgrade is completed. However, this automatic image cleanup may not be performed for various reasons. You can use [this script](https://github.com/harvester/upgrade-helpers/blob/main/bin/harv-purge-images.sh) to manually remove images. For more information, see issue [#6620](https://github.com/harvester/harvester/issues/6620).
+
+### Set Up a Private Container Registry and Skip Image Preloading
+
+The system partition might still lack free space even after you remove images. To address this, set up a private container registry for both current and new images, and configure the setting [`upgrade-config`](advanced/settings.md#upgrade-config) with following value:
+
+```
+{"imagePreloadOption":{"strategy":{"type":"skip"}}, "restoreVM": false}
+```
+
+Harvester skips the upgrade image preloading process. When the deployments on the nodes are upgraded, the container runtime loads the images stored in the private container registry.
+
+:::caution
+
+Do not rely on the public container registry. Note any potential internet service interruptions and how close you are to reaching your [Docker Hub rate limit](https://www.docker.com/increase-rate-limits/). Failure to download any of the required images may cause the upgrade to fail and may leave the cluster in a middle state.
+
+:::
+
 ## Longhorn Manager Crashes Due to Backing Image Eviction
 
 :::caution
diff --git a/versioned_docs/version-v1.5/install/requirements.md b/versioned_docs/version-v1.5/install/requirements.md
@@ -26,7 +26,7 @@ Harvester nodes have the following hardware requirements and recommendations for
 | :--- | :--- | :--- |
 | CPU | ARM64 or x86_64 (with hardware-assisted virtualization); 8 cores minimum | ARM64 or x86_64 (with hardware-assisted virtualization); 16 cores minimum |
 | Memory | 32 GB minimum | 64 GB minimum |
-| Disk capacity	| 250 GB minimum (180 GB minimum when using multiple disks) | 500 GB minimum |
+| Disk capacity	| 250 GB minimum (180 GB minimum when using multiple disks) | 500 GB minimum, 1 TB or more recommended |
 | Disk performance | 5,000+ random IOPS per disk (SSD/NVMe); management node storage must meet [etcd](https://www.suse.com/support/kb/doc/?id=000020100) speed requirements. Only local disks and hardware RAID are supported. | 5,000+ random IOPS per disk (SSD/NVMe); management node storage must meet [etcd](https://www.suse.com/support/kb/doc/?id=000020100) speed requirements. Only local disks and hardware RAID are supported. |
 | Network card count | Management cluster network: 1 NIC required, 2 NICs recommended; VM workload network: 1 NIC required, at least 2 NICs recommended (does not apply to the [witness node](../advanced/witness.md)) | Management cluster network: 1 NIC required, 2 NICs recommended; VM workload network: 1 NIC required, at least 2 NICs recommended (does not apply to the [witness node](../advanced/witness.md)) |
 | Network card speed | 1 Gbps Ethernet minimum | 10 Gbps Ethernet minimum |
@@ -39,6 +39,7 @@ Harvester nodes have the following hardware requirements and recommendations for
 - Each node must have a unique `product_uuid` (fetched from `/sys/class/dmi/id/product_uuid`) to prevent errors from occurring during VM live migration and other operations. For more information, see [Issue #4025](https://github.com/harvester/harvester/issues/4025).
 - Harvester has a [built-in management cluster network](../networking/clusternetwork.md#built-in-cluster-network) (`mgmt`). To achieve high availability and the best performance in production environments, use at least two NICs in each node to set up a bonded NIC for the management network (see step 6 in [ISO Installation](../install/iso-install.md#installation-steps)). You can also create [custom cluster networks](../networking/clusternetwork.md#custom-cluster-network) for VM workloads. Each custom cluster network requires at least two additional NICs to set up a bonded NIC in every involved node of the Harvester cluster. The [witness node](../advanced/witness.md) does not require additional NICs. For more information, see [Cluster Network](../networking/clusternetwork.md#concepts).
 - During testing, you can use only one NIC for the [built-in management cluster network](../networking/clusternetwork.md#built-in-cluster-network) (`mgmt`), and for testing the [VM network](../networking/harvester-network.md#create-a-vm-network) that is also carried by `mgmt`. High availability and optimal performance are not guaranteed.
+- If the disk only meets the minimum required capacity, you may encounter issues related to the [free system partition space requirement](../upgrade/automatic.md#free-system-partition-space-requirement) during upgrades.
 :::
 
 ### CPU Specifications
diff --git a/versioned_docs/version-v1.5/upgrade/automatic.md b/versioned_docs/version-v1.5/upgrade/automatic.md
@@ -175,6 +175,28 @@ Setting a smaller value than the pre-defined value may cause the upgrade to fail
 
 :::
 
+The following sections describe solutions for issues related to this requirement.
+
+### Free System Partition Space Manually
+
+Harvester attempts to remove unnecessary container images after an upgrade is completed. However, this automatic image cleanup may not be performed for various reasons. You can use [this script](https://github.com/harvester/upgrade-helpers/blob/main/bin/harv-purge-images.sh) to manually remove images. For more information, see issue [#6620](https://github.com/harvester/harvester/issues/6620).
+
+### Set Up a Private Container Registry and Skip Image Preloading
+
+The system partition might still lack free space even after you remove images. To address this, set up a private container registry for both current and new images, and configure the setting [`upgrade-config`](advanced/settings.md#upgrade-config) with following value:
+
+```
+{"imagePreloadOption":{"strategy":{"type":"skip"}}, "restoreVM": false}
+```
+
+Harvester skips the upgrade image preloading process. When the deployments on the nodes are upgraded, the container runtime loads the images stored in the private container registry.
+
+:::caution
+
+Do not rely on the public container registry. Note any potential internet service interruptions and how close you are to reaching your [Docker Hub rate limit](https://www.docker.com/increase-rate-limits/). Failure to download any of the required images may cause the upgrade to fail and may leave the cluster in a middle state.
+
+:::
+
 ## VM Backup Compatibility
 
 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)
