Doc changes for modular upgrades in Bare Metal (#6905)

* Add Documentation for osImageURL field added to machine config for baremetal

Signed-off-by: Rahul Ganesh <rahulgab@amazon.com>

* Address comments on naming conventions

Signed-off-by: Rahul Ganesh <rahulgab@amazon.com>

* update docs to include os version upgrade messaging

Signed-off-by: Rahul Ganesh <rahulgab@amazon.com>

* make the worker node k8s version messaging clearer

Signed-off-by: Rahul Ganesh <rahulgab@amazon.com>

---------

Signed-off-by: Rahul Ganesh <rahulgab@amazon.com>
Co-authored-by: Rahul Ganesh <rahulgab@amazon.com>

docs/content/en/docs/clustermgmt/cluster-upgrades/baremetal-upgrades.md

@@ -170,8 +170,7 @@ spec:
       ...
 ```
 
->**_NOTE:_** If you have a custom machine image for your nodes in your cluster config yaml you may also need to update 
-your [`TinkerbellDatacenterConfig`]({{< relref "../../getting-started/baremetal/bare-spec/#tinkerbelldatacenterconfig-fields" >}}) with a new [`osImageURL`]({{< relref "../../getting-started/baremetal/bare-spec/#osimageurl" >}}).
+>**_NOTE:_** If you have a custom machine image for your nodes in your cluster config yaml or to upgrade a node or group of nodes to a new operating system version (ie. RHEL 8.7 to RHEL 8.8), you may also need to update your [`TinkerbellDatacenterConfig`]({{< relref "../../getting-started/baremetal/bare-spec/#tinkerbelldatacenterconfig-fields" >}}) or [`TinkerbellMachineConfig`]({{< relref "../../getting-started/baremetal/bare-spec/#tinkerbellmachineconfig-fields" >}}) with the new operating system image URL [`osImageURL`]({{< relref "../../getting-started/baremetal/bare-spec/#osimageurl" >}}). 
 
 and then you will run the [upgrade cluster command]({{< relref "baremetal-upgrades/#upgrade-cluster-command" >}}).
 
@@ -269,6 +268,7 @@ and then you will run the [upgrade cluster command]({{< relref "baremetal-upgrad
 
 `Cluster`:
 - `kubernetesVersion`
+- `workerNodeGroupConfigurations.kubernetesVersion`
 
 ### Advanced configuration for rolling upgrade
 

docs/content/en/docs/getting-started/baremetal/bare-spec.md

@@ -199,6 +199,11 @@ EKS Anywhere will add by default.
 Modifying the labels associated with a worker node group configuration will cause new nodes to be rolled out, replacing
 the existing nodes associated with the configuration.
 
+### workerNodeGroupConfigurations.kubernetesVersion
+The Kubernetes version you want to use for this worker node group. [Supported values]({{< relref "../../concepts/support-versions/#kubernetes-support" >}}): `1.28`, `1.27`, `1.26`, `1.25`, `1.24`
+
+Must be less than or equal to the cluster `kubernetesVersion` defined at the root level of the cluster spec. The worker node kubernetesVersion must be no more than two minor Kubernetes versions lower than the cluster control plane's Kubernetes version. Removing `workerNodeGroupConfiguration.kubernetesVersion` will trigger an upgrade of the node group to the `kubernetesVersion` defined at the root level of the cluster spec.
+
 ## TinkerbellDatacenterConfig Fields
 
 ### tinkerbellIP
@@ -208,8 +213,7 @@ Once the Tinkerbell services move from the Admin machine to run on the target cl
 When separate management and workload clusters are supported in Bare Metal, the IP address becomes a necessity.
 
 ### osImageURL
-Optional field to replace the default Bottlerocket operating system. EKS Anywhere can only auto-import Bottlerocket. In order to use Ubuntu or Redhat see [building baremetal node images]({{< relref "../../osmgmt/artifacts/#build-bare-metal-node-images" >}})
-to learn more on building and using Ubuntu with an EKS Anywhere cluster. This field is also useful if you want to provide a customized operating system image or simply host the standard image locally.
+Optional field to replace the default Bottlerocket operating system. EKS Anywhere can only auto-import Bottlerocket. In order to use Ubuntu or RHEL see [building baremetal node images]({{< relref "../../osmgmt/artifacts/#build-bare-metal-node-images" >}}). This field is also useful if you want to provide a customized operating system image or simply host the standard image locally. To upgrade a node or group of nodes to a new operating system version (ie. RHEL 8.7 to RHEL 8.8), modify this field to point to the new operating system image URL and run [upgrade cluster command]({{< relref "../../clustermgmt/cluster-upgrades/baremetal-upgrades/#upgrade-cluster-command" >}}).
 
 ### hookImagesURLPath
 Optional field to replace the HookOS image.
@@ -261,6 +265,12 @@ spec:
 ### osFamily (required)
 Operating system on the machine. Permitted values: `bottlerocket`, `ubuntu`, `redhat` (Default: `bottlerocket`).
 
+### osImageURL (optional)
+Optional field to replace the default Bottlerocket operating system. EKS Anywhere can only auto-import Bottlerocket. In order to use Ubuntu or RHEL see [building baremetal node images]({{< relref "../../osmgmt/artifacts/#build-bare-metal-node-images" >}}). This field is also useful if you want to provide a customized operating system image or simply host the standard image locally. To upgrade a node or group of nodes to a new operating system version (ie. RHEL 8.7 to RHEL 8.8), modify this field to point to the new operating system image URL and run [upgrade cluster command]({{< relref "../../clustermgmt/cluster-upgrades/baremetal-upgrades/#upgrade-cluster-command" >}}).
+
+>**_NOTE:_** If specified for a single `TinkerbellMachineConfig`, osImageURL has to be specified for all the `TinkerbellMachineConfigs`.
+osImageURL field cannot be specified both in the `TinkerbellDatacenterConfig` and `TinkerbellMachineConfig` objects.
+
 ### templateRef (optional)
 Identifies the template that defines the actions that will be applied to the TinkerbellMachineConfig.
 See TinkerbellTemplateConfig fields below.

docs/content/en/docs/getting-started/vsphere/vsphere-spec.md

@@ -209,7 +209,7 @@ the existing nodes associated with the configuration.
 ### workerNodeGroupConfigurations.kubernetesVersion
 The Kubernetes version you want to use for this worker node group. [Supported values]({{< relref "../../concepts/support-versions/#kubernetes-support" >}}): `1.28`, `1.27`, `1.26`, `1.25`, `1.24`
 
-Must be less than or equal the cluster `kubernetesVersion`. There can only be a skew of two minor versions between the control plane and each worker node. Removing `workerNodeGroupConfiguration.kubernetesVersion` will trigger an upgrade to that node group to upgrade to the root level kubernetesVersion.
+Must be less than or equal to the cluster `kubernetesVersion` defined at the root level of the cluster spec. The worker node kubernetesVersion must be no more than two minor Kubernetes versions lower than the cluster control plane's Kubernetes version. Removing `workerNodeGroupConfiguration.kubernetesVersion` will trigger an upgrade of the node group to the `kubernetesVersion` defined at the root level of the cluster spec.
 
 ### externalEtcdConfiguration.count
 Number of etcd members