Add a target project

With Migrate to Virtual Machines, you work with two types of projects:

  • Host project Use the host project to perform migrations and to host the Compute Engine instances running your migrated workloads. You must create and configure a host project as described Enable Migrate to Virtual Machines services.

  • Target project

    A target project defines a destination project for a Compute Engine instance running your migrated VM. Your host project can be used as a target project. If you want to migrate VMs to additional projects, you must add them as target projects to Migrate to Virtual Machines.

    You typically don't add target projects to Migrate to Virtual Machines until you are ready to start deploying migrated workloads.

Perform the following steps to add a target project to Migrate to Virtual Machines:

  1. Identify and configure the target project.
  2. Set required permissions.
  3. Add the target project.

If necessary, you can later Remove a target project.

Identify and configure the target project

You must identify the Google Cloud project that you want to use as the target project:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project to use as a target project:

    Go to the project selector page

  2. Note the name and ID of the selected project.

  3. Enable the following services on the target project:

    Name Title
    servicemanagement.googleapis.com Service Management API
    servicecontrol.googleapis.com Service Control API
    iam.googleapis.com Identity and Access Management (IAM) API
    cloudresourcemanager.googleapis.com Cloud Resource Manager API
    compute.googleapis.com Compute Engine API

    To enable the required services:

    1. Ensure that you have set the default project to the target project. Replace PROJECT_ID with the project ID of your target project:

      gcloud config set project PROJECT_ID
    2. View the list of services already enabled:

      gcloud services list
    3. If you don't see all of the required services listed, enable them:

      gcloud services enable servicemanagement.googleapis.com servicecontrol.googleapis.com iam.googleapis.com cloudresourcemanager.googleapis.com compute.googleapis.com

Set required permissions

For a user to be able to add a target project, and to configure the details of the Compute Engine instance on the target project, that user requires the necessary IAM roles and permissions.

Because you perform these actions in the Google Cloud console, the user account that requires these permissions is the account that you use to sign in to the Google Cloud console:

  • To add a target project to Migrate to Virtual Machines, the user account you use to sign in to the Google Cloud console requires the permissions described in Set permissions to add a target project.

  • To configure the target details of the Compute Engine instance running on the target project, the user account you use to sign in to the Google Cloud console requires permissions to access data in the target project, such as networks, instance types, and more. For more information, see Set permissions to configure a target instance.

Depending on how you configure IAM for your environment, you might configure a single user to perform both actions, or configure two separate users.

Set permissions to add a target project

To add a target project, the user account you use on the Google Cloud console requires:

  • The role vmmigration.admin on the host project

  • The role resourcemanager.projectIamAdmin on the target project

To add these roles:

  1. Determine the email address of your user account. In the Google Cloud console, you can see all users in your project on the IAM page:

    Go to the project selector page

  2. Grant your user account the vmmigration.admin role on the host project:

    gcloud projects add-iam-policy-binding HOST_PROJECT_ID --member=user:USER_EMAIL_ADDRESS --role=roles/vmmigration.admin
  3. Grant your user account the resourcemanager.projectIamAdmin role on the target project:

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID --member=user:USER_EMAIL_ADDRESS --role=roles/resourcemanager.projectIamAdmin

If you are unable to assign role resourcemanager.projectIamAdmin on the target project to your user account, you can assign the role vmmigration.serviceAgent on the target project to the Migrate to Virtual Machines default service account.

To add this role:

  1. Open the Migrate to Virtual Machines page in the Google Cloud console:

    Go to the Migrate to Virtual Machines page

  2. Select the Targets tab.

    At the top of the page is an information box showing the email address of the Migrate to Virtual Machines default service account in the form:

    service-HOST_PROJECT_NUMBER@gcp-sa-vmmigration.iam.gserviceaccount.com

  3. Copy the email address.

  4. Use that email address to grant the vmmigration.serviceAgent role on the target project to the Migrate to Virtual Machines default service account:

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
       --member=serviceAccount:service-HOST_PROJECT_NUMBER@gcp-sa-vmmigration.iam.gserviceaccount.com \
       --role=roles/vmmigration.serviceAgent

Set permissions to configure target details

To configure the target details of the Compute Engine instance on the target project, the user account you use on the Google Cloud console requires:

  • The role compute.viewer and the role iam.serviceAccountUser on the target project

To add this role:

  1. Determine the email address of your user account. In the Google Cloud console, you can see all users in your project on the IAM page:

    Go to the project selector page

  2. Grant your user account the compute.viewer role and the iam.serviceAccountUser role on the target project:

    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID --member=user:USER_EMAIL_ADDRESS --role=roles/compute.viewer
    gcloud projects add-iam-policy-binding TARGET_PROJECT_ID --member=user:USER_EMAIL_ADDRESS --role=roles/iam.serviceAccountUser
  3. (Shared VPC environment only) Grant your user account the compute.viewer role on the Shared VPC host project:

    gcloud projects add-iam-policy-binding VPC_HOST_PROJECT_ID --member=user:USER_EMAIL_ADDRESS --role=roles/compute.viewer

Add the target project

After you have configured the target project, and assigned the necessary roles to the user account, you can add it to Migrate to Virtual Machines.

To add a target project to Migrate to Virtual Machines:

  1. Open the Migrate to Virtual Machines page in the Google Cloud console:

    Go to the Migrate to Virtual Machines page

  2. Select the Targets tab. A list of projects already added appears.

  3. Select Add Projects.

    A panel opens listing the available projects.

  4. Select one or more projects.

  5. Select Add.

    The new project appears in the projects table.

Remove a target project

You can remove a target project from Migrate to Virtual Machines. Removing the target project means you can no longer perform a test-clone or cut-over operation that uses the target project to host Compute Engine instances.

When you add a target project to Migrate to Virtual Machines, Migrate to Virtual Machines automatically adds permissions to the default Migrate to Virtual Machines service account on the host project that allows the host project to perform operations on the target project.

When you later remove the target project, Migrate to Virtual Machines attempts to remove those permissions on the service account. However, if there has been a change that prevents those permissions from being removed, the target project is still removed from Migrate to Virtual Machines. If necessary you can manually update the service account to remove those permissions.

To remove a target project from Migrate to Virtual Machines:

  1. Open the Migrate to Virtual Machines page in the Google Cloud console:

    Go to the Migrate to Virtual Machines page

  2. Select the Targets tab. A list of projects already added appears.

  3. Select one or more projects.

  4. Select Remove Projects.

  5. Confirm that you want to remove the projects.

What's next