You're viewing the current version of Migration Assistant documentation (Kubernetes/EKS-based). For the classic ECS/CDK-based version, see the classic documentation.

Deploy on Amazon EKS

Amazon Elastic Kubernetes Service (EKS) is the recommended production path on AWS. An EKS deployment runs the same Migration Assistant engine and workflows as a generic Kubernetes deployment, and the bootstrap script provisions the surrounding AWS infrastructure for you.

EKS deployment components

The bootstrap path prepares AWS infrastructure around the workflow engine, including:

• EKS cluster deployment into a new or existing virtual private cloud (VPC).
• Pod identity for the Migration Console and workflow pods.
• Image mirroring and VPC endpoint support for isolated subnets.
• Default Amazon Simple Storage Service (Amazon S3) bucket and snapshot-role helpers.
• Amazon CloudWatch logging and dashboards.
• AWS-aware storage and node-pool defaults.

If you are migrating to or from Amazon OpenSearch Service, this is usually the shortest path to a working production setup.

Prerequisites

Before you begin, make sure you have the following:

• An AWS account with permissions for AWS CloudFormation, Amazon EKS, AWS Identity and Access Management (IAM), Amazon Elastic Compute Cloud (Amazon EC2), Amazon Elastic Container Registry (Amazon ECR), Amazon S3, Amazon CloudWatch, and related services.
• Either AWS CloudShell or a local terminal with AWS CLI v2, kubectl, and Helm installed. AWS CloudShell is recommended because it comes preconfigured with the required tools and avoids platform-specific issues (for example, the tac command used by the bootstrap script is not available on macOS by default).

Deployment label

Throughout this guide, <STAGE> is a short label such as dev, staging, or prod. It is used in cluster and resource names so you can keep multiple deployments separate.

Step 1: Download the bootstrap script

Download the bootstrap script:

curl -sL -o aws-bootstrap.sh \
  "https://github.com/opensearch-project/opensearch-migrations/releases/latest/download/aws-bootstrap.sh" \
  && chmod +x aws-bootstrap.sh

Bootstrap flag reference

The following table lists the most commonly used flags. To see all available options for the version you downloaded, run ./aws-bootstrap.sh --help.

Step 2: Deploy into a new or existing VPC

Deploy Migration Assistant into either a new VPC or an existing VPC.

New VPC using the latest published release

To deploy into a new VPC using the latest published release, run the following command:

./aws-bootstrap.sh \
  --deploy-create-vpc-cfn \
  --stack-name MA \
  --stage dev \
  --region us-east-2

New VPC pinned to a specific release

To pin the deployment to a specific release version, run the following command:

./aws-bootstrap.sh \
  --deploy-create-vpc-cfn \
  --stack-name MA \
  --stage prod \
  --region us-east-2 \
  --version 3.2.1

Pinning a version makes the deployment reproducible. If you need to deploy the same artifacts again or deploy through continuous integration (CI), always pass --version.

Existing VPC

To deploy into an existing VPC, run the following command:

./aws-bootstrap.sh \
  --deploy-import-vpc-cfn \
  --stack-name MA \
  --stage dev \
  --vpc-id vpc-0abc123 \
  --subnet-ids subnet-111,subnet-222 \
  --region us-east-2

When the script finishes, it has installed the Helm chart and configured the Migration Console, the Argo workflow controller, and the Argo server.

Step 3: Verify the deployment

First, point kubectl at the new cluster:

aws eks update-kubeconfig --region <REGION> --name migration-eks-cluster-<STAGE>-<REGION>

Then list the pods in the ma namespace:

kubectl get pods -n ma

You should see the Migration Console, the Argo workflow controller, and the Argo server in Running state.

Step 4: Access the Migration Console

Access the Migration Console:

kubectl exec -it migration-console-0 -n ma -- /bin/bash

After you access the console, the migration flow is the same as for any other deployment: verify the version, load the sample configuration, run a pilot migration, validate it, and then run the full migration.

Step 5: Use the AWS resources created by the deployment

The EKS path provides a default snapshot bucket and related configuration so you do not have to build it manually.

Default S3 bucket

The deployment creates a default S3 bucket for migration artifacts and snapshots:

s3://migrations-default-<ACCOUNT_ID>-<STAGE>-<REGION>

