How to pre-install MGN replication agents and migrate with AWS Transform

Introduction

AWS Transform for migrations is an AI-assisted migration service that orchestrates the end-to-end journey of moving workloads to AWS — from discovery and planning to server rehosting. For the rehost step, it uses AWS Transform MGN (formerly AWS Application Migration Service), which performs continuous block-level replication from source servers to AWS and launches them as native Amazon EC2 instances.

AWS Transform requires the MGN replication agent to be installed on each source server to initiate data replication. This can be done in multiple ways; manually via SSH/RDP, through the MGN Connector for automated at-scale deployment, or using your organization's existing software distribution tooling such as SCCM, Ansible, or Tanium.

In some migration scenarios, customers prefer to install the MGN agent ahead of time, getting replication running early and then use AWS Transform later to plan waves and orchestrate test launches and cutover. This article walks through that approach; preinstalling the agent on your source servers, so they are already replicating when you engage with AWS Transform for migration.

Before you begin, ensure you:

• Identify your target AWS account(s) — the account where each server will be migrated to, as this determines where replication occurs and which credentials to use
• Initialize MGN in the target account and Region
• Define the replication settings on the target accounts
• Note the MGN service quota of 150 actively replicating servers per region per account. For larger migrations, you can request a quota increase or stagger replication using the --no-replication flag

The MGN Agent user-provided ID

The user-provided-id is an optional parameter you can pass during MGN agent installation. It is a custom identifier (up to 256 characters) that you assign to a source server — typically the server hostname, a CMDB reference, or another name meaningful to your organization.

MGN uses the user-provided ID to consistently recognize the source server and avoid duplication when importing inventory. AWS Transform relies on this identifier to sync with and map your source servers to its migration workflow. When you later engage with AWS Transform for wave planning and orchestration, it uses the user-provided ID to identify which servers are already replicating and to associate them with your migration plan.

Ways to set the MGN Agent user-provided ID

Option A: During agent installation

We recommend setting the user-provided ID at the time of agent installation. This ensures that as soon as the server appears in MGN, it is already identifiable and ready to be picked up by AWS Transform.

Example:

sudo ./aws-replication-installer-init \
  --region us-east-1 \
  --aws-access-key-id <ACCESS_KEY> \
  --aws-secret-access-key <SECRET_KEY> \
  --user-provided-id "webserver-prod-01"

You can run the installer manually on each source server by connecting directly (SSH for Linux, RDP for Windows) or distribute it at scale using your organization's existing third-party tooling such as SCCM, Ansible, or any other configuration management tool that can execute commands on your servers.

You can also dynamically set the identifier to get the server's hostname, avoiding the need to hardcode the value and for scalability to install across multiple servers:

• Linux: --user-provided-id $(hostname)
• Windows (PowerShell): --user-provided-id $env:COMPUTERNAME
• Windows (CMD): --user-provided-id %COMPUTERNAME%

Installing without starting replication:

By default, replication begins automatically after agent installation. To install the agent without starting replication, pass the --no-replication flag.

This is useful when you want to control when the 90-day free replication window begins, when networking to the staging area is not yet finalized, or when you need to stay within the limit of 150 actively replicating servers per account. For large-scale migrations with more than 150 servers, you can install agents across all servers using --no-replication and then start replication in batches as each wave approaches migration.

You can start replication from the MGN console (Replication menu → "Start Replication"), via the AWS CLI start-replication command, or directly from within your AWS Transform migration job.

Option B: After installation via the UpdateSourceServer API

If agents have already been installed without a user-provided ID or if you need to update the identifier — you can set it post-install using the UpdateSourceServer API. This is useful when MGN agents were deployed before the migration plan was finalized, or when a different team handles agent installation and doesn't have the naming convention at deployment time.

Example:

aws mgn update-source-server \
  --source-server-id s-1234567890abcdef0 \
  --user-provided-id "webserver-prod-01"

You can run this from AWS CLI, AWS CloudShell or programmatically using scripts with AWS SDKs such as Python Boto3.

Using AWS Transform to complete the migration

Once your source servers are replicating with the user-provided ID set, you can engage AWS Transform to orchestrate the remaining migration lifecycle — wave planning, testing, and cutover.

AWS Transform automatically correlates your replicating servers with the source inventory using the user-provided ID, FQDN, or hostname. This means servers you preinstalled will appear in the Transform workflow as already replicating, and you can proceed directly to migration orchestration.

The workflow within AWS Transform proceeds as follows:

1. Configure migration defaults — Set your Amazon EC2 launch template settings, and recommendation preferences across target accounts.

2. Set up the migration wave — AWS Transform confirms your target accounts, verifies MGN initialization, and checks resource tagging. For servers that are already replicating (preinstalled agents), AWS Transform detects that source servers exist and provides a direct link to the tagging page where you can tag them with the following required tags:

   • CreatedBy: AWSTransform
   • ATWorkspace: <workspace_id>

3. Validate and confirm inventory — AWS Transform generates an inventory file for review. This file includes a mgn:server:user-provided-id column. The value in this column must exactly match the user-provided ID on the source server in MGN. This is how AWS Transform correlates each row in the inventory with the corresponding source server already replicating in MGN. If needed, you can update this column in the inventory file or use Option B (UpdateSourceServer API) to adjust the user-provided ID on the source server side.

4. Monitor replication — AWS Transform tracks replication status across your source servers. If replication is already complete and ready for testing, you can proceed directly to testing. If you installed agents with --no-replication, you can start replication from within the AWS Transform migration job. AWS Transform notifies you when servers are ready for testing.

5. Launch test instances — AWS Transform orchestrates test launches. You validate the migrated EC2 instances.

6. Perform cutover — Once testing is complete, coordinate the final cutover from AWS Transform.

Conclusion

Pre-installing the MGN replication agent gives you the flexibility to decouple agent deployment from migration orchestration. Your infrastructure team can roll out agents early using existing tools and processes while migration planning continues in parallel. When you're ready, AWS Transform picks up the already-replicating servers and handles the rest: wave planning, test launches, and cutover. This approach reduces the overall migration window, allows teams to work independently, and ensures servers are fully synced by the time you're ready to migrate.

For more information, see:

• Installing the AWS Replication Agent
• Migrate servers with AWS Transform
• UpdateSourceServer API reference