Perform the migration

This page provides the steps to migrate a Google Cloud project from one organization resource to another, or from no organization resource into an organization resource.

To migrate a project, you must ensure you have the correct (Identity and Access Management (IAM)) permissions and that specific organization policies are configured on both the source and destination resources.

Before you begin

A project migration is a cross-organization operation. To prevent unauthorized movement of resources, you must satisfy the following requirements.

Required roles

To get the permissions that you need to migrate projects between organization resources, ask your administrator to grant you the following IAM roles:

• Project IAM Admin (roles/resourcemanager.projectIamAdmin) on the project you want to migrate between organization resources
• Project Mover (roles/resourcemanager.projectMover) on the project's parent resource (folder or organization resource)
• If the destination resource is a folder: Project Mover (roles/resourcemanager.projectMover) on the destination resource
• If the destination resource is an organization: Project Creator (roles/resourcemanager.projectCreator) on the destination resource

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

These roles must be granted to the same user account in both the source and destination organizations. These predefined roles contain the permissions required to migrate projects. To see the exact permissions that are required, expand the Required permissions section.

Required permissions

The following permissions are required to migrate projects:

• resourcemanager.projects.getIamPolicy on the project you want to migrate between organization resources
• resourcemanager.projects.update on the project you want to migrate between organization resources
• resourcemanager.projects.move on the project's parent resource (folder or organization resource)
• If the destination resource is a folder: resourcemanager.projects.move on the destination resource
• If the destination resource is an organization resource: resourcemanager.projects.create on the destination resource
• If you want to migrate a project that is not associated with an organization: resourcemanager.projects.setIamPolicy on the project you want to migrate

You can also gain these permissions with a custom role, or other predefined roles.

Required organization policies

By default, project migration is restricted. You must explicitly allow the export and import by setting organization policies at the root of both organizations. To configure organization policies required for the migration, you must have the roles/orgPolicy.policyAdmin role on the parent and the destination organization.

• On the source organization resource: Set the constraints/resourcemanager.allowedExportDestinations policy. Add the ID of the destination organization as an allowed value.

• On the destination organization resource: Set the constraints/resourcemanager.allowedImportSources policy. Add the ID of the source organization as an allowed value.

Perform the migration

Once permissions are granted and policies are enforced, you can migrate the project using the Google Cloud CLI or the Resource Manager API.

gcloud beta projects move PROJECT_ID \
    --organization ORGANIZATION_ID

gcloud beta projects move PROJECT_ID \
    --folder FOLDER_ID

    project = crm.projects().get(projectId=flags.projectId).execute()
    project['parent'] = {
        'type': 'organization',
        'id': flags.organizationId
    }

    project = crm.projects().update(
    projectId=flags.projectId, body=project).execute()

Post-migration tasks

After successfully migrating your project, you must perform several post-migration tasks to ensure continuity of operations, security compliance, and proper billing. Migrating a project changes its resource hierarchy, which affects inherited permissions and organization-level policies.

Here are some steps that you can complete post migration:

1. Policy verification: Verify that the project is inheriting the expected organization policies from its new parent.

2. Access control: Audit IAM roles to ensure users in the new organization have the necessary access.

3. Billing: Update the billing account if the project needs to be billed to the destination organization. This is an optional step. For details, see Change the billing account for a project and Migrate a billing account between organization resources.

4. Cleanup: Revoke the temporary Project Mover roles and remove the allowedExportDestinations and the allowedImportSources constraints."

Change the billing account for a project

Cloud Billing accounts can be used across organization resources. Moving a project from one organization resource to another won't impact billing, and charges will continue against the old billing account. However, migration of projects between organization resources often also include a requirement to migrate to a new billing account.

To change the billing account, do the following:

1. Go to the Billing page in the Google Cloud console.
   Go to the Billing page
2. Click the name of the billing account you want to change.
3. Under Projects linked to this billing account, find the name of the Project to migrate and then click the menu button to the right.