Setting up Google Cloud for CloudM Migrate using Cloud Shell

Updated August 20, 2026 15:16

This article explains how to configure a Google Cloud project for CloudM Migrate using Google Cloud Shell. A script does the Google Cloud work for you, and an interactive tutorial walks you through the parts that have to be done by hand. There is nothing to install, so it is an alternative to the PowerShell setup script, which needs a Windows machine with the Google Cloud SDK installed.

This route is in beta. It has been tested end to end and the script is safe to run, but it is new and we are still gathering feedback on it. The PowerShell script remains the standard route, and either produces a working configuration. If you try this one, tell us how it went through your CloudM contact.

You need permission to create projects in your Google Cloud organisation, or an existing project you administer, and super administrator access to the Google Workspace tenant. One step, granting domain-wide delegation, has to be done in the Google Admin console and cannot be automated. Allow about 15 minutes.

What the script does

Creates the Google Cloud project, or selects it if it already exists
Creates a service account and grants it owner on that project
Creates a JSON key for the service account and downloads it to your browser
Enables the Google APIs the migration needs
Builds a link for the domain-wide delegation grant with the client ID and the full scope list already filled in

What you do yourself

Grant domain-wide delegation. This happens in the Google Admin console rather than in Google Cloud, so the script cannot do it. It gives you a prefilled link instead, which turns the step into a click and a confirmation rather than pasting a list of nearly 30 scopes without altering any of it.

Configure the Google Chat app, if the migration includes Google Chat. This needs values the script has no way of knowing, including an endpoint URL from your CloudM Migrate setup and a Google Group for visibility. See Enable and Configure the Google Chat API.

Before you start

A Google account that can create projects in the target Google Cloud organisation, or the ID of an existing project you administer
Super administrator access to the Google Workspace tenant being migrated
A browser. Cloud Shell already has the Google Cloud CLI installed and signed in as you, so nothing is installed locally

The script is public, and it is worth reading before you run it because it grants owner and creates a private key. You can review it in the cloudm-public repository.

Open the tutorial in Cloud Shell

Open the CloudM Migrate setup in Google Cloud Shell

The link clones the repository into your Cloud Shell session and opens the tutorial in a side panel next to the terminal. Follow the tutorial and you can ignore the rest of this article, which covers the same ground as reference.

Commands in the tutorial have a copy button and a run button. The copy button pastes the command into the terminal without running it, so you can edit it first.

Choose a scope

The scope you pass to the script controls which OAuth scopes are granted and which APIs are enabled. Pick the narrowest one that covers the migration.

Scope	Use it when
`Standard`	The usual choice. Full mailbox access, for a normal Google Workspace migration.
`SourceLimited`	Migrating out of a Google tenant and you do not want to grant write access to it. Gmail is read-only.
`DestinationLimited`	Migrating into a Google tenant and you do not want to grant read access to it. Gmail is insert only.
`Vault`	Standard, plus Google Vault and Cloud Storage.
`Storage`	Standard, plus Cloud Storage.
`All`	Everything above. Only use this if you need it, because it grants the broadest access.

Nine APIs are enabled for the mail, Drive, Calendar, Contacts, Tasks, Groups and Forms work every migration does. The Vault and Storage scopes add the Google Vault and Cloud Storage APIs on top. If a migration includes Google Chat, add --include-chat to grant the Chat scopes and enable the Chat API, whichever scope you chose.

The full list of scopes and APIs is in Setting up the Service Account and enable the APIs within Google Workspace for CloudM Migrate.

Run the script

The tutorial runs these commands for you in order. The arguments are the project ID, a name for the service account, and the scope.

