Migrating Projects to another Organization

Google Cloud Platform (GCP) Project resources can only be migrated into an Organization if they aren't currently associated with an Organization. This guide describes how to work with Google Support to migrate Projects that are associated with an Organization into a different Organization.

This guide assumes that the destination Organization closely resembles the source Organization. Larger design efforts to integrate applications into a new ecosystem aren't discussed in this guide.

Planning and performing your migration

Step 1: Prepare your Projects

Migrating a project from one Organization to another is a manual support process that requires Project configuration.

Use the following list to prepare to migrate your Project resource:

• If you have changed the primary domain for your Organization's Google account, include this information when you open a case with Google Support.
• Disable Shared VPC network on the Project to move.
• Configure any custom organization-level Cloud Identity and Access Management roles you need at the level of the Project to move. For more details, see Custom Cloud IAM roles.
• Set all organization policies to inherit from the parent resource, and review the policies ahead of time so you understand the effect they will have after the migration. For more details, see Organization policies below.
• Set email routing for the primary domain associated with the destination Organization so you can accept ownership of the new Project resource.
• Grant the Cloud IAM roles you will need for the destination Organization resource. For example, roles/resourcemanager.projectCreator. All inherited roles will be removed after the Project has migrated to the target Organization.
• If you are using Domain restricted sharing in the target Organization, add the domains that have access to resources in the source Organization to the target Organization's whitelist.

Note: Memberships of groups in the source Organization remain under the control of the administrators for the source Organization.

Step 2: Open a support case

If you have a service plan that includes Google Professional Services (PSO), you should work with them to plan your Project migration. A Google Technical Account Manager (TAM) can coordinate the relevant parties on the Google side.

To start the migration process, open a support case, and provide:

1. A list of the project IDs for each Project resource to be moved.
2. If you are working with PSO on your migration plan, include a date and time to meet with Google Support and PSO over Hangouts. The TAM will arrange the meeting to finalize your plan.

Google Support will remove the Project resources you listed from their current Organization and notify you when this operation has been completed. You can then perform the migration.

Step 3: Perform the migration

To complete the migration:

1. Move the projects into the new Organization after Google finishes removing them from the parent Organization.
2. Update the service configuration for your Projects based on the new Organization hierarchy. For details, see the below service-related sections.

Note: While Google is moving your Projects out of the old Organization, some down-time might be necessary. This depends on the services in use by the Projects that are being migrated. Google will notify you by email when this operation is complete.

Mitigating service issues

GCP Project resources are the basis for using all GCP services. Project resources rely on the Organization resource for many functions, which can be disrupted when you move a Project resource from one Organization to another. You should plan mitigation strategies for each of the services that are used by the Project resources you're moving.

Custom Cloud IAM roles

Custom Cloud IAM roles can be created at an Organization level in your GCP resource hierarchy. These can be used to grant access to users below the Organization resource in the hierarchy. When a project is moved out of the Organization, custom roles configured at the Organization level won't move with it, but custom roles configured at the Project level will.

Organization-level custom roles that aren't moved will no longer function, and the getIamPolicy method won't return these custom roles as part of the Cloud IAM policy.

When you move a project with custom roles, some of the original Organization policies might still affect the project. If a custom role from the old Organization exists in the new Cloud IAM policy, it might invalidate the policy and cause errors when you try to update the policy. This issue isn't likely to present immediately after the migration, because it only occurs when trying to update the Cloud IAM policy.

To list existing custom roles at the Organization level:

gcloud iam roles list --organization ORGANIZATION_ID

To describe a particular custom role in an Organization:

gcloud iam roles describe --organization ORGANIZATION_ID /
ROLE_NAME

Where:

• ORGANIZATION_ID is your Organization ID.
• ROLE_NAME is the name of the role.

Mitigation

To reduce the risk of errors around existing custom Cloud IAM roles:

1. Use the projects.getIamPolicy method to get the Cloud IAM policy for the Project you want to move.
2. For each Organization-level custom role in the Project Cloud IAM policy, create an equivalent project-level custom role and update the Project Cloud IAM policy to use these new roles.
   1. If you need to increase your Project quota, submit a request to increase it.
3. Remove the Organization-level Cloud IAM custom role bindings from the Projects to be moved.
4. Migrate the Projects as above.
5. Update the Cloud IAM policies of the resources in the moved Projects to use the custom roles from the target Organization.

For more information, see Creating and managing custom roles.

Shared VPCs

