Deploying to Kubernetes

Deploying to Kubernetes

This guide covers deploying Migration Assistant to a generic Kubernetes cluster using Helm charts. For AWS EKS deployment (recommended for AWS users), see Deploying to EKS.

Prerequisites

• Kubernetes cluster: Version 1.24 or later
• Helm 3: Installed and configured
• kubectl: Configured to access your cluster
• Network access: Connectivity from the cluster to source and target clusters
• Persistent storage: StorageClass with dynamic provisioning for state management

Installation

Migration Assistant is deployed via Helm charts from the opensearch-migrations repository.

Step 1: Clone the repository

git clone https://github.com/opensearch-project/opensearch-migrations
cd opensearch-migrations/deployment/k8s

Step 2: Review deployment documentation

See the deployment/k8s/README.md in the repository for:

• Helm chart configuration options
• Required values and customization
• Environment-specific setup

Step 3: Create the namespace

kubectl create namespace ma

Step 4: Create authentication secrets

Before deploying, create Kubernetes secrets for cluster authentication.

Basic authentication:

kubectl create secret generic <secret-name> \
  --from-literal=username=<user> \
  --from-literal=password=<pass> \
  -n ma

mTLS authentication:

kubectl create secret generic <secret-name> \
  --from-file=client.crt=<path-to-cert> \
  --from-file=client.key=<path-to-key> \
  -n ma

Step 5: Deploy with Helm

helm install migration-assistant ./charts/migration-assistant -n ma -f values.yaml

Step 6: Verify deployment

kubectl get pods -n ma

Expected output:

NAME                                    READY   STATUS    RESTARTS   AGE
argo-workflows-server-xxxxxxxxx-xxxxx   1/1     Running   0          5m
argo-workflows-workflow-controller-xx   1/1     Running   0          5m
migration-console-0                     1/1     Running   0          5m

Step 7: Access the Migration Console

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

You should see:

Welcome to the Migration Assistant Console

Authentication configuration

Configure authentication in your workflow configuration. Run workflow configure sample on the Migration Console to see the exact schema for your installed version.

Authentication types

Type	Use case	Secret requirements
Basic	Username/password auth	Secret with username and password keys
SigV4	AWS managed OpenSearch/Elasticsearch	IAM role (no secret needed)
mTLS	Certificate-based auth	Secret with client.crt and client.key

Creating secrets for each auth type

Basic auth:

kubectl create secret generic source-credentials \
  --from-literal=username=admin \
  --from-literal=password=<password> \
  -n ma

mTLS:

kubectl create secret generic source-mtls \
  --from-file=client.crt=/path/to/client.crt \
  --from-file=client.key=/path/to/client.key \
  -n ma

Reference these secret names in your workflow configuration under the appropriate authConfig section.

Network requirements

From	To	Port	Purpose
Migration Console	Source cluster	9200/443	Source cluster access
Migration Console	Target cluster	9200/443	Target cluster access
Migration Console	Snapshot storage	443	S3/snapshot repository
Workflow pods	Source cluster	9200/443	Migration operations
Workflow pods	Target cluster	9200/443	Migration operations

Troubleshooting

Pods not starting

kubectl describe pod <pod-name> -n ma
kubectl logs <pod-name> -n ma

Cannot connect to clusters

Verify connectivity from the migration console:

kubectl exec -it migration-console-0 -n ma -- curl -k https://<cluster-endpoint>:9200

Common issues:

• Network policies: Ensure egress to cluster endpoints is allowed
• DNS resolution: Verify cluster hostnames resolve correctly
• Firewall rules: Check that ports 9200/443 are accessible

Next steps

1. Workflow CLI Overview — Learn about the Workflow CLI concepts
2. Workflow CLI Getting Started — Run your first migration
3. Backfill Workflow — Configure and execute document backfill