Migrating Projects into an Organization

Once a Google Cloud Platform (GCP) Organization resource has been created for your domain, you can move your existing projects into the organization. You must be an owner or an editor of the project and a Project Creator in the organization to be able to move the projects.

Note: To acquire an Organization resource, you must have a G Suite or Cloud Identity account. Once you have the account set up, you must create a Project resource for the Organization resource to be provisioned. For detailed instructions, see Getting an Organization resource.

All projects created after the creation of the Organization resource will automatically belong to the Organization resource. You can migrate a project into an organization using the GCP Console, the Resource Manager API, or the gcloud command-line tool.

Note: The link between projects and billing accounts is preserved, irrespective of the hierarchy. When you move your existing projects into the organization they will continue to work and be billed as they used to before the migration, even if the corresponding billing account has not been migrated yet. Similarly, if you move a billing account into the organization, all projects linked to it will continue to work even if they are still outside of the organization. There should be no server downtime or impact as a result of migration.

Migrating projects in an organization

If a project is associated with an organization, you can't change it back to No organization or migrate it to another organization without involving Google Cloud Platform support. If you need to migrate a project after it's associated with an organization, see Migrating Projects to another Organization.

Migrating projects with no organization

To migrate a project, you will need the Project Creator role (roles/resourcemanager.projectCreator) on the organization to which you want to migrate your project. You will also need the Project Mover role (roles/resourcemanager.projectMover) on the project you are migrating. If you don't have these roles, the target organization won't appear in the Google Cloud Platform Console as a choice for migration.

Project migration isn't reversible. After a project is associated with an organization, you can't change it back to No organization or move it to another organization on your own. If you want to move a project after it's associated with an organization, contact GCP Support.

Console

To migrate a project into an organization:

1. Open the IAM & admin > Settings page in the GCP Console.

   Open the Settings page

2. On the Select organization drop-down list at the top of the page, select No Organization, and then select the project you want to migrate.

   

3. At the top of the page, click Migrate.

4. On the Organization drop-down list, select the organization you want to migrate your project to.

After a project is added to an organization, you cannot undo the selection on your own.

gcloud

To migrate a project into an organization, run the following command:

gcloud alpha projects move PROJECT_ID /
    --organization ORGANIZATION_ID

Where:

• PROJECT_ID is the ID of the project you wish to move into the organization.
• ORGANIZATION_ID is the ID of the organization to which you wish to move the project.

After a project is added to an organization, you cannot undo the selection on your own.

API

Using the Resource Manager API, you can move a project into the organization resource by setting its parent field to the organization ID of the organization.

To migrate a project into the organization:

• Get the project object using projects.get() method.
• Set its parent field to the Organization ID of the organization.
• Update the project object using projects.update() method.

You can't change the parent field after you set it.

The following code snippet demonstrates the steps above:

    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()

Note on policy implications

Cloud IAM policies that are already defined for a project are imported with the project. This means users who have permissions on a project before it moves maintain the permissions after the project is migrated into the organization.

Cloud IAM permissions are inherited and additive; if there are roles defined at the organization level, those roles are inherited by the projects as they are moved into the organization. If, for example, [e-mail] has the Project Editor role defined at the organization level, he will also have this role on any project migrated into the organization. This does not break anything in existing projects, but more users may gain access due to inheritance.

Similarly, organization policies are also inherited down the hierarchy. By default no organization policy is defined for an organization when it is created. If you have subsequently defined organization policies on your organization, care needs to be taken when moving projects into the organization to make sure projects are consistent with such policies.

Key Point: It is the user’s responsibility to make sure that IAM and organization policies are consistent when projects are moved into the organization.

Migrating existing billing accounts

If you are a G Suite or Cloud Identity customer with existing billing accounts, you can migrate them to your organization. You must be a Billing Account Creator and a Billing Administrator on the organization to which you want to migrate your project to migrate billing accounts. To learn about granting these roles, see Managing Default Organization Roles. Migrating a billing account into an Organization doesn't impact project services.

To migrate your existing billing accounts into an organization, follow the steps below:

1. Go to the GCP Console Billing page:
   GO TO THE BILLING PAGE
2. In the drop-down at the top of the page, select No organization to see billing accounts that aren't associated with an organization.
3. Under Billing account name, click the name of the billing account that you want to migrate. The billing account overview page will appear.
4. Next to Billing account on the right, click Manage.
5. On the account management page that appears, click Change Organization, and then select the organization to which you want to migrate the billing account.