opensearch-project · Naarcha-AWS · Jun 29, 2025 · Jun 29, 2025 · Jun 29, 2025 · Jul 1, 2025
@@ -89,6 +89,9 @@ collections:
   data-prepper: 
     permalink: /:collection/:path/
     output: true
+  migration-upgrade:
+    permalink: /:collection/:path/
+    output: true
   migration-assistant:
     permalink: /:collection/:path/
     output: true
@@ -215,6 +218,12 @@ clients_collection:
         name: Clients
         nav_fold: true
 
+migrations_and_upgrades_collection:
+  collections:
+    migrations-and-upgrades:
+        name: Migrations and upgrades
+        nav_fold: true
+
 migration_assistant_collection:
   collections:
     migration-assistant:
@@ -260,11 +269,17 @@ defaults:
     values:
       section: "benchmark"
       section-name: "Benchmark"
+  -
+    scope:
+      path: "_migrations-and-upgrades"
+    values:
+      section: "migrations-and-upgrades"
+      section-name: "Migrations and upgrades"
   -
     scope:
       path: "_migration-assistant"
     values:
-      section: "migration-assistant"
+      section: "migrations-assistant"
       section-name: "Migration Assistant"
 
 # Enable or disable the site search
@@ -326,6 +341,7 @@ plugins:
   - jekyll-redirect-from
   - jekyll-sitemap
   - jekyll-spec-insert
+  - jekyll-include-cache
 
 # This format has to conform to RFC822
 last-modified-at:
@@ -352,4 +368,4 @@ exclude:
   - .bundle/
   - _site/
   - spec-insert
-  - release-notes
+  - release-notes
@@ -26,4 +26,3 @@ migration_paths:
   - source: "OpenSearch 2.x"
     targets:
       - "OpenSearch 2.x"
-      - "OpenSearch 3.x"
@@ -61,9 +61,9 @@
       </div>  
 
     <div class="home-card">
-      <a href="{{site.url}}{{site.latesturl}}/migration-assistant/" class='card-link'></a>
-        <p class="heading">Migration Assistant</p>
-        <p class="description">Migrate to OpenSearch.</p>
+      <a href="{{site.url}}{{site.latesturl}}/migrations-and-upgrades/" class='card-link'></a>
+        <p class="heading">Modernize Workloads</p>
+        <p class="description">Migration Assistant for OpenSearch and other upgrade and migration options</p>
         <p class="last-link">Documentation &#x2192;</p>
       </div>  
   </div>

@@ -3,6 +3,7 @@ layout: default
 title: Configuration options
 nav_order: 15
 parent: Deploying Migration Assistant
+permalink: /migration-assistant/deploying-migration-assistant/configuration-options/
 ---
 
 # Configuration options

@@ -3,6 +3,7 @@ layout: default
 title: Getting started with data migration
 parent: Deploying Migration Assistant
 nav_order: 10
+permalink: /migration-assistant/deploying-migration-assistant/getting-started-data-migration/
 redirect_from:
   - /upgrade-to/snapshot-migrate/
   - /migration-assistant/getting-started-with-data-migration/

@@ -3,6 +3,7 @@ layout: default
 title: IAM and security groups for existing clusters
 nav_order: 20
 parent: Deploying Migration Assistant
+permalink: /migration-assistant/deploying-migration-assistant/iam-and-security-groups-for-existing-clusters/
 ---
 
 # IAM and security groups for existing clusters

@@ -8,22 +8,24 @@ has_toc: false
 permalink: /migration-assistant/
 redirect_from:
   - /migration-assistant/index/
+  - /migration-assistant/overview/
   - /upgrade-to/index/
   - /upgrade-to/
   - /upgrade-to/upgrade-to/
