Migrate projects between organization resources

Migrating a Google Cloud project is a metadata operation that changes the project's location in the resource hierarchy. This page provides an overview of how migrations work, what stays the same, and what changes when a project moves to a new organization.

Projects in the resource hierarchy

The project resource is the base-level organizing entity in a Google Cloud organization resource. Projects are created under organization resources and can be placed under folders or the organization resource itself, forming the resource hierarchy.

You may need to migrate projects between organization resources due to acquisitions, regulatory requirements, or the separation of business units. You can use the Resource Manager API to migrate these projects. The migration operation returns a string representing the operation name. The API also lets you roll back a migration, moving the project back to its original place in the hierarchy if necessary.

Migration scenarios

Your project's location determines which of two paths you take:

  • Migrate projects from one organization to another organization resource.
  • Migrate a standalone project (created without an organization) into the hierarchy of an organization resource.

If you need to move a project back to No organization after it is associated with an organization resource, you must contact Cloud Customer Care. Self-service rollback from an organization back to no organization isn't supported.

In addition to the API, you can also use the Google Cloud console to move projects by selecting the project and assigning it a new parent destination.

Identify the project's current state

Before you begin, you must determine if your project is associated with an organization resource. This determines whether you follow the Organization-to-Organization path or the No Organization path.

If you don't have the resourcemanager.organizations.get permission on the parent organization resource of the project, it's likely that your projects don't reflect as expected under the actual organization in the Google Cloud console. This can make it seem like the project is not associated with any organization resource.

To determine whether the project is associated with an organization resource, run the following command:

gcloud 

gcloud projects get-ancestors PROJECT_ID

Replace PROJECT_ID with the ID of the project that you want to migrate.

If the output includes an organization resource type in the hierarchy, your project is already part of an organization hierarchy.

If the organization type is missing or empty, the project is a standalone project with no organization resource.

Based on your project's state, follow the relevant guide:

How migration works

A project migration is not a data transfer. Your services, databases, and virtual machine (VM) instances remain active and don't experience downtime. Instead, the migration updates the project's parent resource. Because Google Cloud follows a hierarchical inheritance model, the project's security posture changes the moment it's attached to a new parent.

Feature Status Impact
Project ID and number Stays the same API keys, service names, and hardcoded IDs remain unchanged.
Data and resources Stays the same VMs, Storage buckets, and databases remain online.
Direct IAM roles Stays the same Roles granted directly on the project move with it.
Inherited IAM roles Changes Roles granted at the source organization or folder level are lost.
Organization policies Changes Source constraints are replaced by destination constraints.
Quotas Changes Inherited organization-level quotas are lost; project-level quotas remain.
Billing account Stays the same The project remains linked to the original billing account.

Quota impact

If you have quotas defined at a certain resource level, the following aspects are applied after migration:

  • Any quotas defined at the project level remain unchanged.
  • Any quotas defined at the organization resource level are not transferred. The organization loses any inherited quotas or quota overrides.

The following pages can be used to determine what quotas are applied to an organization resource:

Example

$ gcloud alpha services quota list --service=compute.googleapis.com --consumer=projects/workloadyee --filter="metric: compute.googleapis.com/cpus"

...
  - defaultLimit: '600'
    dimensions:
      region: us-central1
    effectiveLimit: '650'
...

Critical considerations

Before starting a migration, review these high-risk areas to prevent service disruption:

  • Quota Limits: If the destination organization has lower quota limits than the source, your project may exceed its quota upon arrival.

  • Asset Inventory: Updates to the complete list of resources in Cloud Asset Inventory can take a few days to fully propagate after migration.

  • Cost and discounts: If the original organization had SKU-based or Enterprise Discount Program (EDP) discounts, those discounts don't apply in the new organization until you negotiate them with your Google Sales representative. Committed use discounts (CUDs) and Google Cloud Marketplace purchases might also need repurchasing.

  • Support Tiers: If there is no active support contract or a lower-tier support level in the destination organization, you might lose your current support tier.

  • Custom roles: If your project relies on custom IAM roles defined at the organization level, those roles won't exist in the destination. Recreate them in the destination organization before moving.

The migration roadmap

Use the following roadmap to navigate the project migration process:

  1. Prepare: Create a migration plan to to coordinate timing.
  2. Perform: Assign IAM roles and configure organization policies and execute the migration.
  3. Verify: Complete post-migration tasks, such as auditing inherited policies and updating billing.

What's next