Snapshot role output

If your workflow needs a snapshot role Amazon Resource Name (ARN), look it up from the CloudFormation outputs:

aws cloudformation describe-stacks \
  --stack-name <YOUR_STACK_NAME> \
  --query "Stacks[0].Outputs[?contains(OutputKey,'MigrationsExportString')].OutputValue" \
  --output text

Authentication on EKS

Migration Assistant supports the following authentication methods on EKS.

Basic authentication

Basic authentication works the same way as generic Kubernetes: create Kubernetes secrets and reference them in authConfig.basic.secretName.

Authenticate with AWS Signature Version 4

For sources or targets authenticated using AWS Signature Version 4, the EKS stack uses IAM Roles for Service Accounts (IRSA) to assign an AWS identity to two sets of pods:

• The Migration Console pod (migration-console-0), which runs under the migration-console-access-role service account.
• The Argo workflow executor pods, which run under the argo-workflow-executor service account.

The console and the migration jobs authenticate to Amazon OpenSearch Service and other AWS services without requiring you to distribute long-lived AWS credentials.

Private or isolated networks

If your subnets do not have direct internet access, the bootstrap script mirrors images into private ECR by default and creates the VPC endpoints needed to pull from inside the cluster:

./aws-bootstrap.sh \
  --deploy-import-vpc-cfn \
  --create-vpc-endpoints \
  --stack-name MA-Prod \
  --stage prod \
  --vpc-id vpc-xxx \
  --subnet-ids subnet-aaa,subnet-bbb \
  --region us-east-1 \
  --version 3.2.1

The mirroring step runs from your machine, which must have internet access, and copies the release images and Helm charts to Amazon ECR. The EKS cluster then pulls everything through VPC endpoints. The script creates endpoints for Amazon S3, Amazon ECR API, Amazon ECR Docker, CloudWatch Logs, and Amazon Elastic File System (Amazon EFS).

If your deployment also requires AWS Security Token Service (AWS STS) or EKS Authentication endpoints (for example, for IRSA or EKS Pod Identity), create those separately before running the bootstrap script.

If you prefer to manage VPC endpoints using another tool, omit --create-vpc-endpoints. The script still mirrors images and uses your existing endpoints.

Grant kubectl access to a CI role or teammate

After the cluster is bootstrapped, run the script in grant-only mode to add a second admin principal:

./aws-bootstrap.sh \
  --grant-eks-access-only \
  --eks-access-principal-arn arn:aws:iam::123456789012:role/MyCIRole \
  --stage dev \
  --region us-east-2

The script applies the EKS access entry and policy association for the principal and then exits. It does not redeploy CloudFormation, mirror images, run Helm, or update your kubeconfig, and it skips the jq, kubectl, and helm prerequisite checks.

From the cluster-owning account, verify the access entry and its associated policies:

aws eks list-access-entries \
  --cluster-name <CLUSTER_NAME> \
  --region <REGION>

aws eks list-associated-access-policies \
  --cluster-name <CLUSTER_NAME> \
  --principal-arn arn:aws:iam::123456789012:role/MyCIRole \
  --region <REGION>

Recovery if bootstrap fails

If CloudFormation fails, verify the stack status:

aws cloudformation describe-stacks --stack-name <STACK_NAME> --query "Stacks[0].StackStatus"

If the stack is stuck in ROLLBACK_COMPLETE or CREATE_FAILED, delete it and rerun the bootstrap script:

aws cloudformation delete-stack --stack-name <STACK_NAME>
aws cloudformation wait stack-delete-complete --stack-name <STACK_NAME>

If CloudFormation succeeded but the Helm portion failed, rerun only the bootstrap’s cluster-side steps:

./aws-bootstrap.sh --skip-cfn-deploy --stage <STAGE> --region <REGION>

Removal

To remove Migration Assistant from EKS, run the following commands:

helm uninstall -n ma ma
kubectl -n ma delete pvc --all
aws cloudformation delete-stack --stack-name <STACK_NAME>
aws cloudformation wait stack-delete-complete --stack-name <STACK_NAME>

Next steps

1. Open the Migration Console and run console --version.
2. Load the sample workflow with workflow configure sample --load.
3. Run console clusters connection-check.
4. Continue with Using the Workflow CLI.