Preview the changes. This validates your input and prints every gcloud call without running any of them, so you can see exactly what will happen before anything changes:
```
./gcp_configuration.sh --dry-run my-project-id cloudm-migrate Standard
```
Run it for real. This creates the service account, grants it owner on the project, issues a private key and enables the APIs. It takes a few minutes:
```
./gcp_configuration.sh my-project-id cloudm-migrate Standard
```
Read the output. The script prints the service account email, the client ID, the project number and the path to the key file, and it leaves a clickable link labelled Grant domain wide delegation. Leave the output on screen, because the next steps use it.
Control-click, or command-click on a Mac, the delegation link. The Google Admin console opens with the Client ID and OAuth scopes fields already populated. Check the Client ID matches the one the script printed, check the scopes field is not empty, then click Authorise.
Reopen the delegation entry and confirm the number of scopes matches what the script printed. A missing scope causes migration failures later that are hard to trace back to this step.
Save the key file. The script starts the download itself. If it did not start, run cloudshell download ~/cloudm/gcpconfig/*_key.json, or use the three dot menu at the top of the Cloud Shell window and choose Download.

Both the project ID and the service account name must be 6 to 30 lowercase letters, digits or hyphens, must start with a letter and must not end with a hyphen. The key and a log of everything the script did are written to ~/cloudm/gcpconfig unless you pass a different path as a fourth argument.

If the prefilled delegation form is empty

The prefill is a convenience and the Admin console can ignore it. Enter the values by hand instead:

Go to Domain-wide delegation in the Google Admin console and click Add new
Paste the client ID the script printed into the Client ID field
Open ~/cloudm/gcpconfig/scopes.txt, copy the whole line, and paste it into the OAuth scopes field
Click Authorise

Copy the scopes from the file rather than from the terminal, where the line will have wrapped and is easy to truncate.

Set up the connection in CloudM Migrate

In CloudM Migrate, create or edit the Google Workspace connection and enter:

Service account email, as printed by the script
Key file, the JSON file you downloaded
Authentication method, set to JSON

The authentication method matters. This script creates a JSON key, not a p12 key, so a connection left on P12 will fail to authenticate.

Test the connection before starting a migration. If it fails, the most likely cause is that domain-wide delegation has not finished propagating, so wait a few minutes and try again.

Remove the key from Cloud Shell

Once the key is stored somewhere secure and the connection tests successfully, delete the copy in Cloud Shell:

shred -u ~/cloudm/gcpconfig/*_key.json

Do not skip this. Your Cloud Shell home directory persists between sessions, so without it a service account private key stays on disk. The log and the scope list contain no secrets, so you can leave them, or remove everything with rm -rf ~/cloudm/gcpconfig.

Permissions and security

The service account is granted roles/owner on the project it is created in. That project exists to hold the migration service account, so the grant covers that project and nothing else in your organisation.

The script creates a service account private key. Treat the downloaded file like a password, and remove the Cloud Shell copy as above.

Re-running the script with the same service account name is safe. The existing account is reused and issued a fresh key rather than being recreated, so you can issue a replacement key without starting again. Google Cloud limits a service account to 10 keys.

Troubleshooting

Key creation fails

The organisation policy constraints/iam.disableServiceAccountKeyCreation prevents service account keys from being created. It is enforced by default on recently created organisations. Someone with organisation policy admin rights needs to disable it for this project, then you can re-run the script with the same service account name.

Creating the project fails

Either the project ID is already taken, because project IDs are globally unique, or your account does not have resourcemanager.projects.create on the target organisation or folder. If it is the permission, ask whoever administers the organisation for an empty project and pass its ID to the script.

The command still contains a placeholder

If a command you copied from the tutorial contains <walkthrough-project-id/> as literal text rather than your project ID, replace it by hand before running it.

The connection fails to authenticate

Check the authentication method on the connection is set to JSON rather than P12, then check the delegation entry in the Admin console has the full scope list and the correct client ID. Delegation changes can take a few minutes to take effect. If your organisation requires multi-party approval for admin actions, another super administrator may need to approve the delegation grant before it becomes active.

Running the script outside Cloud Shell

Cloud Shell is the easiest route because the Google Cloud CLI is already installed and signed in, but the script also runs on any Linux or macOS machine with the CLI installed and initialised. Clone the repository, then run the script from Migrate/CloudShell with the same arguments. Without Cloud Shell the key is written to the path you pass rather than downloaded through the browser, and there is no automatic download step to skip.