UpgradeController and SystemUpgradeController (#577)

* Clarify UpgradeController and SystemUpgradeController, when to use what, and why both are used

Add minimum required components for upgrade operations

* Update UpgradeController and SysUpgController and Upgrade doc (#577)

Refine the description and remove the duplicated statement

* Update asciidoc/components/upgrade-controller.adoc
* Update asciidoc/components/system-upgrade-controller.adoc
* Update asciidoc/day2/migration.adoc

Co-authored-by: Ivo Petrov <[email protected]>

* Update Update Controller description (#577)

* Update asciidoc/components/upgrade-controller.adoc
* Withdraw previous changes from asciidoc/day2/migration.adoc

* Update UpgradeController and SUC descriptions (#577)

* Update asciidoc/components/upgrade-controller.adoc
* Update asciidoc/components/system-upgrade-controller.adoc

Co-authored-by: Ivo Petrov <[email protected]>

---------

Co-authored-by: Ivo Petrov <[email protected]>
(cherry picked from commit 41cd7cd)

Author: 2 people

asciidoc/components/system-upgrade-controller.adoc

@@ -19,7 +19,11 @@ ____
 
 == How does SUSE Edge use System Upgrade Controller?
 
-*SUC* is used to assist in the various "Day 2" operations that need to be executed in order to upgrade management/downstream clusters from one Edge platform version to another. Day 2 operations are defined in the form of *SUC Plans*. Based on the these plans, SUC deploys workloads on each node that executes the respective Day 2 operations.
+SUSE Edge uses `SUC` to facilitate various "Day 2" operations related to OS and Kubernetes version upgrades on management and downstream clusters.
+
+"Day 2" operations are defined through `SUC Plans`. Based on these plans, `SUC` deploys workloads on each node to execute the respective "Day 2" operation.
+
+`SUC` is also used within the <<components-upgrade-controller>>. To learn more about the key differences between SUC and the Upgrade Controller, see <<components-upgrade-controller-uc-vs-suc>>.
 
 [#components-system-upgrade-controller-install]
 == Installing the System Upgrade Controller

asciidoc/components/upgrade-controller.adoc

@@ -10,16 +10,18 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-See the link:https://github.com/suse-edge/upgrade-controller[Upgrade Controller] documentation.
-
-[quote]
-____
-A Kubernetes controller capable of performing infrastructure platform upgrades consisting of:
+A Kubernetes controller capable of performing upgrades over the following SUSE Edge platform components:
 
 * Operating System (SUSE Linux Micro)
 * Kubernetes (K3s & RKE2)
 * Additional components (Rancher, Elemental, SUSE Security, etc.)
-____
+
+The link:https://github.com/suse-edge/upgrade-controller[Upgrade Controller] streamlines the upgrade process for the components mentioned above by encapsulating their complexities within a single `user-facing` resource that serves as a *trigger* for the upgrade. Users only need to configure this resource and the `Upgrade Controller` takes care of the rest.
+
+[NOTE]
+====
+The `Upgrade Controller` currently supports SUSE Edge platform upgrades only for *non air-gapped management* clusters. Refer to the <<components-upgrade-controller-known-issues>> section for more information.
+====
 
 == How does SUSE Edge use Upgrade Controller?
 
@@ -31,6 +33,17 @@ For further details on how the Upgrade Controller works, see <<components-upgrad
 
 For known limitations that the Upgrade Controller has, see <<components-upgrade-controller-known-issues>>.
 
+For information on the difference between the Upgrade Controller and the System Upgrade Controller, see <<components-upgrade-controller-uc-vs-suc>>.
+
+[#components-upgrade-controller-uc-vs-suc]
+== Upgrade Controller vs System Upgrade Controller
+
+The <<components-system-upgrade-controller, System Upgrade Controller (SUC)>> is a general-purpose tool that propagates upgrade instructions to specific Kubernetes nodes.
+
+While it supports some "Day 2" operations for the SUSE Edge platform, it *does not* cover all of them. Moreover, even for supported operations, users have to manually configure, maintain, and deploy multiple `SUC Plans` — an error-prone process that can lead to unexpected issues.
+
+This led to the need for a tool that **automates** and **abstracts** the complexity of managing various "Day 2" operations for the SUSE Edge platform. Thus, the `Upgrade Controller` was developed. It simplifies the upgrade process by introducing a single `user-facing resource` that drives the upgrade. Users only need to manage this resource, while the `Upgrade Controller` takes care of the rest.
+
 [#components-upgrade-controller-installation]
 == Installing the Upgrade Controller
 
@@ -159,7 +172,7 @@ For Helm charts deployed outside of EIB, the Upgrade Controller creates a `HelmC
 
 After the creation/update of the `HelmChart` resource, the Upgrade Controller relies on the link:https://github.com/k3s-io/helm-controller/[helm-controller] to pick up this change and proceed with the actual component upgrade.
 
-Charts will be upgraded sequentially based on their order in the `ReleaseManifest`. Additional values can also be passed through the `UpgradePlan`. For more information about this, refer to <<components-upgrade-controller-extensions-upgrade-plan>>.
+Charts will be upgraded sequentially based on their order in the `ReleaseManifest`. Additional values can also be passed through the `UpgradePlan`. If a chart's version remains unchanged in the new SUSE Edge release, it will not be upgraded. For more information about this, refer to <<components-upgrade-controller-extensions-upgrade-plan>>.
 
 [#components-upgrade-controller-extensions]
 == Kubernetes API extensions