Deploy Migration Assistant on other Kubernetes platforms
Use this path to run Migration Assistant on any Kubernetes platform other than the managed cloud paths that have dedicated tooling (Amazon Elastic Kubernetes Service (Amazon EKS) and Google Kubernetes Engine (GKE)). This includes self-managed clusters on any cloud (for example, your own cluster on AWS or Google Cloud Platform (GCP)), other managed Kubernetes services, self-managed platforms such as Rancher or OpenShift, and local evaluation. Unlike the managed cloud paths, this path requires you to provision the surrounding platform infrastructure yourself.
To use a recommended production path with dedicated tooling, see Deploy Migration Assistant on Amazon EKS for AWS or Deploy Migration Assistant on Google Kubernetes Engine for GCP.
Recommended use cases
Use this path in the following cases:
- You already run a self-managed Kubernetes platform and are comfortable configuring cluster identity, storage, logging, and registry access.
- You self-manage Kubernetes on a cloud such as AWS or GCP and prefer to configure the platform integrations yourself.
- You are testing Migration Assistant locally using
minikubeorkind.
Your responsibilities
On this path, Migration Assistant runs the same workflow engine as every other path, but it does not automatically provision or configure the surrounding platform. You must supply the following components yourself:
- Cluster identity for authenticated source or target clusters (for example, AWS IAM roles for a Signature Version 4 target or a GCP service account configured using Workload Identity).
- Image access for isolated networks, such as copying the images into your own registry.
- Snapshot storage and the access permissions the migration pods need for reading and writing to the snapshot storage (for example, an Amazon S3 or Google Cloud Storage bucket).
- Logging and metrics integration with your platform’s observability stack.
- Storage classes and node auto scaling tuned for your platform.
The migration engine, workflow model, and console experience are identical to the managed cloud paths.
Prerequisites
Before you begin, ensure that you have the following:
- Kubernetes 1.24 or later.
kubectlconfigured for your cluster.- Helm 3.
- Network connectivity from the cluster to the source and target clusters.
- A StorageClass with dynamic provisioning.
Local evaluation with Minikube
For local testing, use the repository’s helper script. This is the fastest way to experience the workflow model before preparing a production platform.
Prerequisites for local builds
Local builds require the following prerequisites:
- JDK 11–17 (
localTesting.shbuilds container images from source) - Docker
minikube,kubectl, and Helm 3- At least 8 vCPUs and 12 GB of RAM available to Docker.
The Migration Assistant images are large (several GB combined). If Docker does not have enough memory, the script fails with unclear error messages.
Step 1: Clone a release tag
Clone a release tag:
git clone --branch 3.2.1 https://github.com/opensearch-project/opensearch-migrations
cd opensearch-migrations/deployment/k8s
Step 2: Run the local testing script
Run the local testing script:
./localTesting.sh
The script starts Minikube, builds the container images, installs the Helm chart, and deploys test source and target clusters. Use this path for learning and validation, not as a production blueprint.
Verify the deployment
To verify that the pods are running and access the Migration Console, run the following commands:
kubectl get pods -n ma
kubectl exec -it migration-console-0 -n ma -- /bin/bash
Production deployment on other Kubernetes platforms
For a production deployment on another Kubernetes platform, follow these steps.
Step 1: Choose an image source
The Migration Assistant images are published to a public container registry (Amazon Public ECR, public.ecr.aws/opensearchproject/...), which you can pull from on any platform. The Helm chart’s default images.*.repository values are short development names that cannot be pulled directly, so you must either point the chart at the public images or copy them into your own registry.
The following options are available:
- Pull from the public registry (simplest): Use the
valuesEks.yamlvalues file included in the chart, which contains the fullimages.*.repositoryandimages.*.tagoverrides for the public images. Despite its name, this file only configures the published image references and works on any Kubernetes platform. - Copy the images into your own registry: Use this option for isolated networks. Then configure the chart to reference your private registry by passing your own values file.
The exact image tags must match the Migration Assistant release you want to run. You can find released versions at the GitHub releases page.
Step 2: Clone the release tag
Clone the release tag you want to install:
git clone --branch <RELEASE_TAG> https://github.com/opensearch-project/opensearch-migrations
cd opensearch-migrations/deployment/k8s
For example, --branch 3.2.1 pins to that release. Building or installing from main is not recommended for production use.
Step 3: Create the namespace
Create the Migration Assistant namespace:
kubectl create namespace ma
Step 4 (Optional): Create Kubernetes secrets
If your source or target requires basic authentication, store the credentials in Kubernetes secrets and reference those secret names in the workflow configuration. The process is the same on every deployment path. To create a secret for the source and target, run the following commands:
kubectl create secret generic source-credentials \
--from-literal=username=<SOURCE_USER> \
--from-literal=password=<SOURCE_PASSWORD> \
-n ma
kubectl create secret generic target-credentials \
--from-literal=username=<TARGET_USER> \
--from-literal=password=<TARGET_PASSWORD> \
-n ma
Step 5: Install the Helm chart
The chart is at charts/aggregates/migrationAssistantWithArgo. Use one of the values files shipped in the chart to provide the public image references:
# For local Minikube/kind testing
helm install ma -n ma charts/aggregates/migrationAssistantWithArgo \
--create-namespace \
-f charts/aggregates/migrationAssistantWithArgo/valuesForLocalK8s.yaml
# For any other Kubernetes cluster pulling from the public registry
helm install ma -n ma charts/aggregates/migrationAssistantWithArgo \
--create-namespace \
-f charts/aggregates/migrationAssistantWithArgo/valuesEks.yaml
If your nodes cannot reach public registries, copy the images into a private registry first and copy valuesEks.yaml into your own values file with the registry prefix updated.
Step 6: Verify that the platform is running
Verify that the platform is running:
kubectl get pods -n ma
You should see the Migration Console, the Argo workflow controller, and the Argo server in Running state.
Step 7: Access the Migration Console
Access the Migration Console:
kubectl exec -it migration-console-0 -n ma -- /bin/bash
After accessing the console, the remaining steps are identical across deployment paths: load the sample configuration, edit it, run a pilot migration, and then run the full workflow.
Authentication on other Kubernetes platforms
Migration Assistant supports the following authentication methods on other Kubernetes platforms.
Basic authentication
Configure basic authentication by creating Kubernetes secrets and referencing them in authConfig.basic.secretName.
Use AWS Signature Version 4 for Amazon OpenSearch Service or Serverless NextGen
AWS Signature Version 4 is supported by the workflow configuration, but other Kubernetes platforms do not automatically create AWS pod identity for you.
If your source or target uses Amazon OpenSearch Service or OpenSearch Serverless NextGen, you must make AWS credentials available to two sets of pods:
- The Migration Console pod (
migration-console-0), running under themigration-console-access-roleservice account, which runs CLI commands such asconsole clusters connection-check - The Argo workflow executor pods, running under the
argo-workflow-executorservice account, which perform the actual migration steps.
On EKS, pod identity is configured automatically. On other Kubernetes platforms, including self-managed clusters on AWS, you must configure credential injection yourself. The same principle applies to other clouds’ managed identity: if you self-manage on GCP and rely on Workload Identity for a service, you must configure that binding yourself rather than having it provisioned for you.
The chart includes a Kyverno policy for local development that mounts AWS credentials into certain pods. Do not use it in production.
To use AWS Signature Version 4 without configuring credential injection manually, use Deploy Migration Assistant on Amazon EKS, which configures EKS Pod Identity automatically.
Next steps
- Open the Migration Console and run
console --version. - Load the sample workflow by running
workflow configure sample --load. - Run
console clusters connection-checkbefore submitting a workflow. - Configure and run your first migration by following Using the Workflow CLI.