docs: Clarify baremetal network requirements and kubectl capabilities (#10429)

- Qualify L2 network as network/PXE boot only, not required for ISO boot
- Clarify DHCP only needed for network/PXE boot mode
- Add TinkerbellIP vs Control Plane Endpoint explanation
- Clarify kubectl works for management and workload cluster operations
- Add hardware CSV operational guidance (when to use CSV vs kubectl)
- Add cross-references between related documentation

These changes address common customer confusion about network requirements
for different boot modes and the scope of kubectl usage for cluster
lifecycle management.

Author: rahulbabu95

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

@@ -65,7 +65,7 @@ If you don't have any available hardware that match this requirement in the clus
     ```
     As noted earlier, adding the `--kubeconfig` option tells `eksctl` to use the management cluster identified by that kubeconfig file to create a different workload cluster.
 
-2. **kubectl CLI**: The cluster lifecycle feature lets you use kubectl to talk to the Kubernetes API to upgrade a workload cluster. To use kubectl, run:
+2. **kubectl CLI**: The cluster lifecycle feature lets you use kubectl to talk to the Kubernetes API to scale a workload cluster. kubectl can also be used for management cluster scaling, except when upgrading the EKS Anywhere CLI version which requires `eksctl anywhere upgrade`. To use kubectl, run:
      ```bash
      kubectl apply -f eksa-w01-cluster.yaml --kubeconfig mgmt/mgmt-eks-a-cluster.kubeconfig
      ```

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

@@ -136,9 +136,9 @@ and then you will run the [upgrade cluster command]({{< relref "baremetal-upgrad
 
 
 #### Upgrade cluster command
-* **kubectl CLI**: The cluster lifecycle feature lets you use kubectl to talk to the Kubernetes API to upgrade a workload cluster. To use kubectl, run:
+* **kubectl CLI**: The cluster lifecycle feature lets you use kubectl to talk to the Kubernetes API to upgrade a workload cluster. kubectl can also be used for management cluster upgrades (Kubernetes version, scaling, configuration changes), except when upgrading the EKS Anywhere CLI version which requires `eksctl anywhere upgrade`. To use kubectl, run:
    ```bash
-   kubectl apply -f eksa-w01-cluster.yaml 
+   kubectl apply -f eksa-w01-cluster.yaml
   --kubeconfig mgmt/mgmt-eks-a-cluster.kubeconfig
    ```
 

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

@@ -25,12 +25,30 @@ Once the hardware is in place, you need to:
 
 ## Prepare hardware inventory
 Create a CSV file to provide information about all physical machines that you are ready to add to your target Bare Metal cluster.
-This file will be used:
 
-* When you generate the hardware file to be included in the cluster creation process described in the Create Bare Metal production cluster Getting Started guide.
-* To provide information that is passed to each machine from the Tinkerbell DHCP server when the machine is initially network booted.
+{{% alert title="Hardware CSV vs kubectl: When to Use Each" color="primary" %}}
+**Hardware CSV** creates the initial hardware catalog (Hardware objects, BMC Machines, credentials).
 
-**NOTE**:While using kubectl, GitOps and Terraform for workload cluster creation, please make sure to refer [this]({{< relref "./baremetal-getstarted/#create-separate-workload-clusters" >}}) section.
+**Use hardware CSV for**:
+- Initial cluster creation
+- Adding new hardware when insufficient hardware available for scaling/upgrades
+
+**Use kubectl for hardware management**:
+- Adding hardware after initial creation: `eksctl anywhere generate hardware -z hardware.csv > hardware.yaml && kubectl apply -f hardware.yaml`
+
+**For cluster operations (scaling, upgrades)**:
+- Update `count` in cluster specification
+- System automatically selects from available hardware (those without `ownerName` label)
+- If insufficient hardware: Add more via hardware CSV with `--hardware-csv` flag or kubectl apply, then perform operation
+
+**Do NOT use CSV for**:
+- Removing hardware from cluster (use CAPI machine delete annotations)
+- Trying to force specific hardware selection during operations (system auto-selects based on availability)
+
+See [Scale Bare Metal Cluster]({{< relref "../../clustermgmt/cluster-scale/baremetal-scale" >}}) for operational examples.
+{{% /alert %}}
+
+**NOTE**: While using kubectl, GitOps and Terraform for workload cluster creation, please make sure to refer to [this section]({{< relref "./baremetal-getstarted/#create-separate-workload-clusters" >}}).
 
 The following is an example of an EKS Anywhere Bare Metal hardware CSV file:
 

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

@@ -45,17 +45,19 @@ When upgrading without an extra machine, keep in mind that your control plane an
 
 Each machine should include the following features:
 
-* Network Interface Cards: at least one NIC is required. It must be capable of network booting.
+* Network Interface Cards: at least one NIC is required. For network/PXE boot mode, it must be capable of network booting. See [Boot Modes]({{< relref "customize/bare-metal-boot-modes" >}}) for boot configuration options.
 
 * BMC integration (recommended): an IPMI or Redfish implementation (such a Dell iDRAC, RedFish-compatible, legacy or HP iLO) on the computer's motherboard or on a separate expansion card. This feature is used to allow remote management of the machine, such as turning the machine on and off.
 
 > **_NOTE:_** BMC integration is not required for an EKS Anywhere cluster. However, without BMC integration, upgrades are not supported and you will have to physically turn machines off and on when appropriate.
 
 Here are other network requirements:
 
-* All EKS Anywhere machines, including the Admin, control plane and worker machines, must be on the same layer 2 network and have network connectivity to the BMC (IPMI, Redfish, and so on).
+* **For network/PXE boot mode** (default): All EKS Anywhere machines, including the Admin, control plane and worker machines, must be on the same layer 2 network and have network connectivity to the BMC (IPMI, Redfish, and so on).
 
-* You must be able to run DHCP on the control plane/worker machine network.
+  **For ISO boot mode**: Layer 2 network connectivity is not required. Machines only need Layer 3 (routable) connectivity to the management cluster and BMC access for virtual media mounting. See [Boot Modes]({{< relref "customize/bare-metal-boot-modes" >}}) for details on boot mode options.
+
+* **For network/PXE boot mode**: You must be able to run DHCP on the control plane/worker machine network. DHCP is not required for ISO boot mode.
 
 > **_NOTE:_** If you have another DHCP service running on the network, you need to prevent it from interfering with the EKS Anywhere DHCP service. You can do that by configuring the other DHCP service to explicitly block all MAC addresses and exclude all IP addresses that you plan to use with your EKS Anywhere clusters.
 
@@ -77,14 +79,33 @@ Here are other network requirements:
 
   * `sts.amazonaws.com`: only if AWS IAM Authenticator is enabled
 
-* Two IP addresses routable from the cluster, but excluded from DHCP offering. One IP address is to be used as the Control Plane Endpoint IP. The other is for the Tinkerbell IP address on the target cluster. Below are some suggestions to ensure that these IP addresses are never handed out by your DHCP server. You may need to contact your network engineer to manage these addresses.
+* Two IP addresses routable from the cluster, but excluded from DHCP offering:
+
+  {{% alert title="Understanding the Two Required IPs" color="primary" %}}
+  **Control Plane Endpoint IP** (`controlPlaneConfiguration.endpoint.host`):
+  - Virtual IP for the Kubernetes API server
+  - Managed by kube-vip on control plane nodes
+  - Used by kubectl and all Kubernetes clients
+  - Must be reachable from admin machine and all cluster nodes
+
+  **Tinkerbell IP** (`tinkerbellIP`):
+  - Virtual IP for Tinkerbell stack services (Smee, Tink-server, Hegel)
+  - Used during node provisioning and lifecycle operations
+  - Must be reachable from all machines being provisioned
+  - On workload clusters, should be the same as the management cluster's Tinkerbell IP
+  
+  **Both IPs must be**:
+  - Outside the DHCP range
+  - Routable from the cluster subnet
+  - Not assigned to any physical interface
+  {{% /alert %}}
+
+  Below are some suggestions to ensure that these IP addresses are never handed out by your DHCP server. You may need to contact your network engineer to manage these addresses:
 
   * Pick IP addresses reachable from the cluster subnet that are excluded from the DHCP range or
 
   * Create an IP reservation for these addresses on your DHCP server. This is usually accomplished by adding a dummy mapping of this IP address to a non-existent mac address.
 
-> **_NOTE:_** When you set up your cluster configuration YAML file, the endpoint and Tinkerbell addresses are set in the `controlPlaneConfiguration.endpoint.host` and `tinkerbellIP` fields, respectively.
-
 * Ports must be open to the Admin machine and cluster machines as described in the [Cluster Networking documentation]({{< relref "../ports" >}}).
 
 ## Validated hardware

docs/content/en/docs/getting-started/baremetal/baremetal-getstarted.md

@@ -184,7 +184,7 @@ Follow these steps if you want to use your initial cluster to create and manage
      ```
      As noted earlier, adding the `--kubeconfig` option tells `eksctl` to use the management cluster identified by that kubeconfig file to create a different workload cluster.
 
-   * **kubectl CLI**: The cluster lifecycle feature lets you use kubectl to talks to the Kubernetes API to create a workload cluster. To use kubectl, run:
+   * **kubectl CLI**: The cluster lifecycle feature lets you use kubectl to talk to the Kubernetes API to create a workload cluster. kubectl can also be used for management cluster operations (scaling, Kubernetes version upgrades), except when upgrading the EKS Anywhere CLI version which requires `eksctl anywhere upgrade`. To use kubectl, run:
       ```bash
       kubectl apply -f eksa-w01-cluster.yaml --kubeconfig mgmt/mgmt-eks-a-cluster.kubeconfig
       ```