Workflow CLI
The Workflow CLI is the operator interface for Migration Assistant. It provides a repeatable way to run migrations without manually chaining individual infrastructure commands.
Migration Assistant runs each migration as an Argo Workflows job. Argo is a Kubernetes-native workflow engine that schedules each step (snapshot, metadata migration, backfill, replay, validation) as a pod and tracks its status. You don’t need to know Argo to operate Migration Assistant; the Workflow CLI is the layer you interact with.
Design principles
Migration Assistant uses Kubernetes and workflows to achieve the following:
- Describe the migration once instead of typing one-time commands.
- Let the platform orchestrate long-running steps.
- Make progress visible.
- Pause at approval gates when human validation matters.
- Resubmit the workflow safely after configuration changes without rebuilding the environment.
Standard operator workflow
Most migrations follow the same pattern:
- Open the Migration Console.
- Verify the installed version by running
console --version. - Load the version-matched sample config by running
workflow configure sample --load. - Edit only the fields that describe your environment and migration path.
- Validate connectivity by running
console clusters connection-check. - Submit a pilot workflow.
- Watch progress and approvals by running
workflow manage. - Validate the pilot, then run the full migration.
Core commands
The Workflow CLI groups commands into the following sections.
Console commands
The console CLI groups operations by component. The workflow CLI orchestrates a full migration; the console CLI is what you use to inspect or manually drive a single component during validation and troubleshooting.
Cluster inspection commands
| Command | Description |
|---|---|
console --version | Confirms which schema and behavior your console is running. |
console clusters connection-check | Verifies the console can reach and authenticate to source and target clusters. |
console clusters connection-check --cluster source|target|proxy | Restricts the check to one cluster. |
console clusters cat-indices [--refresh] [--cluster source|target|proxy] | Lists indexes on one or both clusters. |
console clusters curl source /_cat/indices?v | Issues a direct API request against the named cluster (path is positional). |
console clusters curl target /_search -X POST --json '{"query":{"match_all":{}}}' | Sends a POST request with a JSON body. |
console clusters clear-indexes --cluster target --acknowledge-risk | Destructive. Deletes all indexes on the named cluster. |
Metrics and Apache Kafka commands
| Group | Commands |
|---|---|
console metrics | list, get-data |
console kafka | create-topic, list-topics, delete-topic, describe-consumer-group, list-consumer-groups, describe-topic-records |
Configuration commands
| Command | Why you use it |
|---|---|
workflow configure sample | Shows the sample schema for your installed version |
workflow configure sample --load | Loads that sample as your starting point |
workflow configure edit | Opens the workflow config in your editor ($EDITOR, defaults to vi) |
workflow configure edit --stdin | Reads YAML from stdin instead of opening an editor—useful in scripts and CI |
workflow configure view | Prints the current config |
workflow configure clear | Clears the current config and lets you start over |
Execution and monitoring commands
| Command | Description |
|---|---|
workflow submit | Starts the migration workflow (auto-stops and replaces an existing one with the same name). |
workflow submit --wait --timeout 300 | Submits and blocks until the workflow completes or the timeout is reached. |
workflow manage | Primary interface for monitoring, approvals, and logs (interactive TUI). |
workflow status | Shows the current workflow tree in a non-interactive form. |
workflow status --all | Shows running and completed workflows. |
workflow status --live-status | Adds live snapshot/backfill status checks per node. |
workflow log all | Shows logs across workflow pods (uses pod labels to find them). |
workflow log all --follow | Streams logs live (uses stern internally). |
workflow log filter -l source=src,target=tgt | Filters by label selector. |
workflow approve step <PATTERN> [<PATTERN> ...] | Approves pending gates that match exact names or globs (for example, *.evaluateMetadata). |
workflow reset | Lists migration CRDs and lets you delete them safely. Use this instead of kubectl delete workflow .... |
workflow reset --all | Deletes all migration CRDs (capture proxies are protected by default; add --include-proxies to remove them). |
workflow reset <NAME> --cascade | Deletes a specific resource and its dependents. |
workflow util completions <bash|zsh|fish> | Generates a shell completion script. |
The workflow manage command
The workflow manage command opens a full-screen terminal user interface (TUI) for monitoring and managing workflow execution. It provides the following capabilities:
- Viewing step-by-step workflow status (waiting, running, or failed).
- Opening logs without switching tools.
- Approving gated steps when they are ready.
Approval gates
Not every migration step should run without human review. Approval gates let the workflow stop at meaningful checkpoints so you can validate before continuing.
Typical approval points include transitions after metadata migration, backfill milestones, and cutover-sensitive steps. To view and approve gates, run the following commands:
workflow manage
workflow approve step <STEP_NAME>
Status symbols
The following table describes the symbols displayed in workflow status output.
| Symbol | Meaning |
|---|---|
✓ | Succeeded |
▶ | Running |
○ | Pending |
✗ | Failed |
⟳ | Waiting for approval |
Version-matched sample configuration
The workflow schema changes between releases. Always load the sample configuration that matches your installed version rather than writing the configuration manually. To load the sample and edit it, run the following commands:
console --version
workflow configure sample --load
workflow configure edit
Schema-aware editing
Each release publishes a workflowMigration.schema.json asset. The console also keeps the active schema locally so your editor and validation can stay aligned with the installed version.
On the Migration Console, the schema is available at:
/root/.workflowUser.schema.json
The CLI uses this schema automatically when editing and validating configurations, so no separate download is required.
Related documentation
| Topic | Link |
|---|---|
| First workflow | Using the Workflow CLI |
| Deployment choice | Choose your deployment |
| Elasticsearch 6.8 to OpenSearch 3.5 | Playbook |
| Amazon OpenSearch Service to Serverless | Playbook |