**Help improve this page** To contribute to this user guide, choose the **Edit this page on GitHub** link that is located in the right pane of every page. # Prepare for Kubernetes version upgrades and troubleshoot misconfigurations with cluster insights Cluster insights Amazon EKS cluster insights provide detection of issues and recommendations to resolve them to help you manage your cluster. Every Amazon EKS cluster undergoes automatic, recurring checks against an Amazon EKS curated list of insights. These *insight checks* are fully managed by Amazon EKS and offer recommendations on how to address any findings. ## Cluster insight types + **Configuration insights**: Identifies misconfigurations in your EKS Hybrid Nodes setup that could impair functionality of your cluster or workloads. + **Upgrade insights**: Identifies issues that could impact your ability to upgrade to new versions of Kubernetes. ## Considerations + **Frequency**: Amazon EKS refreshes cluster insights every 24 hours, or you can manually refresh them to see the latest status. For example, you can manually refresh cluster insights after addressing an issue to see if the issue was resolved. + **Permissions**: Amazon EKS automatically creates a cluster access entry for cluster insights in every EKS cluster. This entry gives EKS permission to view information about your cluster. Amazon EKS uses this information to generate the insights. For more information, see [AmazonEKSClusterInsightsPolicy](access-policy-permissions.md#access-policy-permissions-AmazonEKSClusterInsightsPolicy). ## Use cases Cluster insights in Amazon EKS provide automated checks to help maintain the health, reliability, and optimal configuration of your Kubernetes clusters. Below are key use cases for cluster insights, including upgrade readiness and configuration troubleshooting. ### Upgrade insights Upgrade insights are a specific type of insight checks within cluster insights. These checks returns insights related to Kubernetes version upgrade readiness. Amazon EKS runs upgrade insight checks on every EKS cluster. **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. For more information about updating your cluster, see [Step 3: Update cluster control plane](update-cluster.md#update-cluster-control-plane). Before updating your cluster Kubernetes version, you can use the **Upgrade insights** tab of the observability dashboard in the [Amazon EKS console](https://console.aws.amazon.com/eks/home#/clusters). If your cluster has identified issues, review them and make appropriate fixes. The issues include links to Amazon EKS and Kubernetes documentation. After fixing the issue, refresh cluster insights on-demand to fetch the latest insights. If all issues have been resolved, [update your cluster](update-cluster.md). Amazon EKS returns insights related to Kubernetes version upgrade readiness. Upgrade insights identify possible issues that could impact Kubernetes cluster upgrades. This minimizes the effort that administrators spend preparing for upgrades and increases the reliability of applications on newer Kubernetes versions. Clusters are automatically scanned by Amazon EKS against a list of possible Kubernetes version upgrade impacting issues. Amazon EKS frequently updates the list of insight checks based on reviews of changes made in each Kubernetes version release. Amazon EKS upgrade insights speed up the testing and verification process for new versions. They also allow cluster administrators and application developers to leverage the newest Kubernetes capabilities by highlighting concerns and offering remediation advice. ### Configuration insights EKS cluster insights automatically scans Amazon EKS clusters with hybrid nodes to identify configuration issues impairing Kubernetes control plane-to-webhook communication, kubectl commands like exec and logs, and more. Configuration insights surface issues and provide remediation recommendations, accelerating the time to a fully functioning hybrid nodes setup. ## Get started To see the list of insight checks performed and any relevant issues that Amazon EKS has identified, you can use the AWS Management Console, the AWS CLI, AWS SDKs, and Amazon EKS `ListInsights` API operation. To get started, see [View cluster insights](view-cluster-insights.md). # View cluster insights Amazon EKS provides two types of insights: **Configuration insights** and **Upgrade insights**. **Configuration insights** identify misconfigurations in your EKS Hybrid Nodes setup that could impair functionality of your cluster or workloads. **Upgrade insights** identify issues that could impact your ability to upgrade to new versions of Kubernetes. To see the list of insight checks performed and any relevant issues that Amazon EKS has identified, you can call the look in the AWS Management Console, the AWS CLI, AWS SDKs, and Amazon EKS `ListInsights` API operation. ## View configuration insights (Console) 1. Open the [Amazon EKS console](https://console.aws.amazon.com/eks/home#/clusters). 1. From the cluster list, choose the name of the Amazon EKS cluster for which you want to see the insights. 1. Choose **Monitor cluster**. 1. Choose the **Cluster health** tab. 1. In the **Configuration insights** table, you will see the following columns: + **Name** – The check that was performed by Amazon EKS against the cluster. + **Insight status** – An insight with a status of `Error` means that there is a misconfiguration that is likely impacting cluster functionality. An insight with a status of `Warning` means that the configuration doesn’t match the documented approach, but that cluster functionality might work if you configured it intentionally. An insight with status of `Passing` means Amazon EKS has not found any issues associated with this insight check in your cluster. + **Version** – The applicable version. + **Last refresh time** – The time the status of the insight was last refreshed for this cluster. + **Description** – Information from the insight check, which includes the alert and recommended actions for remediation. ## View upgrade insights (Console) 1. Open the [Amazon EKS console](https://console.aws.amazon.com/eks/home#/clusters). 1. From the cluster list, choose the name of the Amazon EKS cluster for which you want to see the insights. 1. Choose **Monitor cluster**. 1. Choose the **Upgrade insights** tab. 1. To view the latest data, choose the **Refresh insights** button and wait for the refresh operation to complete. 1. In the **Upgrade insights** table, you will see the following columns: + **Name** – The check that was performed by Amazon EKS against the cluster. + **Insight status** – An insight with a status of "Error" typically means the impacted Kubernetes version is N\$11 of the current cluster version, while a status of "Warning" means the insight applies to a future Kubernetes version N\$12 or more. An insight with status of "Passing" means Amazon EKS has not found any issues associated with this insight check in your cluster. An insight status of "Unknown" means Amazon EKS is unable to determine if your cluster is impacted by this insight check. + **Version** – The Kubernetes version that the insight checked for possible issues. + **Last refresh time** – The time the status of the insight was last refreshed for this cluster. + **Last transition time** – The time the status of this insight last changed. + **Description** – Information from the insight check, which includes the alert and recommended actions for remediation. ## View cluster insights (AWS CLI) 1. To view the latest data, refresh the insights for a specified cluster. Make the following modifications to the command as needed and then run the modified command. + Replace *region-code* with the code for your AWS Region. + Replace *my-cluster* with the name of your cluster. ``` aws eks start-insights-refresh --region region-code --cluster-name my-cluster ``` 1. To track the status of an insights refresh, run the following command. Replace *my-cluster* with the name of your cluster. ``` aws eks describe-insights-refresh --cluster-name my-cluster ``` An example output is as follows. ``` { "message": "Insights refresh is in progress", "status": "IN_PROGRESS", "startedAt": "2025-07-30T13:36:09-07:00" } ``` 1. List the insights for a specified cluster. Make the following modifications to the command as needed and then run the modified command. + Replace *region-code* with the code for your AWS Region. + Replace *my-cluster* with the name of your cluster. ``` aws eks list-insights --region region-code --cluster-name my-cluster ``` An example output is as follows. ``` { "insights": [ { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "name": "Deprecated APIs removed in Kubernetes vX.XX", "category": "UPGRADE_READINESS", "kubernetesVersion": "X.XX", "lastRefreshTime": 1734557315.000, "lastTransitionTime": 1734557309.000, "description": "Checks for usage of deprecated APIs that are scheduled for removal in Kubernetes vX.XX. Upgrading your cluster before migrating to the updated APIs supported by vX.XX could cause application impact.", "insightStatus": { "status": "PASSING", "reason": "No deprecated API usage detected within the last 30 days.", }, }, { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222", "name": "Kubelet version skew", "category": "UPGRADE_READINESS", "kubernetesVersion": "X.XX", "lastRefreshTime": 1734557309.000, "lastTransitionTime": 1734557309.000, "description": "Checks for kubelet versions of worker nodes in the cluster to see if upgrade would cause non compliance with supported Kubernetes kubelet version skew policy.", "insightStatus": { "status": "UNKNOWN", "reason": "Unable to determine status of node kubelet versions.", }, }, { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE33333", "name": "Deprecated APIs removed in Kubernetes vX.XX", "category": "UPGRADE_READINESS", "kubernetesVersion": "X.XX", "lastRefreshTime": 1734557315.000, "lastTransitionTime": 1734557309.000, "description": "Checks for usage of deprecated APIs that are scheduled for removal in Kubernetes vX.XX. Upgrading your cluster before migrating to the updated APIs supported by vX.XX could cause application impact.", "insightStatus": { "status": "PASSING", "reason": "No deprecated API usage detected within the last 30 days.", }, }, { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLEaaaaa", "name": "Cluster health issues", "category": "UPGRADE_READINESS", "kubernetesVersion": "X.XX", "lastRefreshTime": 1734557314.000, "lastTransitionTime": 1734557309.000, "description": "Checks for any cluster health issues that prevent successful upgrade to the next Kubernetes version on EKS.", "insightStatus": { "status": "PASSING", "reason": "No cluster health issues detected.", }, }, { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLEbbbbb", "name": "EKS add-on version compatibility", "category": "UPGRADE_READINESS", "kubernetesVersion": "X.XX", "lastRefreshTime": 1734557314.000, "lastTransitionTime": 1734557309.000, "description": "Checks version of installed EKS add-ons to ensure they are compatible with the next version of Kubernetes. ", "insightStatus": { "status": "PASSING", "reason": "All installed EKS add-on versions are compatible with next Kubernetes version."}, }, { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLEccccc", "name": "kube-proxy version skew", "category": "UPGRADE_READINESS", "kubernetesVersion": "X.XX", "lastRefreshTime": 1734557314.000, "lastTransitionTime": 1734557309.000, "description": "Checks version of kube-proxy in cluster to see if upgrade would cause non compliance with supported Kubernetes kube-proxy version skew policy.", "insightStatus": { "status": "PASSING", "reason": "kube-proxy versions match the cluster control plane version.", }, }, { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLEddddd", "name": "Deprecated APIs removed in Kubernetes vX.XX", "category": "UPGRADE_READINESS", "kubernetesVersion": "X.XX", "lastRefreshTime": 1734557315.000, "lastTransitionTime": 1734557309.000, "description": "Checks for usage of deprecated APIs that are scheduled for removal in Kubernetes vX.XX. Upgrading your cluster before migrating to the updated APIs supported by vX.XX could cause application impact.", "insightStatus": { "status": "PASSING", "reason": "No deprecated API usage detected within the last 30 days.", }, }, ], "nextToken": null, } ``` 1. For descriptive information about an insight, run the following command. Make the following modifications to the command as needed and then run the modified command. + Replace *region-code* with the code for your AWS Region. + Replace *a1b2c3d4-5678-90ab-cdef-EXAMPLE22222* with an insight ID retrieved from listing the cluster insights. + Replace *my-cluster* with the name of your cluster. ``` aws eks describe-insight --region region-code --id a1b2c3d4-5678-90ab-cdef-EXAMPLE22222 --cluster-name my-cluster ``` An example output is as follows. ``` { "insight": { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222", "name": "Kubelet version skew", "category": "UPGRADE_READINESS", "kubernetesVersion": "1.27", "lastRefreshTime": 1734557309.000, "lastTransitionTime": 1734557309.000, "description": "Checks for kubelet versions of worker nodes in the cluster to see if upgrade would cause non compliance with supported Kubernetes kubelet version skew policy.", "insightStatus": { "status": "UNKNOWN", "reason": "Unable to determine status of node kubelet versions.", }, "recommendation": "Upgrade your worker nodes to match the Kubernetes version of your cluster control plane.", "additionalInfo": { "Kubelet version skew policy": "https://kubernetes.io/releases/version-skew-policy/#kubelet", "Updating a managed node group": "https://docs.aws.amazon.com/eks/latest/userguide/update-managed-node-group.html", }, "resources": [], "categorySpecificSummary": { "deprecationDetails": [], "addonCompatibilityDetails": [] }, }, } ```