“Fasten your seatbelts, it’s going to be a bumpy night.” (All About Eve, 1950)

Or in other words, what happens when you try to migrate a Google workspace domain into another Google workspace domain?

​​

A few months back, I got a request to migrate a Google workspace domain into our main Fiverr Google account. This request came with some basic needs:

• Email flow should continue as usual for both domains
• No data loss
• User experience should remain the same or better
• Seamless migration for the end users
• Most importantly, users should keep using the same email address

When handling such a complex project, it all starts and ends with planning. What steps must be taken along the way? What happens in case of failure? Can we do a rollback?

Planning phase

I’ve used GAM to gather information about the source and target domains. GAMADV-XTD3 is a free, open-source command-line tool for Google Workspace Administrators to manage domain and user settings quickly and easily.

Here are a few commands I’ve used:

gam print users todrive
gam print users deleted_only todrive
gam print users query ‘isSuspended=True’ todrive

These commands provide data about the existing users and export the information to Google Sheets.

Once we have a proper view on our users, let’s see our groups. In this example, the data are exported to a local file.

gam print groups allfields members managers owners delimiter “ “ sortheaders > mygroups.csv

It’s important to understand which aliases are defined for the users and groups:

gam print aliases > Domain-Aliases.csv

We didn’t know how long the migration would take, since it depends mostly on Google API response time and the amount of data we need to transfer. Partial but useful data can be found on https://admin.google.com/ under Reports, App Reports, Accounts.

Resources & shared drives

We’ve checked the resources (Meeting rooms, etc.) and verified what had to be moved. We verified which groups and shared drives are in use and what can be left behind.

Licenses

Verify which licenses are being used on the source domain and delete them if they are not in use. It might affect your migration timelines.

Domains, GCP, & Apple ID

It’s important to verify whether other domains are being used and need to be copied. If users are using GCP, then it requires attention as well. For AppleID, there’s a special procedure to migrate the users, or you might lose access to your Apple data.

External Sharing

If external sharing is enabled on the source domain and files are shared from a user’s drive,then these files will have to be shared again after the migration.

However, if files are shared from a shared drive, there is a workaround you can use to migrate these files and keep the original shared link. This is highly useful when you have a file that is shared externally with lots of users whom you can’t update about the link change.

During planning, it’s critical that you gather this information and understand how many files are shared and what the effect would be if these links were gone. Answering these questions will assist you during the migration process.

Once we had all the information, we were able to plan and set the migration date and the migration type. Also, we decided on proper communication channels (as email could not be used during the migration), such as Whatsapp, Zoom, and Slack.

Our HR team was fully involved in the process to make sure that we have an accurate employees list and that everyone is mapped into the right department.

Preparations

For our migrations, we used Google Workspace Migrate [Beta] (GWM). There are other tools on the market, but we decided to use this one. Remember that it requires a few Windows servers in order to run properly.

In our case, we are also using an IDP (identity provider), so we’ve created our new users and verified that they can use it prior to the migration.

We’ve created the users on our target domain and used this GAM command for that purpose:

gam redirect stdout CreateUsers.log multiprocess redirect stderr stdout csv UsersToCreate.csv gam create user “~useremail” firstname “~firstname” lastname “~lastname” ou “~ou” password random notify “my-email@sample.com”

All users are created with a temporary domain name, so we can switch them easily after the cutover and data migration.

Our next step was to define the settings on GWM and start the migration in the background. Data are replicated to the target domain without any change to the source domain. It took a full 4 days to move all Users data, Shared Drive, Groups mappings,, and resources data. The amount of migration time depends on the network speed, as well as the number of users and servers you defined for the project. In our case, we used 10 servers.

We kept an open communication channel between source and destination domains in order to answer any question that might appear before, during, or after the migration.

Cutover

For a smooth migration, we decided to use a third-party vendor and deliver the email via a gateway. While the domain was being transferred, the vendor kept the emails for us until the domain was set up correctly on the other side.

Important: From my experience, it takes around 10–15 minutes to migrate the domain name from one Google domain to another. However, in this case, the domain was locked on the source due to an old, inactive license that was tied to it, and Google could not release it for 14 hours. Make sure your third-party vendor can store your emails for long periods of time in case something similar happens to you during the migration.

The first step during cutover is to do a few DNS and MX changes and make sure new email is not delivered to the domain. I’ve written a small Python script that sends email to the old and new domain and also to a slack channel, so I could quickly monitor the progress.

The next step was to make sure our users on the source domain did not alter the data, so we had to block them from accessing their Google accounts. We blocked everyone except the Admin user and used this command for doing so:

gam csv UsersToReset.csv gam update user us…@domain.com password “new password” notify us…@home.com

All users are now blocked, but they can still use other systems they are already logged into, such as Slack.

It’s almost time to move the domain name from the old Google Workspace to the new one. Before doing that, we need to run another delta data migration using GWM and make sure all data are copied to the target domain.

Once this task is done, we can go ahead and move the domain alias from the source domain to the target domain.

Cutover continues

So, now we have all our users with their data on the target domain, but with a temporary email domain. We need to make sure that

• users are using the right email address,
• groups are migrated and contain the right users,
• aliases are applied to the users and groups, and
• Shared Drive data migrated without issues.

Once again, GAM is here to help. This command changes the primary email address of a user:

gam update user allyson@targetdomain.com primaryemail allyson@sourcedomain.com

This command will rename all groups main email address:

gam csv Groups_Rename.csv gam update group “~sourcegroup” email “~targetgroup”

We need to make sure aliases are applied to all users and groups, so we are running the command twice. The aliases data arrived from the data gathered during the planning stage.

gam csv “Aliases_To_Add.csv” gam create alias “~Alias” user “~email”

gam csv “Aliases_To_Add.csv” gam create alias “~Alias” group “~email”

Remove the temporary domain from the new users accounts using this command:

gam csv “Users_Rename.csv” gam user “~targetemail” clear contacts emailmatchpattern “.*@tempdomain.com”

Once all data have been verified, there are a few more things to check:

• Domain moved and verified correctly
• Routing rules that exist on the source domain might be applied on the target domain, or on a specific OU
• Check with a few users that they can log into their mailbox, see data, calendar, and groups information

If all tests passed, it’s time to set up the MX records and release the emails kept on the vendor side.

Support, Proper Communication, & More Support:

Things might fail during the migration, and users might have difficulty locating their data. For example, if your users are using an old folder of a suspended user, it might not be moved, and your users will complain that they lost data.

During the first 24 hours, users might have LOTS of questions. We opened a Slack channel for that purpose and found out that once someone asked a question, it was related to many other users. By using a public channel, people could react quickly and advise whether certain problems were solved or whether they needed our help.

It’s important to give 24/7 support during the first few days after the migration and report back on any issue that might pop up. Our technical support team assisted by providing real-time support after the migration, and most problems were resolved very quickly.

A week later

Things calmed very quickly, as users are getting used to the new working environment under the target Google workspace. We’ve put all of them in a separate OU so it’s very easy to apply specific changes they might need to use on their own domain.

Migrations are tough sometimes, but it’s not something to be afraid of. With proper planning, the right technical tools, and management support, you can do it too!

Fiverr is hiring in Tel Aviv and Kyiv. Learn more about us here