Workflow CLI Getting Started

Workflow CLI Getting Started

This guide walks you through configuring and running your first OpenSearch migration using the Workflow CLI.

Prerequisites

• Access to the migration console on your Kubernetes cluster
• Argo Workflows installed and running
• Source and target clusters accessible
• S3 bucket for snapshots (or persistent volume)

Step 1: Access the Migration Console

# For EKS deployments
aws eks update-kubeconfig --region <REGION> --name migration-eks-cluster-<STAGE>-<REGION>

# Connect to the Migration Console pod
kubectl exec -it migration-console-0 -n ma -- /bin/bash

Step 2: Check your version

Identify the installed version to ensure you're using the correct configuration schema:

console --version

Step 3: Load the sample configuration

Use the sample configuration as your starting point. This ensures you're working with the correct schema for your installed version:

workflow configure sample --load

To view the full schema without loading:

workflow configure sample

Step 4: Edit the configuration

workflow configure edit

Customize the loaded sample for your environment:

• Set source and target cluster endpoints
• Configure authentication (see below)
• Set snapshot repository location
• Define which indexes to migrate

View your changes:

workflow configure view

Step 5: Create Kubernetes secrets

Cluster credentials are stored as Kubernetes secrets. Create secrets for each cluster that uses basic authentication:

# Source cluster credentials
kubectl create secret generic source-credentials \
  --from-literal=username=<USERNAME> \
  --from-literal=password=<PASSWORD> \
  -n ma

# Target cluster credentials
kubectl create secret generic target-credentials \
  --from-literal=username=<USERNAME> \
  --from-literal=password=<PASSWORD> \
  -n ma

Reference these secret names in your configuration under authConfig.basic.secretName.

Authentication options

The configuration supports multiple authentication methods:

Method	Use case
basic	Username/password via Kubernetes secret
sigv4	AWS SigV4 for Amazon OpenSearch Service (service: es) or Serverless (service: aoss)
mtls	Mutual TLS with client certificates

For mTLS authentication, create a secret containing the client certificate and key, then reference it in authConfig.mtls.clientSecretName.

Step 6: Submit the workflow

workflow submit

This prints the workflow name and returns immediately—the workflow runs asynchronously in the background.

Step 7: Monitor progress

Using the interactive TUI (recommended)

workflow manage

The TUI lets you watch progress, view logs, and approve steps all in one interface.

Using status commands

workflow status

Status symbols:

• ✓ Succeeded
• ▶ Running
• ○ Pending
• ✗ Failed
• ⟳ Waiting for approval

Step 8: Handle approvals

When a step shows ⟳, it's waiting for your approval to proceed:

# Approve via TUI
workflow manage

# Or approve directly
workflow approve <STEP_NAME>

# Approve multiple steps matching a pattern
workflow approve "*.metadataMigrate"

Step 9: Handle failures

If a step shows ✗ (Failed):

1. Check logs to identify the issue:

   workflow output

2. Fix the configuration if needed:

   workflow configure edit

3. Resubmit the workflow:

   workflow submit

Configuration reference

Key configuration fields (run workflow configure sample for the complete schema):

Field	Description
version	Source cluster only. Format: ES 7.10, OS 2.11
authConfig.basic.secretName	K8s secret with username and password keys
authConfig.sigv4.region	AWS region for SigV4 signing
authConfig.sigv4.service	es for managed OpenSearch, aoss for Serverless
authConfig.mtls.clientSecretName	K8s secret with client cert and key
snapshotRepos.<name>.s3RoleArn	Required for AWS managed service sources
snapshotConfig.repoName	Must match a key in source cluster's snapshotRepos

Configuration fields may change between versions. Always use workflow configure sample to see the current schema.

Quick reference

console --version            # Check installed version
workflow configure sample    # View configuration schema
workflow configure sample --load  # Load sample as starting point
workflow configure edit      # Edit configuration
workflow configure view      # Show configuration
workflow submit              # Submit workflow (async)
workflow manage              # Interactive TUI
workflow status              # Show workflow status
workflow approve <STEP>      # Approve a blocked step
workflow stop                # Stop a running workflow
workflow output              # View workflow logs

Next steps

• Backfill Workflow - Detailed backfill options and tuning
• Workflow CLI Overview - Concepts and command reference
• Troubleshooting - Common issues and solutions