doc(setting): add upgrade-config setting

Signed-off-by: Zespre Chang <[email protected]>
harvester · Aug 20, 2024 · e623469 · e623469
1 parent 6027f71
commit e623469
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 0 deletions.
diff --git a/docs/advanced/settings.md b/docs/advanced/settings.md
@@ -503,6 +503,61 @@ This setting can only be used if the `upgrade-checker-enabled` setting is set to
 https://your.upgrade.checker-url/v99/checkupgrade
 ```
 
+### `upgrade-config`
+
+**Definition**: Upgrade-related configuration.
+
+**Default value**: `{"imagePreloadOption":{"strategy":{"type":"sequential"}}}`
+
+**Example**:
+
+```json
+{
+  "imagePreloadOption": {
+    "strategy": {
+      "type": "parallel",
+      "concurrency": 2
+    }
+  }
+}
+```
+
+#### `imagePreloadOption`
+
+**Definition**: Options for the image-preloading phase.
+
+##### `strategy`
+
+**Definition**: Image preload strategy.
+
+###### `type`
+
+**Definition**: Type of the image preload strategy.
+
+There are three available types:
+
+- `skip`: Nodes will not preload images
+- `sequential`: Nodes will preload images one by one. This is the default.
+- `parallel`: Nodes will preload images in batches. This can be fine-tuned by the `concurrency` option.
+
+:::important
+
+Please do not use `skip` if your cluster is air-gapped. Harvester upgrade will fail if no new images are preloaded to the nodes or downloadable from any registry.
+
+:::
+
+###### `concurrency`
+
+**Definition**: Batch size of image preloading in terms of node count.
+
+Customize the number of nodes that can start preloading images simultaneously. The default value is `0`, which is equivalent to setting it with the cluster's node counts. One benefit of setting it to `0` is it dynamically follows the scale of the cluster. Values higher than the cluster's node counts are treated as `0`; values lower than 0 are invalid and will be rejected by Harvester.
+
+:::note
+
+The `concurrency` option only takes effect when the image-preload strategy `type` is set to `parallel`.
+
+:::
+
 ### `vip-pools`
 
 **Versions**: Deprecated as of v1.2.0 (Use [IP pools](../networking/ippool.md) instead.)

diff --git a/docs/upgrade/automatic.md b/docs/upgrade/automatic.md
@@ -39,6 +39,10 @@ For the Harvester & Rancher support matrix, please visit our website [here](http
 
 :::
 
+## Before starting an upgrade
+
+Check out the available [`upgrade-config` setting](../advanced/settings.md#upgrade-config) to tweak the upgrade strategies and behaviors that best suit your cluster environment.
+
 ## Start an upgrade
 
 :::caution