Skip to content

Commit 1b5d187

Browse files
benradstonebenradstone
authored
DOC-2311 - AL2 deprecation notice and migration guide for EKS clusters (#8374)
* docs: AL2 migration guide for EKS clusters * docs: address Vale comment * docs: additional steps for troubleshooting * docs: Apply suggestion from code review * ci: auto-formatting prettier issues * docs: Apply suggestion from code review (part 2) * ci: auto-formatting prettier issues * docs: add release note for deprecation notice * docs: Set removal date to April 4th 2026 * docs: clarify disablement and removal guidance * docs: further clarification on disablement and removal * docs: final hopeful date fixes
1 parent 5813e44 commit 1b5d187

File tree

4 files changed

+207
-4
lines changed

4 files changed

+207
-4
lines changed

‎docs/docs-content/clusters/public-cloud/aws/eks.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,18 @@ sidebar_position: 30
1111
Palette supports creating and managing Amazon Web Services (AWS) Elastic Kubernetes Service (EKS) clusters deployed to
1212
an AWS account. This section guides you on how to create an EKS cluster in AWS that Palette manages.
1313

14+
:::warning
15+
16+
[EKS-optimized Amazon Linux 2 (AL2) AMIs](https://docs.aws.amazon.com/eks/latest/userguide/eks-ami-deprecation-faqs.html)
17+
will be disabled in Palette from January 10, 2026, and removed on April 4, 2026. When disabled, you will no longer be
18+
able to select the AL2 AMIs for EKS worker nodes in Palette for new clusters. For existing clusters, you must create new
19+
worker nodes using AL2023 AMIs. Existing AL2 AMI worker nodes will no longer receive bug fixes or security patches after
20+
the removal date. Refer to our
21+
[Scenario - Unable to Upgrade EKS Worker Nodes from AL2 to AL2023](../../../troubleshooting/cluster-deployment.md#scenario---unable-to-upgrade-eks-worker-nodes-from-al2-to-al2023)
22+
guide for help with migrating workloads.
23+
24+
:::
25+
1426
## Prerequisites
1527

1628
- Access to an AWS cloud account.

‎docs/docs-content/release-notes/announcements.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -31,10 +31,11 @@ for the changes in your environment.
3131
The table below lists the upcoming deprecations in Palette and Palette VerteX. Review the information to below and take
3232
necessary actions to avoid any disruptions in your environment.
3333

34-
| Change | Target Removal Date | Published Date |
35-
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | -------------- |
36-
| The [Palette Edge CLI](../downloads/cli-tools.md#palette-edge-cli) is deprecated and will be removed in a future release. We recommend using the [Palette CLI](../automation/palette-cli/palette-cli.md) for the creation and management of content bundles. Refer to the [Build Content Bundle](../clusters/edge/edgeforge-workflow/palette-canvos/build-content-bundle.md) guide for further information. | _To be announced_ | May 25, 2025 |
37-
| The `stylus.installationMode` [Edge Installer Configuration](../clusters/edge/edge-configuration/installer-reference.md) flag is deprecated. We recommend using the `stylus.managementMode` flag instead, which has two allowed values: `central`, which means the Edge host is connected to Palette, and `local`, which means the Edge host has no connection to a Palette instance. Refer to the [Prepare User Data](../clusters/edge/edgeforge-workflow/prepare-user-data.md) guide for further information. | December 6, 2025 | May 25, 2025 |
34+
| Change | Target Removal Date | Published Date |
35+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- | ---------------- |
36+
| [EKS-optimized Amazon Linux 2 (AL2) AMIs](https://docs.aws.amazon.com/eks/latest/userguide/eks-ami-deprecation-faqs.html) will be disabled in Palette from January 10, 2026 and removed on 4 April, 2026. When disabled, you will no longer be able to select the AL2 AMIs for EKS worker nodes in Palette for new clusters. For existing clusters, you must create new worker nodes using AL2023 AMIs. Existing AL2 AMI worker nodes will no longer receive bug fixes or security patches after the removal date. Refer to our [Scenario - Unable to Upgrade EKS Worker Nodes from AL2 to AL2023](../troubleshooting/cluster-deployment.md#scenario---unable-to-upgrade-eks-worker-nodes-from-al2-to-al2023) guide for help with migrating workloads. | April 4, 2026 | October 18, 2025 |
37+
| The [Palette Edge CLI](../downloads/cli-tools.md#palette-edge-cli) is deprecated and will be removed in a future release. We recommend using the [Palette CLI](../automation/palette-cli/palette-cli.md) for the creation and management of content bundles. Refer to the [Build Content Bundle](../clusters/edge/edgeforge-workflow/palette-canvos/build-content-bundle.md) guide for further information. | _To be announced_ | May 25, 2025 |
38+
| The `stylus.installationMode` [Edge Installer Configuration](../clusters/edge/edge-configuration/installer-reference.md) flag is deprecated. We recommend using the `stylus.managementMode` flag instead, which has two allowed values: `central`, which means the Edge host is connected to Palette, and `local`, which means the Edge host has no connection to a Palette instance. Refer to the [Prepare User Data](../clusters/edge/edgeforge-workflow/prepare-user-data.md) guide for further information. | December 6, 2025 | May 25, 2025 |
3839

3940
## Removals
4041

‎docs/docs-content/release-notes/release-notes.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,14 @@ tags: ["release-notes"]
4343

4444
#### Deprecations and Removals
4545

46+
- [EKS-optimized Amazon Linux 2 (AL2) AMIs](https://docs.aws.amazon.com/eks/latest/userguide/eks-ami-deprecation-faqs.html)
47+
will be disabled in Palette from January 10, 2026 and removed on April 4, 2026. When disabled, you will no longer be
48+
able to select the AL2 AMIs for EKS worker nodes in Palette for new clusters. For existing clusters, you must create
49+
new worker nodes using AL2023 AMIs. Existing AL2 AMI worker nodes will no longer receive bug fixes or security patches
50+
after the removal date. Refer to our
51+
[Scenario - Unable to Upgrade EKS Worker Nodes from AL2 to AL2023](../troubleshooting/cluster-deployment.md#scenario---unable-to-upgrade-eks-worker-nodes-from-al2-to-al2023)
52+
guide for help with migrating workloads.
53+
4654
### Edge
4755

4856
#### Features

‎docs/docs-content/troubleshooting/cluster-deployment.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,188 @@ tags: ["troubleshooting", "cluster-deployment"]
1010

1111
The following steps will help you troubleshoot errors in the event issues arise while deploying a cluster.
1212

13+
## Scenario - Unable to Upgrade EKS Worker Nodes from AL2 to AL2023
14+
15+
AWS does not provide a direct upgrade path from Amazon Linux 2 (AL2) to Amazon Linux 2023 (AL2023) for EKS worker nodes.
16+
This is due to significant changes between AL2 and AL2023, including differences in worker node initialization and
17+
bootstrapping prior to joining an EKS cluster. Refer to the
18+
[AWS documentation](https://docs.aws.amazon.com/eks/latest/userguide/al2023.html) for more details.
19+
20+
You can use the following debug steps for existing clusters that were deployed using AL2 worker nodes and need to be
21+
upgraded to AL2023 worker nodes.
22+
23+
:::info
24+
25+
After January 10, 2026, you can only create node pools with the AL2023 AMI type in Palette. If AL2 is needed, consider
26+
using custom AMIs. Ensure you have accounted for this change in any of your automation, such as Terraform, API, etc.
27+
28+
:::
29+
30+
### Debug Steps
31+
32+
1. Check the
33+
[Compatibility Requirements](https://docs.aws.amazon.com/eks/latest/userguide/al2023.html#al2023-compatibility-requirements)
34+
for AL2023 to ensure your applications run correctly on AL2023.
35+
36+
If your applications are not ready to run on AL2023, continue with the following steps but use a custom AL2 AMI
37+
instead of AL2023.
38+
39+
2. Log in to [Palette](https://console.spectrocloud.com/).
40+
41+
3. Ensure you are in the correct project scope.
42+
43+
4. From the left main menu, click **Profiles** and select the profile used to deploy your EKS cluster.
44+
45+
5. [Create a new version of the cluster profile](../profiles/cluster-profiles/modify-cluster-profiles/version-cluster-profile.md).
46+
47+
6. Select the **Kubernetes** layer of your cluster profile.
48+
49+
7. On the **Edit Pack** page, select **Values** under **Pack Details**.
50+
51+
8. Add your IRSA roles to the `managedControlPlane.irsaRoles` and `managedMachinePool.roleAdditionalPolicies` sections
52+
if they are not already configured.
53+
54+
```yaml hideClipboard title="Example configuration"
55+
managedControlPlane:
56+
...
57+
irsaRoles:
58+
- name: "{{.spectro.system.cluster.name}}-irsa-cni"
59+
policies:
60+
- arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy
61+
serviceAccount:
62+
name: aws-node
63+
namespace: kube-system
64+
- name: "{{.spectro.system.cluster.name}}-irsa-csi" # optional, defaults to audience sts.amazonaws.com
65+
policies:
66+
- arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy
67+
...
68+
managedMachinePool:
69+
...
70+
roleAdditionalPolicies:
71+
- "arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy"
72+
```
73+
74+
Refer to the
75+
[Scenario - PV/PVC Stuck in Pending Status for EKS Cluster Using AL2023 AMI](#scenario---pvpvc-stuck-in-pending-status-for-eks-cluster-using-al2023-ami)
76+
section for further information on why it is necessary to configure IRSA roles for AL2023.
77+
78+
9. Click **Confirm Updates** after editing.
79+
80+
10. Select the **Storage** layer of your cluster profile.
81+
82+
11. On the **Edit Pack** page, select **Values** under **Pack Details**.
83+
84+
12. Use the YAML editor to add an IAM role ARN annotation to the AWS EBS CSI Driver so that the IRSA role is correctly
85+
referenced. Replace `<aws-account-id>` with your AWS account ID.
86+
87+
```yaml hideClipboard title="Example configuration" {12}
88+
charts:
89+
...
90+
aws-ebs-csi-driver:
91+
...
92+
controller:
93+
...
94+
serviceAccount:
95+
# A service account will be created for you if set to true. Set to false if you want to use your own.
96+
create: true
97+
name: ebs-csi-controller-sa
98+
annotations: {
99+
"eks.amazonaws.com/role-arn":"arn:aws:iam::<aws-account-id>:role/{{.spectro.system.cluster.name}}-irsa-csi"
100+
}
101+
## Enable if EKS IAM for SA is used
102+
# eks.amazonaws.com/role-arn: arn:<partition>:iam::<account>:role/ebs-csi-role
103+
automountServiceAccountToken: true
104+
```
105+
106+
13. Click **Confirm Updates** after editing.
107+
108+
14. Click **Save Changes** on the cluster profile page.
109+
110+
15. From the left main menu, click **Clusters** and select your EKS cluster.
111+
112+
16. Select the **Profile** tab.
113+
114+
17. Click the version drop-down for **INFRASTRUCTURE LAYERS** and select the new version of the cluster profile that you
115+
created with these changes.
116+
117+
18. Click **Review & Save**. In the pop-up window, click **Review changes in Editor**.
118+
119+
19. Review your changes and click **Apply Changes** when ready.
120+
121+
20. Select the **Nodes** tab.
122+
123+
21. Click **New Node Pool**.
124+
125+
22. Fill out the input fields in the **Add node pool** page as per your requirements.
126+
127+
Ensure that you select an **Amazon Linux 2023** AMI type, or, if you are using a custom AL2 AMI, select **Custom
128+
AMI** and provide the AMI ID.
129+
130+
23. Click **Confirm** to create the new node pool.
131+
132+
24. Wait for the new nodes to be **Healthy** (green tick) in the **Health** column and show a **Status** of **Running**.
133+
134+
25. Repeat steps 20-24 to create additional AL2023 node pools as needed. Ensure that the total number of nodes in the
135+
AL2023 node pools meets your requirements to replace the AL2 node pools.
136+
137+
26. On the **Nodes** tab, click the **Edit** option for your existing AL2 node pool.
138+
139+
27. Click the **Add New Taint** option and add a
140+
[taint](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) to the AL2 node pool. Use the
141+
`NoExecute` effect to evict workloads from the AL2 nodes.
142+
143+
Example:
144+
145+
- **Key** = `migrate-to-al2023`
146+
- **Value** = `true`
147+
- **Effect** = `NoExecute`
148+
149+
28. Click **Confirm** to update the AL2 node pool.
150+
151+
29. Wait for the workloads to be evicted from the AL2 nodes and rescheduled on the AL2023 nodes.
152+
153+
You can check for running pods on the AL2 nodes by issuing the following command. Replace `<al2-node-identifier>`
154+
with part of the name of one of your AL2 nodes.
155+
156+
```bash title="Example command"
157+
kubectl get pods --all-namespaces --output wide --field-selector spec.nodeName=<al2-node-identifier>
158+
```
159+
160+
The AL2 nodes will display only system pods, such as `aws-node`, `ebs-csi-controller`, `ebs-csi-node`, `kube-proxy`,
161+
and potentially `palette-webhook`.
162+
163+
```shell hideClipboard title="Example output from AL2 node"
164+
NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
165+
kube-system aws-node-rvkbv 2/2 Running 0 29m 10.0.206.110 ip-10-11-12-13.ec2.internal <none> <none>
166+
kube-system ebs-csi-controller-6f6f7d776b-q7hlj 5/5 Running 0 58m 10.0.196.103 ip-10-11-12-13.ec2.internal <none> <none>
167+
kube-system ebs-csi-node-tbm7t 3/3 Running 0 29m 10.0.215.130 ip-10-11-12-13.ec2.internal <none> <none>
168+
kube-system kube-proxy-xqm5w 1/1 Running 0 29m 10.0.206.110 ip-10-11-12-13.ec2.internal <none> <none>
169+
palette-system palette-webhook-86c7b5f99d-tdcf7 1/1 Running 0 29m 10.0.205.155 ip-10-11-12-13.ec2.internal <none> <none>
170+
```
171+
172+
You can compare this output with the output from the same command issued for one of your AL2023 nodes to confirm
173+
that the workloads have been successfully migrated.
174+
175+
```shell hideClipboard title="Example output from AL2023 node"
176+
NAMESPACE NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
177+
capi-webhook-system capa-controller-manager-59c947b948-lwwrv 1/1 Running 0 8m22s 10.0.201.130 ip-20-21-22-23.ec2.internal <none> <none>
178+
capi-webhook-system capi-controller-manager-5455d67696-pv69l 1/1 Running 0 8m21s 10.0.215.178 ip-20-21-22-23.ec2.internal <none> <none>
179+
capi-webhook-system capi-kubeadm-control-plane-controller-manager-67b7d996cd-96lqp 1/1 Running 0 8m21s 10.0.252.246 ip-20-21-22-23.ec2.internal <none> <none>
180+
cert-manager cert-manager-webhook-6b5c469577-wwsqb 1/1 Running 0 8m22s 10.0.234.189 ip-20-21-22-23.ec2.internal <none> <none>
181+
cluster-68ee17be1ccd1304cf843c0f cluster-management-agent-645f84964f-sw9n4 1/1 Running 0 8m21s 10.0.212.43 ip-20-21-22-23.ec2.internal <none> <none>
182+
cluster-68ee17be1ccd1304cf843c0f metrics-server-56594bcd99-mkjlp 1/1 Running 0 8m17s 10.0.209.82 ip-20-21-22-23.ec2.internal <none> <none>
183+
cluster-68ee17be1ccd1304cf843c0f palette-controller-manager-68c698776c-xjnn4 3/3 Running 0 8m22s 10.0.204.59 ip-20-21-22-23.ec2.internal <none> <none>
184+
kube-system aws-node-77hv6 2/2 Running 0 43m 10.0.200.120 ip-20-21-22-23.ec2.internal <none> <none>
185+
kube-system coredns-6b9575c64c-trp5v 1/1 Running 0 8m22s 10.0.204.97 ip-20-21-22-23.ec2.internal <none> <none>
186+
kube-system ebs-csi-controller-6f6f7d776b-q7hlj 5/5 Running 0 42m 10.0.196.103 ip-20-21-22-23.ec2.internal <none> <none>
187+
kube-system ebs-csi-node-mjth6 3/3 Running 0 42m 10.0.216.41 ip-20-21-22-23.ec2.internal <none> <none>
188+
kube-system kube-proxy-544fg 1/1 Running 0 40m 10.0.200.120 ip-20-21-22-23.ec2.internal <none> <none>
189+
palette-system palette-webhook-86c7b5f99d-f8n5v 1/1 Running 0 40m 10.0.206.77 ip-20-21-22-23.ec2.internal <none> <none>
190+
```
191+
192+
30. Once all workloads have been successfully migrated to the AL2023 nodes, you can
193+
[delete](../clusters/cluster-management/node-pool.md#delete-a-node-pool) the AL2 node pools.
194+
13195
## Scenario - PV/PVC Stuck in Pending Status for EKS Cluster Using AL2023 AMI
14196

15197
After deploying an Amazon EKS cluster using an

0 commit comments

Comments
 (0)