-tutorial_cards:
-  - heading: "Overview"
-    description: "Get familiar with the key components of Migration Assistant and evaluate your use case."
-    link: "/migration-assistant/overview/"
-  - heading: "Deploying Migration Assistant"
-    description: "Follow step-by-step instructions to deploy Migration Assistant and prepare data for migration."
-    link: "/deploying-migration-assistant/"
-  - heading: "Migration phases"
-    description: "Execute your migration in phases—metadata, backfill, and traffic replay—for a controlled and validated transition."
-    link: "/migration-phases/"
-  - heading: "Migration console"
-    description: "Use CLI commands provided by the migration console to orchestrate and monitor your migration process."
-    link: "/migration-console/"
+  - /upgrade-to/snapshot-migrate/
+items:
+  - heading: "Is Migration Assistant right for you?"
+    description: "Evaluate whether Migration Assistant is right for your use case."
+    link: "/migration-assistant/overview/is-migration-assistant-right-for-you/"
+  - heading: "Key components"
+    description: "Get familiar with the key components of Migration Assistant."
+    link: "/migration-assistant/overview/key-components/"
+  - heading: "Architecture"
+    description: "Understand how Migration Assistant integrates into your infrastructure."
+    link: "/migration-assistant/overview/architecture/"
+  - heading: "Execute your migration in phases"
+    description: "A step-by-step guide for performing a migration."
+    link: "/migration-assistant/migration-phases"
 ---
 
 # Migration Assistant for OpenSearch
@@ -37,8 +39,5 @@ Migration Assistant for OpenSearch aids you in successfully performing an end-to
 
 This user guide focuses on conducting a comprehensive migration involving both existing and live data with zero downtime and the option to back out of a migration.
 
-It's crucial to note that migration strategies are not universally applicable. This guide provides a detailed methodology, based on certain assumptions detailed throughout, emphasizing the importance of robust engineering practices to ensure a successful migration.
-{: .tip }
-
-{% include cards.html cards=page.tutorial_cards %}
+{% include list.html list_items=page.items%}
 
@@ -3,6 +3,7 @@ layout: default
 title: Accessing the migration console
 nav_order: 35
 parent: Migration console
+permalink: /migration-assistant/migration-console/accessing-the-migration-console/
 ---
 
 # Accessing the migration console

@@ -3,6 +3,7 @@ layout: default
 title: Command reference
 nav_order: 40
 parent: Migration console
+permalink: /migration-assistant/migration-console/migration-console-commands-reference/
 ---
 
 # Migration console command reference

