Best Practice Guide: Google Workspace to Google Workspace (Domain-Switch) Migrations

Domain-Switch Scenarios

Scenario 1: The Domain Name is NOT Migrating

If migrating to a new domain name (e.g., source.com to destination.com), execute a standard migration.

Scenario 2: The Domain Name IS Migrating

If source.com will become the new primary domain at the destination, a phased migration is required. A domain cannot exist in two active Google instances simultaneously.

Prerequisites

• Destination Google Workspace Instance: Configured with a temporary primary domain (e.g., temp.destination.com).
• Temporary Source Secondary Domain: Configured at the source (e.g., temp.source.com) to facilitate user renaming during the transition.
• CloudM Migrate License: Assign licenses to the temporary destination domain. Licenses are assigned by ID; updating Import Names during delta runs does not consume additional licenses.
• Domain & Address Replacements: Configure replacements for routing between source and destination.
• Service Accounts: Configure API access on both the source and destination. Reference Service Account and API Setup.

Planning & Migration Strategy

1. Bulk Administrative Tooling

The Google Workspace Admin Console has limitations for high-volume operations. For bulk user renaming and alias removals during a cutover window, manual methods are slow and introduce risk.

We recommend using GAM (Google Apps Manager). GAM is a command-line tool that interacts directly with Google APIs to execute bulk administrative tasks. Test scripts on a subset of users before the migration date to verify syntax and API authorization.

2. Mail Flow & MX Records

CloudM Migrate does not affect live mail flow. Manage MX record cutovers manually between the bulk migration and the final delta sync. Ensure all primary addresses in the CloudM item list are active and reachable during the respective migration phase.

3. Calendar Migration Strategy

Aligning with the Standard Migration Strategy, all calendar data should be migrated during the final Delta / Go-Live phase.

• Event Immutability: Migrating calendars during the final cutover prevents data inconsistencies. Migrated calendar events are generally immutable; running early passes means subsequent updates to source events will not sync to the destination.
• Visibility for Shared Users: Secondary calendars migrate successfully and retain their data. However, applying sharing permissions (ACLs) does not automatically pin the calendar to the UI for shared users or delegates. To resolve this, navigate to Configuration > Advanced settings > Calendar and enable Send calendar sharing notifications so sharees receive an email link to subscribe. Reference the Google Workspace Watchpoints for more details.

Execution Workflow

Step 1: Configure Initial Migration

Configure the batch to migrate from source.com to temp.destination.com.

• Configuration > General > Review domain names: Set to source.com and temp.destination.com.
• Configuration > Destination > Email: Disable Modify sent address.
• Configuration > Advanced settings > Address replacement: Configure required address replacements.

Step 2: Bulk Migration (Historic Data)

Execute the bulk migration for historic Email and Drive data. Do not include Calendar data in this pass.

Step 3: Source Domain Removal

1. Change the Primary Domain at the source to a secondary domain (e.g., temp.source.com).
2. Rename Source Users: Change user@source.com to user@temp.source.com.
3. Remove Aliases: Strip all @source.com aliases from all users and groups.
4. Remove Domain: Delete source.com from the source Google Admin Console.

Step 4: Destination Domain Integration

Add source.com to the destination Google Workspace instance.

Step 5: Delta Reconfiguration

1. Rename Destination Users: Update users to user@source.com.
2. Source Connection: Update Domain Name and Admin Username to temp.source.com.
3. Items List: Update Import Names to reflect user@source.com.
4. Configuration > General > Review domain names: Update domain replacement values.
5. Configuration > Destination > Email: Enable Modify sent address.
6. Configuration > Destination > Shared Drive: Enable Repatch existing permissions.
7. Configuration > Advanced settings > Address replacement: Update the Address Replacements CSV.

Step 6: Switch MX Records

Update MX records at the domain registrar to point to the destination Google Workspace.

• Immediate Mail Flow: Incoming mail routes directly to the new destination tenant.
• Final Synchronization: The subsequent Delta Migration (Step 7) captures data delivered to the source during the DNS propagation window.

Step 7: Run Delta / Cutover Migration

Initiate the final sync. Include Calendar data in this pass, alongside delta updates for Mail and Drive files generated during the switch-over window.

Step 8: Grace Period & Cleanup

Allow a one-month grace period before decommissioning temporary domains.