docs: adds documentation about nodeadm

Author: faiq

docs/book/src/topics/eks/cluster-upgrades.md

@@ -4,4 +4,81 @@
 
 Upgrading the Kubernetes version of the control plane is supported by the provider. To perform an upgrade you need to update the `version` in the spec of the `AWSManagedControlPlane`. Once the version has changed the provider will handle the upgrade for you.
 
-You can only upgrade a EKS cluster by 1 minor version at a time. If you attempt to upgrade the version by more then 1 minor version the provider will ensure the upgrade is done in multiple steps of 1 minor version. For example upgrading from v1.15 to v1.17 would result in your cluster being upgraded v1.15 -> v1.16 first and then v1.16 to v1.17.
+You can only upgrade a EKS cluster by 1 minor version at a time. If you attempt to upgrade the version by more then 1 minor version the provider will ensure the upgrade is done in multiple steps of 1 minor version. For example upgrading from v1.15 to v1.17 would result in your cluster being upgraded v1.15 -> v1.16 first and then v1.16 to v1.17.
+
+## Upgrading Nodes from AL2 (EKSConfig) to AL2023 (NodeadmConfig)
+
+Amazon Linux 2 (AL2) AMIs are only supported up to Kubernetes v1.32. To upgrade cluster nodes to v1.33 or newer, you **must** migrate them to Amazon Linux 2023 (AL2023) AMIs. This migration also requires changing the bootstrap provider from `EKSConfig` to the new `NodeadmConfig`.
+
+The upgrade process follows the standard Cluster API rolling update strategy. You will create a new bootstrap template (using `NodeadmConfigTemplate`) and update your `MachineDeployment` or `MachinePool` to reference it, along with the new Kubernetes version and an AL2023-based AMI.
+
+### MachineDeployment Upgrade Example
+
+Here is an example of upgrading a `MachineDeployment` from Kubernetes v1.32 (using `EKSConfig`) to v1.33 (using `NodeadmConfig`).
+
+**Before (v1.32 with `EKSConfigTemplate`):**
+
+```yaml
+apiVersion: bootstrap.cluster.x-k8s.io/v1beta2
+kind: EKSConfigTemplate
+metadata:
+  name: default132
+spec:
+  template:
+    spec:
+      postBootstrapCommands:
+        - "echo \"bye world\""
+---
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: MachineDeployment
+metadata:
+  name: default
+spec:
+  clusterName: default
+  template:
+    spec:
+      bootstrap:
+        configRef:
+          apiVersion: bootstrap.cluster.x-k8s.io/v1beta2
+          kind: EKSConfigTemplate
+          name: default132
+      infrastructureRef:
+        kind: AWSMachineTemplate
+        name: default132
+      version: v1.32.0
+```
+
+After (v1.33 with NodeadmConfigTemplate):
+
+A new NodeadmConfigTemplate is created, and the MachineDeployment is updated to reference it and the new version.
+YAML
+
+```yaml
+apiVersion: bootstrap.cluster.x-k8s.io/v1beta2
+kind: NodeadmConfigTemplate
+metadata:
+  name: default
+spec:
+  template:
+    spec:
+      preNodeadmCommands:
+        - "echo \"hello world\""
+---
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: MachineDeployment
+metadata:
+  name: default
+spec:
+  clusterName: default
+  template:
+    spec:
+      bootstrap:
+        configRef:
+          apiVersion: bootstrap.cluster.x-k8s.io/v1beta2
+          kind: NodeadmConfigTemplate
+          name: default
+      infrastructureRef:
+        kind: AWSMachineTemplate
+        name: default
+      version: v1.33.0
+```

docs/book/src/topics/eks/creating-a-cluster.md

@@ -17,6 +17,61 @@ NOTE: When creating an EKS cluster only the **MAJOR.MINOR** of the `-kubernetes-
 By default CAPA relies on the default EKS cluster upgrade policy, which at the moment of writing is EXTENDED support.
 See more info about [cluster upgrade policy](https://docs.aws.amazon.com/eks/latest/userguide/view-upgrade-policy.html)
 
+## Choosing a Bootstrap Provider: EKSConfig vs. NodeadmConfig
+
+With the introduction of Amazon Linux 2023 (AL2023), the bootstrapping method for EKS nodes has changed. Cluster API Provider AWS (CAPA) supports two bootstrap providers for EKS:
+
+1.  **`EKSConfig`**: The original bootstrap provider. It uses the legacy `bootstrap.sh` script and is intended for use with **Amazon Linux 2 (AL2)** AMIs.
+2.  **`NodeadmConfig`**: The new bootstrap provider. It uses the modern `nodeadm` tool and is **required** for **Amazon Linux 2023 (AL2023)** AMIs.
+
+### When to use which provider
+
+The provider you must use depends on the Amazon Machine Image (AMI) and Kubernetes version you are targeting. Amazon Linux 2 AMIs are only supported for Kubernetes v1.32 and older.
+
+| Bootstrap Provider | AMI Type | Kubernetes Version |
+| --- | --- | --- |
+| `EKSConfig` | Amazon Linux 2 (AL2) | $\le$ v1.32 |
+| `NodeadmConfig` | Amazon Linux 2023 (AL2023) | $\ge$ v1.33 |
+
+When you generate a cluster, you will need to ensure your `MachineDeployment` or `MachinePool` references the correct bootstrap template `kind`.
+
+**For AL2 / K8s $\le$ v1.32, use `EKSConfigTemplate`:**
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: MachineDeployment
+metadata:
+  name: default
+spec:
+  template:
+    spec:
+      bootstrap:
+        configRef:
+          apiVersion: bootstrap.cluster.x-k8s.io/v1beta2
+          kind: EKSConfigTemplate  # <-- Uses bootstrap.sh
+          name: default-132
+      version: v1.32.0
+```
+
+### Secrets Manager
+
+Amazon Linux 2023 does not have the proper tooling to use the secrets manager flow for bootstrapping. Therefore, whenever creating `AWSMachineTemplate` objects  `insecureSkipSecretsManager` must be set to false
+
+```yaml
+apiVersion: infrastructure.cluster.x-k8s.io/v1beta2
+kind: AWSMachineTemplate
+metadata:
+  name: default
+spec:
+  template:
+    spec:
+      cloudInit:
+        insecureSkipSecretsManager: true
+      ami:
+        eksLookupType: AmazonLinux2023
+      iamInstanceProfile: nodes.cluster-api-provider-aws.sigs.k8s.io
+      instanceType: m5a.16xlarge
+```
+
 ## Kubeconfig
 
 When creating an EKS cluster 2 kubeconfigs are generated and stored as secrets in the management cluster. This is different to when you create a non-managed cluster using the AWS provider.