Deploy the solution

This solution deploys to Amazon Elastic Kubernetes Service (Amazon EKS). The Amazon EKS deployment is the recommended deployment for Migration Assistant 3.0 and is the deployment used throughout the rest of this implementation guide. A legacy Amazon ECS deployment remains available in support-only mode for existing deployments.

Before you begin, review the cost, architecture, network security, and other considerations discussed earlier in this guide.

Prerequisites

To deploy this solution on Amazon EKS, you need:

The bootstrap script handles cluster creation, IAM role wiring (IRSA), private image mirroring, VPC endpoint setup, and Helm chart installation.

Deployment options

Choose one of the following CloudFormation templates to deploy the Amazon EKS infrastructure:

After the CloudFormation stack deploys, run the bootstrap script to install the Migration Assistant Helm chart and configure the Amazon EKS cluster.

Step 1: Download the bootstrap script

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.

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

Run ./aws-bootstrap.sh --help to see every available flag for the version you downloaded.

Bootstrap flag reference

The flags below cover the most common cases. The script always installs the matching Helm chart and Amazon CloudWatch dashboards after the AWS CloudFormation stack succeeds.

Step 2: Deploy into a new or existing VPC

New VPC (latest published release)

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

New VPC pinned to a specific release

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

Existing VPC

./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 already installed the Helm chart and configured the core platform pieces.

Step 3: Verify the deployment

Update your kubeconfig to point at the new Amazon EKS 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 (migration-console-0), the Argo workflow controller, and the Argo server in Running state.

Step 4: Access the Migration Console

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

Once you are in the Migration Console pod, the migration flow is the same regardless of source: confirm the version, load the sample workflow configuration, run a pilot, validate, and then run the full migration. See Use the solution.

Step 5: Use the AWS helpers the deployment created for you

The Amazon EKS deployment provides a default Amazon S3 bucket and snapshot-role wiring so you do not have to build this manually.

Default Amazon S3 bucket

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

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

The default bucket is mounted on the Migration Console pod for direct artifact access.

Snapshot role output

If your workflow needs a snapshot role ARN, look it up from the AWS CloudFormation outputs:

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

Authentication on Amazon EKS

Basic authentication

For sources that require basic authentication, create a Kubernetes secret in the ma namespace and reference it in authConfig.basic.secretName in your workflow configuration:

kubectl create secret generic source-credentials \
  --from-literal=username=SOURCE_USER \
  --from-literal=password=SOURCE_PASSWORD \
  -n ma

AWS Signature Version 4 (SigV4)

For Amazon OpenSearch Service domains, Amazon OpenSearch Serverless collections, and other AWS services that authenticate with SigV4, the Amazon EKS stack uses IAM Roles for Service Accounts (IRSA) to give two sets of pods an AWS identity:

The Migration Console and the migration jobs can authenticate to Amazon OpenSearch Service, Amazon OpenSearch Serverless, and other AWS services without manually distributing long-lived AWS credentials.

Use es as the SigV4 service name when targeting an Amazon OpenSearch Service domain, and aoss when targeting an Amazon OpenSearch Serverless collection. Verify the identity inside the Migration Console pod with aws sts get-caller-identity.

Private or isolated networks

If your subnets do not have direct internet access, the bootstrap script mirrors images into private Amazon 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.0.1

The mirroring step runs from your machine (which has internet access), copies the release images and Helm charts to Amazon ECR, then the Amazon EKS cluster pulls everything through VPC endpoints. The endpoints created are: Amazon ECR API, Amazon ECR Docker, Amazon S3, Amazon CloudWatch Logs, Amazon EFS, AWS STS, and Amazon EKS Auth.

If you prefer to manage VPC endpoints with 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

You can run the bootstrap script in access-only mode after the stack is already deployed:

./aws-bootstrap.sh \
  --skip-cfn-deploy \
  --eks-access-principal-arn arn:aws:iam::123456789012:role/MyCIRole \
  --stage dev \
  --region us-east-2 \
  --skip-console-exec

This grants the principal cluster-admin access to the existing Amazon EKS cluster without redeploying anything else.

Recovery if the bootstrap fails

If AWS CloudFormation fails, check the stack status first:

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 AWS 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

For additional troubleshooting, see Troubleshooting.

Legacy Amazon ECS deployment (support only)

The Amazon ECS deployment has been available since Migration Assistant 1.0. Existing Amazon ECS deployments will continue to function, but customers are encouraged to migrate to the Amazon EKS deployment for access to new features and ongoing support.