Update docs/upgrade/v1-5-x-to-v1-6-0.md

rrajendran17 · jillian-maroket · rrajendran17 · commit 373bf63d2773 · 2025-10-08T10:52:12.000-07:00
Co-authored-by: Jillian Maroket &lt;67180770+jillian-maroket@users.noreply.github.com&gt;
Signed-off-by: Renuka Devi Rajendran &lt;renuka.rajendran@suse.com&gt;
diff --git a/docs/networking/clusternetwork.md b/docs/networking/clusternetwork.md
@@ -80,18 +80,16 @@ When a Harvester cluster is deployed, a cluster network named `mgmt` is automati
 
 `mgmt` does not require a network configuration and is always enabled on all hosts. You cannot disable and delete `mgmt`.
 
-_Change in behaviour as of v1.6.0_
-
-The [primary VLAN ID](https://docs.harvesterhci.io/latest/install/harvester-configuration#installmanagement_interface) provided during installation is automatically added to the `mgmt-br` bridge and the `mgmt-bo` interface. You can [add secondary VLAN interfaces](#add-secondary-vlan-interfaces) after installation is completed.
-
-::: note
+:::note
 
-In Harvester v1.5.0 and earlier versions, the entire VLAN ID range (2 to 4094) was assigned to the `mgmt` interfaces. This prevented hardware VLAN offloading from functioning correctly on certain network cards.
+In Harvester v1.5.x and earlier versions, the entire VLAN ID range (2 to 4094) was assigned to the `mgmt` interfaces. However, this exceeded the upper limit of supported VLANs on certain network cards, so hardware VLAN offloading stopped working correctly.
 
 For more information, see [issue #7650](https://github.com/harvester/harvester/issues/7650).
 
 :::
 
+As of v1.6.0,only the [primary VLAN ID](https://docs.harvesterhci.io/latest/install/harvester-configuration#installmanagement_interface) provided during installation is automatically added to the `mgmt-br` bridge and the `mgmt-bo` interface. You can [add secondary VLAN interfaces](#add-secondary-vlan-interfaces) after installation is completed.
+
 During installation of the first cluster node, you can configure the MTU value for `mgmt` using the [`install.management_interface`](../install/harvester-configuration.md#installmanagement_interface) setting. The default value of the `mtu` field is `1500`, which is what `mgmt` typically uses. However, if you specify an MTU value other than `0` or `1500`, you must [add a corresponding annotation](#annotate-a-non-default-mtu-value-to-mgmt-after-installation) after the cluster is deployed.
 
 :::caution
@@ -102,6 +100,29 @@ During installation of the first cluster node, you can configure the MTU value f
 
 :::
 
+### Add Secondary VLAN Interfaces
+
+Add the following commands to the `/oem/90_custom.yaml` file and reboot the node.
+
+- `/etc/wicked/scripts/setup_bond.sh` section
+
+    ```
+    bridge vlan add vid <vlan-id> dev $INTERFACE
+    ```
+
+- `/etc/wicked/scripts/setup_bridge.sh` section
+
+    ```
+    bridge vlan add vid <vlan-id> dev $INTERFACE self
+    bridge vlan add vid <vlan-id> dev mgmt-bo
+    ```
+
+:::info important
+
+You must include a separate command for each distinct VLAN ID. Ensure that the `vlan-id` placeholder is replaced with the actual ID.
+
+:::
+
 #### Annotate a Non-Default MTU Value to `mgmt` After Installation
 
 _Available as of v1.6.0_
diff --git a/docs/upgrade/v1-5-x-to-v1-6-0.md b/docs/upgrade/v1-5-x-to-v1-6-0.md
@@ -154,9 +154,9 @@ The workaround is to replace the above contents generated from gopkg.in/yaml.v3
 
 Related issue: [#9033](https://github.com/harvester/harvester/issues/9033)
 
-### 5. Network connectivity issue on secondary vlans for mgmt interface
+### 5. Network connectivity lost on secondary VLAN interfaces on the `mgmt` cluster network
 
-A change introduced in v1.6.0 to fix a hardware VLAN offloading issue unintentionally created a new issue. All secondary VLAN interfaces previously connected to the `mgmt-br` bridge and `mgmt-bo` are removed from the management hosts after the cluster is upgraded to v1.6.x.
+In v1.6.0, a feature change was introduced to only attach required VLAN interfaces to mgmt-br and mgmt-bo, instead of all secondary VLANs. This is intended behavior to reduce unnecessary VLAN provisioning.Due to this all secondary VLAN interfaces previously attached to the `mgmt-br` bridge and `mgmt-bo` are removed from the management hosts after the cluster is upgraded to v1.6.x.
 
 :::warning
 
@@ -166,15 +166,16 @@ For more information, see [issue #7650](https://github.com/harvester/harvester/i
 
 :::
 
-Before upgrading to v1.6.x, perform the following steps:
+After upgrading to v1.6.x, perform the following steps:
 
-1. Identify secondary VLAN interfaces by running the following command on management hosts:
+1. Verify VLANs attached to the `mgmt-br` and `mgmt-bo` by running the following command on management hosts:
 
     ```
     bridge vlan show
     ```
+   The above outputs only the primary vlan part of `mgmt-br` and `mgmt-bo`
 
-1. Manually add the VLAN interfaces to the `mgmt-br` bridge and the `mgmt-bo` interface by adding the following commands to the `/oem/90_custom.yaml` file:
+1. Manually add the required secondary VLANs to the `mgmt-br` bridge and the `mgmt-bo` interface by adding the following commands to the `/oem/90_custom.yaml` file:
   
     - `/etc/wicked/scripts/setup_bond.sh` section
   
@@ -191,21 +192,19 @@ Before upgrading to v1.6.x, perform the following steps:
 
     :::info important
 
-    You must include a separate command for each distinct VLAN ID. Ensure that the <vlan-id> placeholder is replaced with the actual ID.
+    You must include a separate command for each distinct VLAN ID. Ensure that the `vlan-id` placeholder is replaced with the actual ID.
 
     :::
 
 1. Once the `/oem/90_custom.yaml` file is updated, reboot the management hosts.
 
-1. Verify that the VLAN interfaces were added by running the following command on the hosts:
+1. Verify that all the required VLANs were added by running the following command on the hosts:
 
     ```
     bridge vlan show
     ```
 
-#### Upgrade Scenario
-
-Starting with v1.6.0, only the primary VLAN ID is assigned to the `mgmt-br` bridge and the `mgmt-bo` interface, rather than the entire VLAN ID range (2–4094). Consequently, communications that use secondary VLANs on the `mgmt` interface are affected.
+#### Upgrade Scenario Example
 
 In the following example, a v1.5.x cluster was initially installed with a [primary VLAN interface](../install/harvester-configuration.md#installmanagement_interface) (VLAN ID: `2021`). To add a secondary VLAN interface (VLAN ID: `2113`), the `/oem/99_vlan-ifcfg.yaml` file  was created on the management hosts with the following contents:
 
@@ -228,7 +227,7 @@ stages:
             DEFROUTE='no'
 
 ```
-Users expect to create an additional vlan sub interface on mgmt interface `mgmt-br.2113` and assign IPv4 address and use it for L3 connectivity in addition to the primary `mgmt-br.2021` interface after upgrade to v1.6.x.
-The additional vlan sub interface is created, but `mgmt-br` bridge and `mgmt-bo` will no longer be part of vlan `2113` as after reboot only the primary `vlan-id` will be assigned to the `mgmt-br` bridge and `mgmt-bo` using `/oem/90_custom.yaml`.Starting from v1.6.0, only primary vlan will be added to `mgmt-br` bridge and `mgmt-bo` instead of all 2-4094 vlans.Due to this communication using secondary vlans on mgmt interface is affected.
-To mitigate the effects of this change, you must perform the workaround described in the previous section. This involves identifying secondary VLAN interfaces and then adding the necessary ones to the `mgmt-br` bridge and the `mgmt-bo` interface.
-```
+The typical expectation is that an additional VLAN sub-interface is created on the `mgmt` interface (`mgmt-br.2113`) and assigned an IPv4 address. In addition, this sub-interface and the primary interface (`mgmt-br.2021`) are both expected to be used for L3 connectivity after the cluster is upgraded to v1.6.x.
+
+In actuality after upgrade to v1.6.0, however, the VLAN sub-interface is created but the secondary VLAN (VLAN ID: `2113`) is removed from the `mgmt-br` bridge and the `mgmt-bo` interface. After a reboot, only the primary VLAN ID is assigned to the `mgmt-br` bridge and the `mgmt-bo` interface (using the `/oem/90_custom.yaml` file).
+To mitigate the effects of this change, you must perform the workaround described in the previous section. This involves identifying secondary VLAN interfaces and then adding the necessary ones to the `mgmt-br` bridge and the `mgmt-bo` interface.
diff --git a/versioned_docs/version-v1.6/networking/clusternetwork.md b/versioned_docs/version-v1.6/networking/clusternetwork.md
@@ -80,21 +80,15 @@ When a Harvester cluster is deployed, a cluster network named `mgmt` is automati
 
 `mgmt` does not require a network configuration and is always enabled on all hosts. You cannot disable and delete `mgmt`.
 
-_Change in behaviour as of v1.6.0_
+:::note
 
-Starting from v1.6.0, only primary vlan configured during installation will be added to `mgmt-br` bridge and `mgmt-bo` instead of all 2-4094 vlans.Users can check this info using `bridge vlan show` command on the host.
-Any additional vlans required on the `mgmt-br` bridge and `mgmt-bo` must be explicitly configured using the following, and repeat below for every secondary `vlan-id` or vlan range the user requires.
+In Harvester v1.5.x and earlier versions, the entire VLAN ID range (2 to 4094) was assigned to the `mgmt` interfaces. However, this exceeded the upper limit of supported VLANs on certain network cards, so hardware VLAN offloading stopped working correctly.
 
-Add the following under contents of /etc/wicked/scripts/setup_bond.sh in /oem/90_custom.yaml
-```
-bridge vlan add vid <vlan-id> dev $INTERFACE
-```
+For more information, see [issue #7650](https://github.com/harvester/harvester/issues/7650).
 
-Add the following under contents of /etc/wicked/scripts/setup_bridge.sh in /oem/90_custom.yaml
-```
-bridge vlan add vid <vlan-id> dev $INTERFACE self
-bridge vlan add vid <vlan-id> dev mgmt-bo
-```
+:::
+
+As of v1.6.0,only the [primary VLAN ID](https://docs.harvesterhci.io/latest/install/harvester-configuration#installmanagement_interface) provided during installation is automatically added to the `mgmt-br` bridge and the `mgmt-bo` interface. You can [add secondary VLAN interfaces](#add-secondary-vlan-interfaces) after installation is completed.
 
 During installation of the first cluster node, you can configure the MTU value for `mgmt` using the [`install.management_interface`](../install/harvester-configuration.md#installmanagement_interface) setting. The default value of the `mtu` field is `1500`, which is what `mgmt` typically uses. However, if you specify an MTU value other than `0` or `1500`, you must [add a corresponding annotation](#annotate-a-non-default-mtu-value-to-mgmt-after-installation) after the cluster is deployed.
 
@@ -106,6 +100,29 @@ During installation of the first cluster node, you can configure the MTU value f
 
 :::
 
+### Add Secondary VLAN Interfaces
+
+Add the following commands to the `/oem/90_custom.yaml` file and reboot the node.
+
+- `/etc/wicked/scripts/setup_bond.sh` section
+
+    ```
+    bridge vlan add vid <vlan-id> dev $INTERFACE
+    ```
+
+- `/etc/wicked/scripts/setup_bridge.sh` section
+
+    ```
+    bridge vlan add vid <vlan-id> dev $INTERFACE self
+    bridge vlan add vid <vlan-id> dev mgmt-bo
+    ```
+
+:::info important
+
+You must include a separate command for each distinct VLAN ID. Ensure that the `vlan-id` placeholder is replaced with the actual ID.
+
+:::
+
 #### Annotate a Non-Default MTU Value to `mgmt` After Installation
 
 _Available as of v1.6.0_
diff --git a/versioned_docs/version-v1.6/upgrade/v1-5-x-to-v1-6-0.md b/versioned_docs/version-v1.6/upgrade/v1-5-x-to-v1-6-0.md
@@ -154,11 +154,59 @@ The workaround is to replace the above contents generated from gopkg.in/yaml.v3
 
 Related issue: [#9033](https://github.com/harvester/harvester/issues/9033)
 
-### 5. Network connectivity issue on secondary vlans for mgmt interface
+### 5. Network connectivity lost on secondary VLAN interfaces on the `mgmt` cluster network
 
-If users configure secondary vlan interfaces for mgmt interface in addition to the primary vlan configured during installation, then after upgrade from v1.5.x to v1.6.x, the additional vlans will not be part of the `mgmt-br` bridge and `mgmt-bo` due to which network connectivity on those secondary vlans are affected.
+In v1.6.0, a feature change was introduced to only attach required VLAN interfaces to mgmt-br and mgmt-bo, instead of all secondary VLANs. This is intended behavior to reduce unnecessary VLAN provisioning.Due to this all secondary VLAN interfaces previously attached to the `mgmt-br` bridge and `mgmt-bo` are removed from the management hosts after the cluster is upgraded to v1.6.x.
 
-For example, consider user having a mgmt interface configured with vlan `2021` during installation and have the following under `/oem/99_vlan-ifcfg.yaml`
+:::warning
+
+Workloads that rely on these interfaces will lose network connectivity.
+
+For more information, see [issue #7650](https://github.com/harvester/harvester/issues/7650).
+
+:::
+
+After upgrading to v1.6.x, perform the following steps:
+
+1. Verify VLANs attached to the `mgmt-br` and `mgmt-bo` by running the following command on management hosts:
+
+    ```
+    bridge vlan show
+    ```
+   The above outputs only the primary vlan part of `mgmt-br` and `mgmt-bo`
+
+1. Manually add the required secondary VLANs to the `mgmt-br` bridge and the `mgmt-bo` interface by adding the following commands to the `/oem/90_custom.yaml` file:
+
+    - `/etc/wicked/scripts/setup_bond.sh` section
+
+    ```
+    bridge vlan add vid <vlan-id> dev $INTERFACE
+    ```
+
+    - `/etc/wicked/scripts/setup_bridge.sh` section
+
+    ```
+    bridge vlan add vid <vlan-id> dev $INTERFACE self
+    bridge vlan add vid <vlan-id> dev mgmt-bo
+    ```
+
+    :::info important
+
+    You must include a separate command for each distinct VLAN ID. Ensure that the `vlan-id` placeholder is replaced with the actual ID.
+
+    :::
+
+1. Once the `/oem/90_custom.yaml` file is updated, reboot the management hosts.
+
+1. Verify that all the required VLANs were added by running the following command on the hosts:
+
+    ```
+    bridge vlan show
+    ```
+
+#### Upgrade Scenario Example
+
+In the following example, a v1.5.x cluster was initially installed with a [primary VLAN interface](../install/harvester-configuration.md#installmanagement_interface) (VLAN ID: `2021`). To add a secondary VLAN interface (VLAN ID: `2113`), the `/oem/99_vlan-ifcfg.yaml` file  was created on the management hosts with the following contents:
 
 ```
 stages:
@@ -179,19 +227,7 @@ stages:
             DEFROUTE='no'
 
 ```
-Users expect to create an additional vlan sub interface on mgmt interface `mgmt-br.2113` and assign IPv4 address and use it for L3 connectivity in addition to the primary `mgmt-br.2021` interface after upgrade to v1.6.x.
-The additional vlan sub interface is created, but `mgmt-br` bridge and `mgmt-bo` will no longer be part of vlan `2113` as after reboot only the primary `vlan-id` will be assigned to the `mgmt-br` bridge and `mgmt-bo` using `/oem/90_custom.yaml`.Starting from v1.6.0, only primary vlan will be added to `mgmt-br` bridge and `mgmt-bo` instead of all 2-4094 vlans.Due to this communication using secondary vlans on mgmt interface is affected.
-Users can check this info using `bridge vlan show` command on the host.
+The typical expectation is that an additional VLAN sub-interface is created on the `mgmt` interface (`mgmt-br.2113`) and assigned an IPv4 address. In addition, this sub-interface and the primary interface (`mgmt-br.2021`) are both expected to be used for L3 connectivity after the cluster is upgraded to v1.6.x.
 
-Starting from v1.6.0,Users have to explicitly add the secondary vlans required to the `mgmt-br` bridge and `mgmt-bo` using the following and repeat below for every secondary `vlan-id` or vlan range the user requires.
-
-Add the following under contents of /etc/wicked/scripts/setup_bond.sh in /oem/90_custom.yaml
-```
-bridge vlan add vid <vlan-id> dev $INTERFACE
-```
-
-Add the following under contents of /etc/wicked/scripts/setup_bridge.sh in /oem/90_custom.yaml
-```
-bridge vlan add vid <vlan-id> dev $INTERFACE self
-bridge vlan add vid <vlan-id> dev mgmt-bo
-```
+In actuality after upgrade to v1.6.0, however, the VLAN sub-interface is created but the secondary VLAN (VLAN ID: `2113`) is removed from the `mgmt-br` bridge and the `mgmt-bo` interface. After a reboot, only the primary VLAN ID is assigned to the `mgmt-br` bridge and the `mgmt-bo` interface (using the `/oem/90_custom.yaml` file).
+To mitigate the effects of this change, you must perform the workaround described in the previous section. This involves identifying secondary VLAN interfaces and then adding the necessary ones to the `mgmt-br` bridge and the `mgmt-bo` interface.