@@ -0,0 +1,42 @@
+---
+layout: default
+title: Accessing the Migration Console
+parent: Deploying Migration Assistant
+nav_order: 10
+redirect_from:
+---
+# Accessing the Migration Console
+
+The Migrations Assistant deployment includes an ECS task that hosts tools to run different phases of the migration and check the progress or results of the migration.
+
+## SSH into the Migration Console
+
+Following the AWS Solutions deployment, the bootstrap box contains a script that simplifies access to the migration console through that instance.
+
+To access the Migration Console, use the following commands:
+
+```sh
+export STAGE=dev
+export AWS_REGION=us-west-2
+/opensearch-migrations/deployment/cdk/opensearch-service-migration/accessContainer.sh migration-console ${STAGE} ${AWS_REGION}
+```
+When opening the console a message will appear above the command prompt, Welcome to the Migration Assistant Console.
+<details>
+
+<summary>
+<b>SSH from any machine into Migration Console</b>
+</summary>
+
+On a machine with the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) ↗ and the [AWS Session Manager Plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) ↗, you can directly connect to the migration console. Ensure you've run `aws configure` with credentials that have access to the environment.
+
+Use the following commands:
+
+```shell
+export STAGE=dev
+export SERVICE_NAME=migration-console
+export TASK_ARN=$(aws ecs list-tasks --cluster migration-${STAGE}-ecs-cluster --family "migration-${STAGE}-${SERVICE_NAME}" | jq --raw-output '.taskArns[0]')
+aws ecs execute-command --cluster "migration-${STAGE}-ecs-cluster" --task "${TASK_ARN}" --container "${SERVICE_NAME}" --interactive --command "/bin/bash"
+```
+</details>
+
+> **Note:** Typically, `STAGE` is `dev`, but this may vary based on what the user specified during deployment.
@@ -0,0 +1,76 @@
+---
+layout: default
+title: Assess
+nav_order: 1
+parent: Migration phases
+redirect_from:
+  - /migration-assistant/migration-phases/assessing-your-cluster-for-migration/
+---
+
+# Assessing your cluster for migration
+
+The goal of the Migration Assistant is to streamline the process of migrating from one location or version of Elasticsearch/OpenSearch to another. However, completing a migration sometimes requires resolving client compatibility issues before they can communicate directly with the target cluster.
+
+
+## Understanding breaking changes
+
+Before performing any upgrade or migration, you should review any breaking changes that might exist between version because there may be changes required in order for clients to connect to the new cluster. Use the following tool by selecting the versions in your migration path. The tool will respond with any breaking changes you should note when migrating:
+
+<link rel="stylesheet" href="{{site.url}}{{site.baseurl}}/migration-assistant/assets/css/breaking-changes-selector.css">
+
+<div class="breaking-changes-selector">
+  <h4>Find a list of breaking changes for your migration path</h4>
+
+  <div>
+    <label for="source-version">Source:</label>
+    <select id="source-version">
+      <option value="">Select</option>
+      <!-- Source versions will be populated by JavaScript -->
+    </select>
+
+    <label for="target-version">Target:</label>
+    <select id="target-version">
+      <option value="">Select</option>
+      <!-- Target versions will be populated by JavaScript -->
+    </select>
+  </div>
+
+  <div>
+    <label>Include Optional Components:</label><br>
+    <!-- Components will be populated by JavaScript -->
+    <span id="component-checkboxes"></span>
+  </div>
+
+  <div id="breaking-changes-results"></div>
+</div>
+
+<div id="migration-data" 
+     data-migration-paths="{{ site.data.migration-assistant.valid_migrations.migration_paths | jsonify | escape }}"
+     data-breaking-changes="{{ site.data.migration-assistant.breaking-changes.breaking_changes | jsonify | escape }}"
+     style="display:none;"></div>
+
+<script type="module" src="{{site.url}}{{site.baseurl}}/migration-assistant/assets/js/breaking-changes-index.js"></script>
+
+## Impact of data transformations
+
+Any time you apply a transformation to your data, such as:
+
+- Changing index names
+- Modifying field names or field mappings
+- Splitting indices with type mappings
+
+These changes might need to be reflected in your client configurations. For example, if your clients are reliant on specific index or field names, you must ensure that their queries are updated accordingly.
+
+We recommend running production-like queries against the target cluster before switching over actual production traffic. This helps verify that the client can:
+
+- Communicate with the target cluster
+- Locate the necessary indices and fields
+- Retrieve the expected results
+
+For complex migrations involving multiple transformations or breaking changes, we highly recommend performing a trial migration with representative, non-production data (e.g., in a staging environment) to fully test client compatibility with the target cluster.
+
+## Supported transformations
+
+The following [transformations]({{site.url}}{{site.baseurl}}/migration-assistant/migration-phases/live-traffic-migration/using-traffic-replayer/#transformations) are included in Migration Assistant. They can be enabled, combined, and configured to customize a migration for your use case. To request additional Migration Assistant transformations , create a GitHub issue [in the OpenSearch migrations repository](https://github.com/opensearch-project/opensearch-migrations/issues).
+
+- [Type mapping deprecation]({{site.url}}{{site.baseurl}}/migration-assistant/migration-phases/planning-your-migration/handling-type-mapping-deprecation/)
@@ -1,107 +1,15 @@
 ---
 layout: default
-title: Backfill
-nav_order: 90
+title: Migrate Data
+nav_order: 6
 parent: Migration phases
+permalink: /migration-assistant/migration-phases/backfill/
 ---
 
 # Backfill
 
 After the [metadata]({{site.url}}{{site.baseurl}}/migration-assistant/migration-phases/migrating-metadata/) for your cluster has been migrated, you can use capture proxy data replication and snapshots to backfill your data into the next cluster.
 
-## Capture proxy data replication
-
-If you're interested in capturing live traffic during your migration, Migration Assistant includes an Application Load Balancer for routing traffic to the capture proxy and the target cluster. Upstream client traffic must be routed through the capture proxy in order to replay the requests later. Before using the capture proxy, remember the following:
-
-* The layer upstream from the Application Load Balancer is compatible with the certificate on the Application Load Balancer listener, whether it's for clients or a Network Load Balancer. The `albAcmCertArn` in the `cdk.context.json` may need to be provided to ensure that clients trust the Application Load Balancer certificate.
-* If a Network Load Balancer is used directly upstream of the Application Load Balancer, it must use a TLS listener.
-* Upstream resources and security groups must allow network access to the Migration Assistant Application Load Balancer.
-
-To set up the capture proxy, go to the AWS Management Console and navigate to **EC2 > Load Balancers > Migration Assistant Application Load Balancer**. Copy the Application Load Balancer URL. With the URL copied, you can use one of the following options.
-
-
-### If you are using **Network Load Balancer → Application Load Balancer → Cluster**
-
-1. Ensure that ingress is provided directly to the Application Load Balancer for the capture proxy.
-2. Create a target group for the Migration Assistant Application Load Balancer on port `9200`, and set the health check to `HTTPS`.
-3. Associate this target group with your existing Network Load Balancer on a new listener for testing.
-4. Verify that the health check is successful, and perform smoke testing with some clients through the new listener port.
-5. Once you are ready to migrate all clients, detach the Migration Assistant Application Load Balancer target group from the testing Network Load Balancer listener and modify the existing Network Load Balancer listener to direct traffic to this target group.
-6. Now client requests will be routed through the proxy (once they establish a new connection). Verify the application metrics.
-
-### If you are using **Network Load Balancer → Cluster**
-
-If you do not want to modify application logic, add an Application Load Balancer in front of your cluster and follow the **Network Load Balancer → Application Load Balancer → Cluster** steps. Otherwise:
-
-1. Create a target group for the Application Load Balancer on port `9200` and set the health check to `HTTPS`.
-2. Associate this target group with your existing Network Load Balancer on a new listener.
-3. Verify that the health check is successful, and perform smoke testing with some clients through the new listener port.
-4. Once you are ready to migrate all clients, deploy a change so that clients hit the new listener.
-
-
-### If you are **not using an Network Load Balancer**
-
-If you're only using backfill as your migration technique, make a client/DNS change to route clients to the Migration Assistant Application Load Balancer on port `9200`.
-
-
-### Kafka connection
-
-After you have routed the client based on your use case, test adding records against HTTP requests using the following steps:
-
-In the migration console, run the following command:
-
-```bash
-console kafka describe-topic-records
-```
-{% include copy.html %}
-
-Note the records in the logging topic.
-
-After a short period, execute the same command again and compare the increased number of records against the expected HTTP requests.
-
-## Creating a snapshot
-
-Create a snapshot for your backfill using the following command:
-
-```bash
-console snapshot create
-```
-{% include copy.html %}
-
-To check the progress of your snapshot, use the following command:
-
-```bash
-console snapshot status --deep-check
-```
-{% include copy.html %}
-
-Depending on the size of the data in the source cluster and the bandwidth allocated for snapshots, the process can take some time. Adjust the maximum rate at which the source cluster's nodes create the snapshot using the `--max-snapshot-rate-mb-per-node` option. Increasing the snapshot rate will consume more node resources, which may affect the cluster's ability to handle normal traffic.
-
-## Backfilling documents to the source cluster
-
-From the snapshot you created of your source cluster, you can begin backfilling documents into the target cluster. Once you have started this process, a fleet of workers will spin up to read the snapshot and reindex documents into the target cluster. This fleet of workers can be scaled to increased the speed at which documents are reindexed into the target cluster.
-
-### Checking the starting state of the clusters
-
-You can check the indexes and document counts of the source and target clusters by running the `cat-indices` command. This can be used to monitor the difference between the source and target for any migration scenario. Check the indexes of both clusters using the following command:
-
-```shell
-console clusters cat-indices
-```
-{% include copy.html %}
-
-You should receive the following response:
-
-```shell
-SOURCE CLUSTER
-health status index       uuid                   pri rep docs.count docs.deleted store.size pri.store.size
-green  open   my-index WJPVdHNyQ1KMKol84Cy72Q   1   0          8            0     44.7kb         44.7kb
-
-TARGET CLUSTER
-health status index                        uuid                   pri rep docs.count docs.deleted store.size pri.store.size
-green  open   .opendistro_security         N3uy88FGT9eAO7FTbLqqqA   1   0         10            0     78.3kb         78.3kb
-```
-
 ### Starting the backfill
 
 Use the following command to start the backfill and deploy the workers: