From cacc69bd284093b38597062e61109f2a6f44d8d2 Mon Sep 17 00:00:00 2001 From: Zespre Chang Date: Tue, 20 Aug 2024 19:47:19 +0800 Subject: [PATCH] doc(setting): add upgrade-config setting Signed-off-by: Zespre Chang Co-authored-by: Jian Wang Co-authored-by: Jillian <67180770+jillian-maroket@users.noreply.github.com> --- docs/advanced/settings.md | 56 +++++++++++++++++++++++++++++++++++++++ docs/upgrade/automatic.md | 4 +++ 2 files changed, 60 insertions(+) diff --git a/docs/advanced/settings.md b/docs/advanced/settings.md index dc814378ab6..dd7337e590d 100644 --- a/docs/advanced/settings.md +++ b/docs/advanced/settings.md @@ -503,6 +503,62 @@ 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"}}}` + +**Supported options and fields**: + +- `imagePreloadOption`: Options for the image preloading phase. + + The full ISO contains the core operating system components and all required container images. Harvester can preload these container images to each node during installation and upgrades. When workloads are scheduled to management and worker nodes, the container images are ready to use. + +- `strategy`: Image preload strategy. + +- `type`: Type of image preload strategy. + + - `sequential`: Harvester preloads the container images from the target ISO to each node. This is the default option. + + - `skip`: Harvester does not preload the container images from the target ISO to each node. **Do not use this option in production environments.** + + :::info important + + If you decide to use `skip`, ensure that the following requirements are met: + + - You have a private container registry that contains all required images. + - Your cluster has high-speed internet access and is able to pull all images from Docker Hub when necessary. + + 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. + + ::: + + - `parallel` (**experimental**): Nodes preload images in batches. You can adjust this using the `concurrency` option. + +- `concurrency`: Number of nodes that can simultaneously preload images. This option takes effect only when `type` is set to `parallel`. + + The default value is `0`, which is equivalent to following the cluster's node counts. Using `0` allows the system to dynamically follow the scale of the cluster. Values higher than the cluster's node counts are treated as `0`, while lower values are considered invalid and are rejected by Harvester. + + :::note + + Harvester deploys an upgrade-repo service on the cluster that serves as an HTTP server for nodes that need to preload the container images. When a `concurrency` value is set, each batch of nodes downloads the container images from this upgrade-repo in parallel. Because of this, you must consider the speed of the Harvester management network and the read speed of the default disk for Longhorn. + + ::: + +**Example**: + +```json +{ + "imagePreloadOption": { + "strategy": { + "type": "parallel", + "concurrency": 2 + } + } +} +``` + ### `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 index d90309577da..e3b92276045 100644 --- 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