Shared VPCs in GCP use the Organization resource for grouping. Project resources can only be connected to Shared VPCs in the same Organization. A project that moves to a new Organization won't preserve the Shared VPC connection.

Shared VPCs are implemented using a host project where the Shared VPC is provisioned, and service projects are permitted to use the Shared VPCs.

Compute Engine virtual machines (VMs) can't directly be moved from one VPC to another, and must be migrated or recreated. VMs are typically provisioned within the Shared VPC service projects, not directly within the Shared VPC host project.

To list all the Shared VPC host projects in an Organization resource:

gcloud beta compute shared-vpc organizations list-host-projects
ORGANIZATION_ID

Where ORGANIZATION_ID is your Organization ID.

Mitigation

1. Go to the Shared VPC page in the GCP Console.
   Go to the Shared VPC page
2. Make a list of the host Projects, Shared VPC networks, and any attached service Projects displayed on the Shared VPC page.
   1. If you are migrating all projects in an Organization, list all Shared VPC host projects using the list-host-projects command above.
3. Provision equivalent host projects and Shared VPCs in the new Organization. For detailed instructions, see Setting up Shared VPC.
4. Remove the Projects to be moved from the Shared VPCs in the source Organization:
   1. Take snapshots of the VM disks connected to the Shared VPC.
   2. Shut down the VMs that have connections to the Shared VPC.
   3. Delete the VMs.
   4. Remove any internal load balancers connected to the Shared VPC.
5. Restore the VMs from the snapshots and connect to a locally-scoped VPC in the service project.
6. Perform the migration.
7. Connect your moved Projects to the new Shared VPCs.

VPC peering

Projects using Google VPC peering can be moved between organizations because VPC peering is not dependant on Organization membership to function. This means that moving a Project into an Organization with VPC peering enabled will enable peering for that Project.

Mitigation

If you are moving a Project into an Organization that has VPC peering enabled, identify what is on the other end of that peering before the migration, and verify that you want the Project to have VPC peering enabled.

Cloud Interconnect

Projects containing a Dedicated Interconnect can only be moved to a new Organization if there are no VLAN attachments defined for the Cloud Interconnect.

Mitigation

Remove any VLAN attachments from the Projects to be moved before migration.

Domain renames

If the source Organization has ever had a domain name change, additional steps might be needed from Google to migrate Projects out of that Organization.

Mitigation

When you open a support case to migrate your Projects, provide the details of the domain change operation, including the original and new domain names. Google has tools to handle this scenario, but might need additional time to complete the migration.

Organization policies

Moving a Project to a new Organization might change the policies that are applied to that Project based on inheritance. The policies in the source Organization might differ from those in the destination Organization, and the effective Organization Policy might impact your Project differently after the migration.

Mitigation

Set the organization policy for each Project to move to inherit from the parent resource. You should review the policies ahead of time so you can make a plan to create a new set of organization policies that will have the effective policy you want in the new Organization.

For more details about how Organization policies are inherited, see Understanding hierarchy evaluation.

Cloud Billing

Cloud Billing accounts can be used across Organizations. Moving a Project from one Organization to another won't impact billing, and charges will continue against the old billing account. However, Organization moves often also include a requirement to move to a new billing account.

Change the billing account for a Project

To change the billing account for an existing project, you must have the roles/owner role on the Project, and the roles/billing.admin role on the destination billing account. To change the billing account:

1. Go to the Billing page in the GCP 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 move and then click the menu button to the right.
4. Click Change billing, and then select the new billing account.
5. Click Set account.

Charges already incurred that have not yet been reported in the transaction history will be billed to the former billing account. This can include charges from up to two days prior to when the project was moved.

Move a billing accoung between Organizations

A billing account can be moved from one Organization to another, although this isn't often a necessary step. Most existing Organizations will already have a billing account that should be used instead. If you need to migrate an existing billing account:

1. Get the necessary permissions for migration:
   1. role/resourcemanager.organizationAdmin on the source Organization.
   2. roles/billing.admin for either the source Organization, or the specific billing accounts to be moved.
   3. role/resourcemanager.organizationAdmin on the destination Organization.
   4. Either roles/billing.admin or roles/billing.creator on the destination Organization.
2. Go to the Billing page in the GCP Console.
   Go to the Billing page
3. Click on the name of the billing account you want to move.
4. At the top of the Overview page, click Change organization.
5. Select the destination Organization, and then click Ok.

The billing account is now associated with the specified Organization.