AWS eks documentation change
Summary
Added 'Summary' section outlining upgrade process steps, updated CLI command syntax/versions, added documentation about cluster insights for upgrade readiness checks, and noted temporary rollback of enforced upgrade insights
Security assessment
The change adds documentation about Amazon EKS cluster insights that scan for deprecated API usage and upgrade-impacting issues, which helps prevent security risks from outdated APIs. However, there is no explicit mention of addressing an active security vulnerability. The temporary rollback note refers to a feature enforcement change without concrete evidence of a security incident.
Diff
diff --git a/eks/latest/userguide/update-cluster.md b/eks/latest/userguide/update-cluster.md index eca8b300b..8543d2f8f 100644 --- a/eks/latest/userguide/update-cluster.md +++ b/eks/latest/userguide/update-cluster.md @@ -5 +5 @@ -Considerations for Amazon EKS Auto ModeStep 1: Prepare for upgradeStep 2: Review upgrade considerationsStep 3: Update cluster control planeStep 4: Update cluster componentsDowngrade the Kubernetes version for an Amazon EKS cluster +Considerations for Amazon EKS Auto ModeSummaryStep 1: Prepare for upgradeStep 2: Review upgrade considerationsStep 3: Update cluster control planeStep 4: Update cluster componentsDowngrade the Kubernetes version for an Amazon EKS cluster @@ -17 +17 @@ When a new Kubernetes version is available in Amazon EKS, you can update your Am -Once you upgrade a cluster, you can’t downgrade to a previous version. We recommend that, before you update to a new Kubernetes version, you review the information in [Understand the Kubernetes version lifecycle on EKS](./kubernetes-versions.html) and also review in the update steps in this topic. +Once you upgrade a cluster, you can’t downgrade to a previous version. Before you update to a new Kubernetes version, we recommend that you review the information in [Understand the Kubernetes version lifecycle on EKS](./kubernetes-versions.html) and the update steps in this topic. @@ -39,0 +40,25 @@ To learn more about what goes into a cluster update, see [Best Practices for Clu +## Summary + +The high-level summary of the Amazon EKS cluster upgrade process is as follows: + + 1. Ensure your cluster is in a state that will support an upgrade. This includes checking the Kubernetes APIs used by resources deployed into the cluster, ensuring the cluster is free of any health issues. You should use Amazon EKS upgrade insights when evaluating your cluster’s upgrade readiness. + + 2. Upgrade the control plane to the next minor version (for example, from 1.31 to 1.32). + + 3. Upgrade the nodes in the data plane to match that of the control plane. + + 4. Upgrade any additional applications that run on the cluster (for example, `cluster-autoscaler`). + + 5. Upgrade the add-ons provided by Amazon EKS, such as those included by default: + + * [Amazon VPC CNI recommended version](./managing-vpc-cni.html) + + * [CoreDNS recommended version](./managing-coredns.html) + + * [kube-proxy recommended version](./managing-kube-proxy.html) + + 6. Upgrade any clients that communicate with the cluster (for example, `kubectl`). + + + + @@ -82,0 +108,2 @@ If no output is returned, this means that your manifest doesn’t have the line. +Amazon EKS cluster insights automatically scan clusters against a list of potential Kubernetes version upgrade impacting issues such as deprecated Kubernetes API usage. Amazon EKS periodically updates the list of insight checks to perform based on evaluations of changes in the Kubernetes project. Amazon EKS also updates the insight checks list as changes are introduced in the Amazon EKS service along with new versions. For more information, see [Prepare for Kubernetes version upgrades with cluster insights](./cluster-insights.html). + @@ -109,0 +137,8 @@ Review the [Deprecated API Migration Guide](https://kubernetes.io/docs/reference +###### Important + +Amazon EKS has temporarily rolled back a feature that would require you to use a `--force` flag to upgrade your cluster when there were certain cluster insight issues. For more information, see [Temporary rollback of enforcing upgrade insights on update cluster version](https://github.com/aws/containers-roadmap/issues/2570) on GitHub. + +Amazon EKS refreshes a cluster insight 24 hours after the "last refresh time". You can compare the time you addressed an issue to the "last refresh time" of the cluster insight. + +Additionally, it can take up to 30 days for the insight status to update after addressing deprecated API usage. Upgrade insights always looks for deprecated API usage over a rolling 30 day window. + @@ -116 +151 @@ You can submit the request to upgrade your EKS control plane version using: - * the AWS cli + * the AWS CLI @@ -123 +158 @@ You can submit the request to upgrade your EKS control plane version using: -This procedure requires `eksctl` version `0.205.0` or later. You can check your version with the following command: +This procedure requires `eksctl` version `0.206.0` or later. You can check your version with the following command: @@ -130 +165 @@ For instructions on how to install and update `eksctl`, see [Installation](https -Update the Kubernetes version of your Amazon EKS control plane. Replace `my-cluster` with your cluster name. Replace `1.30` with the Amazon EKS supported version number that you want to update your cluster to. For a list of supported version numbers, see [Understand the Kubernetes version lifecycle on EKS](./kubernetes-versions.html). +Update the Kubernetes version of your Amazon EKS control plane. Replace `<cluster-name>` with your cluster name. Replace `<version-number>` with the Amazon EKS supported version number that you want to update your cluster to. For a list of supported version numbers, see [Understand the Kubernetes version lifecycle on EKS](./kubernetes-versions.html). @@ -133 +168 @@ Update the Kubernetes version of your Amazon EKS control plane. Replace `my-clus - eksctl upgrade cluster --name my-cluster --version 1.30 --approve + eksctl upgrade cluster --name <cluster-name> --version <version-number> --approve @@ -137 +172 @@ The update takes several minutes to complete. -Continue to Step 4: Update cluster components +Continue to Step 4: Update cluster components. @@ -143 +178 @@ Continue to Step 4: Update cluster components - 2. Choose the name of the Amazon EKS cluster to update and choose **Update cluster version**. + 2. Choose **Upgrade now** for a cluster you wish to upgrade. @@ -145 +180 @@ Continue to Step 4: Update cluster components - 3. For **Kubernetes version** , select the version to update your cluster to and choose **Update**. + 3. Select the version to update your cluster to and choose **Upgrade**. @@ -147,5 +182 @@ Continue to Step 4: Update cluster components - 4. For **Cluster name** , enter the name of your cluster and choose **Confirm**. - -The update takes several minutes to complete. - - 5. Continue to Step 4: Update cluster components + 4. The update takes several minutes to complete. Continue to Step 4: Update cluster components. @@ -158 +189,3 @@ The update takes several minutes to complete. - 1. Update your Amazon EKS cluster with the following AWS CLI command. Replace the `example values` with your own. Replace `1.30` with the Amazon EKS supported version number that you want to update your cluster to. For a list of supported version numbers, see [Understand the Kubernetes version lifecycle on EKS](./kubernetes-versions.html). + 1. Verify that the AWS CLI is installed and that you are logged in. For more information, see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). + + 2. Update your Amazon EKS cluster with the following AWS CLI command. Replace `<cluster-name>` and `<region-code>` of the cluster you want to upgrade. Replace `<version-number>` with the Amazon EKS supported version number that you want to update your cluster to. For a list of supported version numbers, see [Understand the Kubernetes version lifecycle on EKS](./kubernetes-versions.html). @@ -160 +193,2 @@ The update takes several minutes to complete. - aws eks update-cluster-version --region region-code --name my-cluster --kubernetes-version 1.30 + aws eks update-cluster-version --name <cluster-name> \ + --kubernetes-version <verion-number> --region <region-code> @@ -166 +200 @@ An example output is as follows. - "id": "b5f0ba18-9a87-4450-b5a0-825e6e84496f", + "id": "<update-id>", @@ -172 +206 @@ An example output is as follows. - "value": "1.30" + "value": "<version-number>" @@ -183 +217 @@ An example output is as follows. - 2. Monitor the status of your cluster update with the following command. Use the cluster name and update ID that the previous command returned. When a `Successful` status is displayed, the update is complete. The update takes several minutes to complete. + 3. The update takes several minutes to complete. Monitor the status of your cluster update with the following command. In addition to using the same `<cluster-name>` and `<region-code>`, use the `<update-id>` that the previous command returned. @@ -185,3 +219,2 @@ An example output is as follows. - aws eks describe-update --region region-code --name my-cluster --update-id b5f0ba18-9a87-4450-b5a0-825e6e84496f - -An example output is as follows. + aws eks describe-update --name <cluster-name> \ + --region <region-code> --update-id <update-id> @@ -189,18 +222 @@ An example output is as follows. - { - "update": { - "id": "b5f0ba18-9a87-4450-b5a0-825e6e84496f", - "status": "Successful", - "type": "VersionUpdate", - "params": [ - { - "type": "Version", - "value": "1.30" - }, - { - "type": "PlatformVersion", - "value": "eks.1" - } - ], - [...] - "errors": [] - } +When a `Successful` status is displayed, the update is complete. @@ -208 +224 @@ An example output is as follows. - 3. Continue to Step 4: Update cluster components + 4. Continue to Step 4: Update cluster components. @@ -221 +237 @@ An example output is as follows. - 2. Set the Cluster Autoscaler image tag to the version that you recorded in the previous step with the following command. If necessary, replace `1.30`.`n` with your own value. + 2. Set the Cluster Autoscaler image tag to the version that you recorded in the previous step with the following command. If necessary, replace `X.XX.X` with your own value. @@ -223 +239 @@ An example output is as follows. - kubectl -n kube-system set image deployment.apps/cluster-autoscaler cluster-autoscaler=registry.k8s.io/autoscaling/cluster-autoscaler:v1.30.n + kubectl -n kube-system set image deployment.apps/cluster-autoscaler cluster-autoscaler=registry.k8s.io/autoscaling/cluster-autoscaler:vX.XX.X @@ -225 +241 @@ An example output is as follows. - 3. (Clusters with GPU nodes only) If your cluster has node groups with GPU support (for example, `p3.2xlarge`), you must update the [NVIDIA device plugin for Kubernetes](https://github.com/NVIDIA/k8s-device-plugin)DaemonSet on your cluster. Replace `vX.X.X` with your desired [NVIDIA/k8s-device-plugin](https://github.com/NVIDIA/k8s-device-plugin/releases) version before running the following command. + 3. (Clusters with GPU nodes only) If your cluster has node groups with GPU support (for example, `p3.2xlarge`), you must update the [NVIDIA device plugin for Kubernetes](https://github.com/NVIDIA/k8s-device-plugin)DaemonSet on your cluster. Replace `<vX.X.X>` with your desired [NVIDIA/k8s-device-plugin](https://github.com/NVIDIA/k8s-device-plugin/releases) version before running the following command. @@ -227 +243 @@ An example output is as follows. - kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/vX.X.X/deployments/static/nvidia-device-plugin.yml + kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/<vX.X.X>/deployments/static/nvidia-device-plugin.yml