From dd278e4424a82c66f228010ea4566786721632a4 Mon Sep 17 00:00:00 2001 From: Geoffrey Cline Date: Wed, 3 Sep 2025 01:01:51 +0000 Subject: [PATCH 1/3] init draft --- .../ug/automode/auto-migrate-reference.adoc | 164 ++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 latest/ug/automode/auto-migrate-reference.adoc diff --git a/latest/ug/automode/auto-migrate-reference.adoc b/latest/ug/automode/auto-migrate-reference.adoc new file mode 100644 index 00000000..b0725151 --- /dev/null +++ b/latest/ug/automode/auto-migrate-reference.adoc @@ -0,0 +1,164 @@ +[.topic] +[#auto-change] += Resolve EKS Auto Mode migration pre-flight checks +:info_titleabbrev: Migration reference + +== Install + +Running these checks requires access to GitHub, and Python 3 installed. + +```bash +git clone +cd eks-automode-preflight-checker-cli +pip install -e . +``` + +== Reference Table + +[cols="1,2,2"] +|=== +| Check | Description | Status Logic + +| <> +| Validates Kubernetes 1.29+ requirement +| FAIL if < 1.29 + +| <> +| Checks cluster role and Auto Mode policies +| WARN if missing policies + +| <> +| Identifies incompatible nano/micro/small instances +| FAIL if small instances found + +| <> +| Detects unsupported Windows workloads +| FAIL if Windows nodes detected + +| <> +| Identifies SSH keys and SSM access in node groups +| FAIL if direct access configured + +| <> +| Detects custom AMI usage (includes AL2023 support) +| FAIL if custom AMIs (triggers NOT_READY) + +| <> +| Identifies custom node bootstrapping +| FAIL if user data found + +| <> +| Validates managed addons compatibility +| WARN if conflicting addons + +| <> +| Detects Karpenter, Cluster Autoscaler, ASGs +| WARN if existing autoscaling found + +| <> +| Checks IRSA v1 vs Pod Identity usage +| WARN if using IRSA v1, PASS for Pod Identity + +| <> +| Detects ALBs and NLBs associated with cluster +| WARN if load balancers found +|=== + +[#version] +== Version + +Suggested action: If recent version, upgrade to 1.29. + +EKS Auto Mode only supports Kubernetes versions 1.29 and newer. + +If your cluster is 1-2 versions behind, learn how to upgrade your Kubernetes version. + +If your cluster is more than a few versions behind, consider doing a blue/green migration where you deploy your workloads onto a new cluster with the current version. + +[#iam] +== IAM Setup + +Suggested action: Complete EKS Auto Mode IAM Setup + +You need to complete some basic IAM setup tasks before enabling EKS Auto Mode. You need to grant {aws} permission to manage storage, compute, and networking resources related to EKS Auto Mode. + +For setup instructions, see... + +[#instances] +== Small Instances + +Suggested action: Review usage small instance, migrate to medium instances + +EKS Auto Mode does not provision small instances. + +Consider if a single medium sized instance would meet your needs. + +If you require these, you could attach them directly, but if you went over EKS Auto Mode would create a medium instance. + +[#windows] +== Windows Containers + +Suggested action: Do not enable EKS Auto Mode. + +EKS Auto Mode does not support windows containers or instances. + +Can these be direct attached? Unsure. + +[#ssh] +== SSH Access Configured + +By design, you cannot SSH into EKS Auto Mode managed instances. {aws} controls and deploys these instances. + +EKS provides alternate troubleshooting tools. + +[#amis] +== Custom AMI Usage + +By design, you cannot use custom AMIs with EKS Auto Mode. + +If you need to run security software, deploy it as a daemonset. + +[#userdata] +== User Data + +Suggested action: Do not enable EKS Auto Mode if you rely on custom user data. + +EKS Auto Mode manages node bootstrapping and configuration. Custom user data scripts are not supported. + +Consider containerizing any custom setup or configuration that was previously handled by user data scripts. + +[#addons] +== Addons + +Suggested action: Review addon compatibility before enabling EKS Auto Mode. + +Some addons may conflict with EKS Auto Mode's built-in functionality. Verify that your current addons are compatible. + +For a list of compatible addons, refer to the EKS documentation. + +[#autoscaling] +== Autoscaling + +Suggested action: Review existing autoscaling solutions. + +EKS Auto Mode includes built-in autoscaling capabilities. If you're using Karpenter, Cluster Autoscaler, or custom ASGs, you'll need to adapt your scaling strategy. + +Consider migrating to EKS Auto Mode's native scaling mechanisms for optimal performance. + +[#identity] +== Identity + +Suggested action: Consider migrating to Pod Identity. + +While IRSA v1 is supported, Pod Identity is the recommended approach for workload identity in EKS Auto Mode. + +Pod Identity provides enhanced security and simplified management for workload credentials. + +[#loadbalancers] +== Load Balancers + +Suggested action: Review load balancer configurations. + +EKS Auto Mode works with existing ALBs and NLBs, but you may need to adjust configurations to ensure optimal integration. + +Verify that your load balancer settings are compatible with EKS Auto Mode's networking model. From 10d3d22f3c03b2efcfe1d40737c1183c471ae933 Mon Sep 17 00:00:00 2001 From: Geoffrey Cline Date: Mon, 8 Sep 2025 20:55:13 +0000 Subject: [PATCH 2/3] revise --- latest/ug/automode/auto-migrate-prepare.adoc | 131 ++++++++++++++ .../ug/automode/auto-migrate-reference.adoc | 164 ------------------ 2 files changed, 131 insertions(+), 164 deletions(-) create mode 100644 latest/ug/automode/auto-migrate-prepare.adoc delete mode 100644 latest/ug/automode/auto-migrate-reference.adoc diff --git a/latest/ug/automode/auto-migrate-prepare.adoc b/latest/ug/automode/auto-migrate-prepare.adoc new file mode 100644 index 00000000..4040977c --- /dev/null +++ b/latest/ug/automode/auto-migrate-prepare.adoc @@ -0,0 +1,131 @@ +[.topic] +[#auto-prepare] += Prepare for EKS Auto Migration +:info_titleabbrev: Prepare for migration + +You can migrate existing clusters to EKS Auto Mode. Use this topic to review your existing configuration, and identify any preparation needed before migrating. + +== Kubernetes Version + +*Requirement:* EKS Auto Mode only supports Kubernetes versions 1.29 and newer. + +*Suggested action:* If recent version, upgrade to 1.29. + +If your cluster is 1-2 versions behind, learn how to upgrade your Kubernetes version. + +If your cluster is more than a few versions behind, consider doing a blue/green migration where you deploy your workloads onto a new cluster with the current version. + +For more information, see <> or link:eks/latest/best-practices/cluster-upgrades.html["Best Practices for Cluster Upgrades",type="documentation"]. + +== IAM Setup + +*Requirement:* EKS Auto Mode requires additional permissions on the Cluster IAM role. + +*Suggested action:* Attach new managed policies to the Cluster IAM Role, and update the trust policy. + +Each EKS cluster has a Cluster IAM Role. EKS uses this role to take action on other {aws} resources in your account. When you migrate to EKS Auto Mode, you need to grant this role additional permissions to manage compute, storage, and networking resources. + +Follow the procedure *Update Cluster IAM role* from <>. + +[#instances] +== Small Instances + +*Requirement:* EKS Auto Mode does not provision small instances. + +*Suggested action:* Identify usage of small instances. Determine if a single larger instance would be acceptable. + +EKS Auto mode does not provision small instances. The smallest instance size it will create is medium. + +First, look at your existing cluster and determine if you are using any small instances. If you are, evaluate if these workloads can be combined onto a single larger instance. + +If you want to seperate workloads to increase resilence, you can use tains to prevent workloads from being scheduled on the same node. EKS Auto Mode will provision new nodes to accomodate the taints. + +For more information about how EKS Auto Mode works with EC2 instances, see <>. + +== Windows Containers + +*Requirement:* EKS Auto Mode does not support windows instances. + +*Suggested action:* Do not enable EKS Auto Mode. + +EKS Auto Mode does not support windows containers or instances. Consider migrating your windows workloads to another cluster. + +For information, see <>. + +== SSH Access + +*Requirement:* You cannot SSH into EKS Auto Mode managed instances. + +*Suggested action:* Use `kubectl` to access logs and debug instances. + +By design, you cannot SSH into EKS Auto Mode managed instances. {aws} controls and deploys these instances. You can use EC2 APIs to retreive instance console output. You can use the command `kubectl debug node` to stream logs live from an instance. + +EKS provides alternate troubleshooting tools. For more information, see <>. + +== Custom AMI Usage + +*Requirement:* By design, you cannot use custom AMIs with EKS Auto Mode. The only OS supported is Bottlerocket. + +*Suggested action:* Migrate to using Kubernetes resources, such as DaemonSets, to provide node-local facilities. + +EKS Auto Mode automatically patches and updates the EC2 instances behind nodes. To support this automation, EKS does not support custom AMIs on nodes. Migrate node workloads such as security software to https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/[Kubernetes DaemonSet], to decople your workloads from the underlying operating system. + +For more information, see <>. + +== User Data + +*Requirement:* By design, EKS Auto Mode does not support custom user data. + +*Suggested action:* Identify actions in current user data, and migrate them to Kubernetes workloads. + +EKS Auto Mode manages node bootstrapping and configuration. Custom user data scripts are not supported. User data is custom information passed to EC2 instances at launch time. + +Consider containerizing any custom setup or configuration that was previously handled by user data scripts. + +For more information, see <>. + +== Addons + +*Requirement:* EKS Auto Mode requires minimum versions of certain add-ons, such as the Amazon VPC CNI plugin for Kubernetes or Kube-proxy. + +*Suggested action:* Review add-on compatibility before enabling EKS Auto Mode. Upgrade add-ons to the minimum version. + +Some add-ons may conflict with EKS Auto Mode's built-in functionality. Verify that your current add-ons are compatible. + +For a list of compatible add-ons and the required minium version, see <>. + +== Autoscaling + +*Requirement:* EKS Auto mode includes built-in autoscaling, based on Karpenter. + +*Suggested action:* Review existing autoscaling solutions and adapt your scaling strategy. + +EKS Auto Mode includes built-in autoscaling capabilities. If you're using Karpenter, Cluster Autoscaler, or custom ASGs, you'll need to adapt your scaling strategy. + +Consider migrating to EKS Auto Mode's native scaling mechanisms for optimal performance. + +For more information, see <> + +== Identity + +*Requirement:* EKS Auto Mode supports both IRSA v1 and Pod Identity for workload identity. + +*Suggested action:* Consider migrating to Pod Identity. + +While IRSA v1 is supported, Pod Identity is the recommended approach for workload identity in EKS Auto Mode. + +Pod Identity provides enhanced security and simplified management for workload credentials. + +// Do we have a migration guide? Good link? + +== Load Balancers + +*Requirement:* EKS Auto Mode integrates with existing load balancer configurations. + +*Suggested action:* Review load balancer configurations. + +EKS Auto Mode works with existing ALBs and NLBs, but you may need to adjust configurations to ensure optimal integration. + +Verify that your load balancer settings are compatible with EKS Auto Mode's networking model. + +// Whatever? diff --git a/latest/ug/automode/auto-migrate-reference.adoc b/latest/ug/automode/auto-migrate-reference.adoc deleted file mode 100644 index b0725151..00000000 --- a/latest/ug/automode/auto-migrate-reference.adoc +++ /dev/null @@ -1,164 +0,0 @@ -[.topic] -[#auto-change] -= Resolve EKS Auto Mode migration pre-flight checks -:info_titleabbrev: Migration reference - -== Install - -Running these checks requires access to GitHub, and Python 3 installed. - -```bash -git clone -cd eks-automode-preflight-checker-cli -pip install -e . -``` - -== Reference Table - -[cols="1,2,2"] -|=== -| Check | Description | Status Logic - -| <> -| Validates Kubernetes 1.29+ requirement -| FAIL if < 1.29 - -| <> -| Checks cluster role and Auto Mode policies -| WARN if missing policies - -| <> -| Identifies incompatible nano/micro/small instances -| FAIL if small instances found - -| <> -| Detects unsupported Windows workloads -| FAIL if Windows nodes detected - -| <> -| Identifies SSH keys and SSM access in node groups -| FAIL if direct access configured - -| <> -| Detects custom AMI usage (includes AL2023 support) -| FAIL if custom AMIs (triggers NOT_READY) - -| <> -| Identifies custom node bootstrapping -| FAIL if user data found - -| <> -| Validates managed addons compatibility -| WARN if conflicting addons - -| <> -| Detects Karpenter, Cluster Autoscaler, ASGs -| WARN if existing autoscaling found - -| <> -| Checks IRSA v1 vs Pod Identity usage -| WARN if using IRSA v1, PASS for Pod Identity - -| <> -| Detects ALBs and NLBs associated with cluster -| WARN if load balancers found -|=== - -[#version] -== Version - -Suggested action: If recent version, upgrade to 1.29. - -EKS Auto Mode only supports Kubernetes versions 1.29 and newer. - -If your cluster is 1-2 versions behind, learn how to upgrade your Kubernetes version. - -If your cluster is more than a few versions behind, consider doing a blue/green migration where you deploy your workloads onto a new cluster with the current version. - -[#iam] -== IAM Setup - -Suggested action: Complete EKS Auto Mode IAM Setup - -You need to complete some basic IAM setup tasks before enabling EKS Auto Mode. You need to grant {aws} permission to manage storage, compute, and networking resources related to EKS Auto Mode. - -For setup instructions, see... - -[#instances] -== Small Instances - -Suggested action: Review usage small instance, migrate to medium instances - -EKS Auto Mode does not provision small instances. - -Consider if a single medium sized instance would meet your needs. - -If you require these, you could attach them directly, but if you went over EKS Auto Mode would create a medium instance. - -[#windows] -== Windows Containers - -Suggested action: Do not enable EKS Auto Mode. - -EKS Auto Mode does not support windows containers or instances. - -Can these be direct attached? Unsure. - -[#ssh] -== SSH Access Configured - -By design, you cannot SSH into EKS Auto Mode managed instances. {aws} controls and deploys these instances. - -EKS provides alternate troubleshooting tools. - -[#amis] -== Custom AMI Usage - -By design, you cannot use custom AMIs with EKS Auto Mode. - -If you need to run security software, deploy it as a daemonset. - -[#userdata] -== User Data - -Suggested action: Do not enable EKS Auto Mode if you rely on custom user data. - -EKS Auto Mode manages node bootstrapping and configuration. Custom user data scripts are not supported. - -Consider containerizing any custom setup or configuration that was previously handled by user data scripts. - -[#addons] -== Addons - -Suggested action: Review addon compatibility before enabling EKS Auto Mode. - -Some addons may conflict with EKS Auto Mode's built-in functionality. Verify that your current addons are compatible. - -For a list of compatible addons, refer to the EKS documentation. - -[#autoscaling] -== Autoscaling - -Suggested action: Review existing autoscaling solutions. - -EKS Auto Mode includes built-in autoscaling capabilities. If you're using Karpenter, Cluster Autoscaler, or custom ASGs, you'll need to adapt your scaling strategy. - -Consider migrating to EKS Auto Mode's native scaling mechanisms for optimal performance. - -[#identity] -== Identity - -Suggested action: Consider migrating to Pod Identity. - -While IRSA v1 is supported, Pod Identity is the recommended approach for workload identity in EKS Auto Mode. - -Pod Identity provides enhanced security and simplified management for workload credentials. - -[#loadbalancers] -== Load Balancers - -Suggested action: Review load balancer configurations. - -EKS Auto Mode works with existing ALBs and NLBs, but you may need to adjust configurations to ensure optimal integration. - -Verify that your load balancer settings are compatible with EKS Auto Mode's networking model. From c0f2c608921ca9fc95ea69339a3a4a5a9aa04de1 Mon Sep 17 00:00:00 2001 From: Geoffrey Cline Date: Fri, 12 Sep 2025 22:11:45 +0000 Subject: [PATCH 3/3] revise --- latest/ug/automode/auto-migrate-prepare.adoc | 38 +++++++++++++------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/latest/ug/automode/auto-migrate-prepare.adoc b/latest/ug/automode/auto-migrate-prepare.adoc index 4040977c..46ff40a3 100644 --- a/latest/ug/automode/auto-migrate-prepare.adoc +++ b/latest/ug/automode/auto-migrate-prepare.adoc @@ -3,7 +3,9 @@ = Prepare for EKS Auto Migration :info_titleabbrev: Prepare for migration -You can migrate existing clusters to EKS Auto Mode. Use this topic to review your existing configuration, and identify any preparation needed before migrating. +Before enabling EKS Auto Mode on an existing cluster, you need to assess your current configuration for compatibility and prepare your environment for a successful migration. This preparation phase is critical to ensure a smooth transition and minimize disruption to your workloads. + +This topic provides a checklist of requirements and suggested actions to address potential compatibility issues before proceeding with migration. Review each section carefully and complete the necessary preparations to ensure your cluster is ready for EKS Auto Mode. == Kubernetes Version @@ -36,9 +38,9 @@ Follow the procedure *Update Cluster IAM role* from <>. EKS Auto mode does not provision small instances. The smallest instance size it will create is medium. -First, look at your existing cluster and determine if you are using any small instances. If you are, evaluate if these workloads can be combined onto a single larger instance. +First, examine your existing cluster and determine if you are using any small instances. If you are, evaluate if these workloads can be combined onto a single larger instance. -If you want to seperate workloads to increase resilence, you can use tains to prevent workloads from being scheduled on the same node. EKS Auto Mode will provision new nodes to accomodate the taints. +If you want to separate workloads to increase resilience, you can use taints to prevent workloads from being scheduled on the same node. EKS Auto Mode will provision new nodes to accommodate the taints. For more information about how EKS Auto Mode works with EC2 instances, see <>. @@ -58,7 +60,7 @@ For information, see <>. *Suggested action:* Use `kubectl` to access logs and debug instances. -By design, you cannot SSH into EKS Auto Mode managed instances. {aws} controls and deploys these instances. You can use EC2 APIs to retreive instance console output. You can use the command `kubectl debug node` to stream logs live from an instance. +By design, you cannot SSH into EKS Auto Mode managed instances. {aws} controls and deploys these instances. You can use EC2 APIs to retrieve instance console output. You can use the command `kubectl debug node` to stream logs live from an instance. EKS provides alternate troubleshooting tools. For more information, see <>. @@ -68,7 +70,7 @@ EKS provides alternate troubleshooting tools. For more information, see <>. @@ -92,7 +94,7 @@ For more information, see <>. Some add-ons may conflict with EKS Auto Mode's built-in functionality. Verify that your current add-ons are compatible. -For a list of compatible add-ons and the required minium version, see <>. +For a list of compatible add-ons and the required minimum version, see <>. == Autoscaling @@ -116,16 +118,28 @@ While IRSA v1 is supported, Pod Identity is the recommended approach for workloa Pod Identity provides enhanced security and simplified management for workload credentials. -// Do we have a migration guide? Good link? +For more information, see <>. == Load Balancers -*Requirement:* EKS Auto Mode integrates with existing load balancer configurations. - -*Suggested action:* Review load balancer configurations. +*Requirement:* EKS Auto Mode does not support taking over management of existing load balancers. EKS Auto Mode does not support all configurations of the open source load balancer controller. -EKS Auto Mode works with existing ALBs and NLBs, but you may need to adjust configurations to ensure optimal integration. +*Suggested action:* Review load balancer configurations, and perform a migration between load balancers by using Route53. Verify that your load balancer settings are compatible with EKS Auto Mode's networking model. -// Whatever? +For information about configuring application load balancers, see <>. + +For information about configuring network load balancers, see <>. + +{aws} suggests a DNS-based traffic shifting approach. Generally, you should maintain your existing load balancer configuration while creating new load balancers under the managed controller. For more information, see link:eks/latest/userguide/migrate-auto.html#_migrating_load_balancers["Migrating load balancers",type="documentation"]. + +== EBS Volumes + +*Requirement:* EKS Auto Mode cannot mount volumes created by the EBS CSI controller. + +*Suggested action:* Use the EKS Auto Mode EBS Migration tool to automate migrating volumes to EKS Auto Mode management. + +This migration requires deleting and re-creating existing `PersistentVolumeClaim` and `PersistentVolume` resources. + +For more information, see link:https://github.com/awslabs/eks-auto-mode-ebs-migration-tool[`eks-auto-mode-ebs-migration-tool`] on GitHub.