doc(setting): add upgrade-config setting

[starbops]

Add description for the newly introduced upgrade-config setting and its sub-options.

Related issues:

harvester/harvester#3059
harvester/harvester#6028

[github-actions]

Name	Link
🔨 Latest commit	78d0524
😎 Deploy Preview	https://66cd79100d24d79e4f7beee5--harvester-preview.netlify.app

[w13915984028]

For customer convenience, I have following suggestions, thanks.

[w13915984028]

Add another:

Harvester deploys a cluster-repo service on the cluster to serve as a http server for nodes to preload the image. When concurrency is set, certain number of nodes will download the Harvester ISO from this cluster-repo in parallel, following factors need to be considered:
(1) The Harvester management network speed.
(2) The writing speed of the default disk for Longhorn.

When your cluster has 20+ nodes, suggest to set the concurrency as 5.

note: Before we have tested this on a at least medium sized cluster, it is better to suggest a conservative number, rather than 0.

[starbops]

If we don't have data from experiments about the appropriate concurrency value, IMO we should not publish any concrete number in the documentation. Maybe just add a "this is an experimental function" warning?

[w13915984028]

experimental is a good label

[jillian-maroket]

@starbops I'll start my review after you check Jian's comments.

Also, I noticed that you used separate headings for the options. We now use an unordered list for such information (within the section dedicated to the setting). Is there any reason you decided to structure the content this way? Also, are all of the options required?

[starbops]

Hi @w13915984028 thank you for the suggestion. I've updated the content, PTAL.

Hi @jillian-maroket because each option under the upgrade-config setting deserves many content to describe its purpose, usage, and potential risks, I put them into dedicated sections. Besides, I'm unsure whether I can put that many kinds of markdown formats under an unordered list. If you have idea about this, I'm happy to change the current structure. Thank you.

[w13915984028]

LGTM, thanks.

[jillian-maroket]

@starbops Here is the recommended wording and structure:

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. 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 a cluster-repo service on the cluster that serves as an HTTP server for nodes that need to preload the image. When a concurrency value is set, each batch of nodes downloads the Harvester ISO from this cluster-repo in parallel. Because of this, you must consider the speed of the Harvester management network and the write speed of the default disk for Longhorn.

  :::

Example:

{
  "imagePreloadOption": {
    "strategy": {
      "type": "parallel",
      "concurrency": 2
    }
  }
}

[starbops]

Thank you @jillian-maroket. I slightly changed the wording in the last "note" section:

• cluster-repo -> upgrade-repo
  A harvester-cluster-repo pod and service is already out there, we should better use another name for the upgrade repo VM.
• Harvester ISO -> container images
  ISO image downloading happens before the image-preload phase. The nodes download the container images here.
• write -> read
  The read operations occur more often than writes in the upgrade repo VM because nodes download container images from it.

Please take a look.

[jillian-maroket]

@starbops The changes work for me so I'll approve now. Just please correct the grammatical error that I flagged ("a" > "an"). Thanks!