View a markdown version of this page

Migrating large-scale self-managed Kubernetes clusters to Amazon EKS - AWS Prescriptive Guidance
OverviewIntended audienceObjectives of this guideService availabilityPrerequisites and limitations

Migrating large-scale self-managed Kubernetes clusters to Amazon EKS

Pradip Kumar Pandey and Pratap Kumar Nanda, Amazon Web Services

June 2026 (document history)

Overview

Moving from a self-managed Kubernetes setup to Amazon Elastic Kubernetes Service (Amazon EKS) represents a significant shift in how organizations handle container orchestration. This transition involves moving your existing workloads, configurations, and operational practices from clusters you manage yourself to a managed Kubernetes service on AWS.

This guide helps you migrate self-managed Kubernetes to Amazon EKS by reducing risks, saving time and cost, and providing clear planning frameworks. It builds team confidence, supports informed decision-making, and enables effective stakeholder communication. The guide serves as a practical reference throughout the migration journey, helping organizations avoid costly mistakes while transitioning from infrastructure maintenance to focusing on application development and business value delivery.

Intended audience

This guide is intended for the following roles:

  • Cloud architects planning the target Amazon EKS environment

  • Platform engineers responsible for Kubernetes cluster operations

  • DevOps engineers managing CI/CD pipelines and deployment workflows

  • Migration leads coordinating the transition from self-managed clusters

Readers should have foundational knowledge of Kubernetes concepts (pods, deployments, services, namespaces), experience with kubectl, and familiarity with AWS core services.

Objectives of this guide

After reading this guide, you will be able to:

  • Assess your current self-managed Kubernetes environment for migration readiness

  • Select the appropriate migration approach (blue-green, phased, or lift-and-shift) based on your requirements

  • Plan infrastructure, networking, storage, and security for the target Amazon EKS environment

  • Define a testing and validation strategy that minimizes risk during cutover

  • Identify post-migration optimization opportunities using AWS-native services

  • Communicate migration plans and progress effectively to stakeholders

Service availability

Some AWS services aren't available in all AWS Regions. For Region availability, see AWS services by Region. For specific endpoints, see the Service endpoints and quotas page, and choose the link for the service.

Prerequisites and limitations

Prerequisites

Requirement

Details

Python

3.9 or higher installed on the local machine

kubectl

Installed and configured with access to both the source cluster (for extraction) and the target Amazon EKS cluster (for migration)

AWS Command Line Interface

Version 2.x, configured with AWS Identity and Access Management (IAM) permissions for Amazon EKS, IAM, and Amazon EC2.

Helm (optional)

Version 3.x, required only if migrating Helm releases

Target Amazon EKS cluster

Must already exist. The migration script does not provision the cluster. For more information, see Creating an Amazon EKS cluster in the Amazon EKS documentation.

Amazon EBS CSI driver

Installed on the target Amazon EKS cluster for StorageClass provisioner remapping (ebs.csi.aws.com)

AWS Load Balancer Controller

Installed on the target Amazon EKS cluster for Service type LoadBalancer and ALB Ingress support

CRD operators

Any controllers for custom resources used in the source cluster (for example, cert-manager, Prometheus Operator) must be installed on the target cluster before migration

IAM roles for service accounts (IRSA)

Configured on the target Amazon EKS cluster if workloads require AWS API access

Network connectivity

The local machine must have network access to both the source and target Kubernetes API servers

Cluster admin access

Admin-level access to both source and target clusters through kubectl. The extraction script requires read access to all resources; the migration script requires create/update permissions.

Limitations

  • Persistent volume data is not migrated. Use AWS DataSync or Velero for persistent volume data migration.

  • Helm releases require the original chart source to reinstall. The script outputs the commands but cannot run them without chart references.

  • Secret values are created as opaque placeholders. You must populate actual values post-migration through AWS Secrets Manager, AWS Systems Manager Parameter Store, or External Secrets Operator.

  • CRD operators and controllers must be pre-installed on the target Amazon EKS cluster before you migrate custom resource instances. For more information, see AWS Controllers for Kubernetes.

  • If the source cluster uses a private container registry, ensure that Amazon EKS nodes have pull access, such as Amazon Elastic Container Registry and image pull secrets.