Managing multiple organization resources

The organization resource establishes ownership of the projects and folders underneath it in the Google Cloud Platform resource hierarchy. Your Google Workspace or Cloud Identity account is associated with exactly one organization resource. Each Google Workspace or Cloud Identity account is also associated with a primary domain, such as example.com. For details on using multiple domains, see Add a user alias domain or secondary domain. For details on changing the primary domain for a Google Workspace account, see Change your primary domain for Google Workspace.

It's best to use folders under one organization resource for most use cases. If you want to maintain sub-organizations or departments within your company as isolated entities with no central administration, you can set up multiple Google Workspace or Cloud Identity accounts. Each account will come with a single organization resource associated with a primary domain.

Effects of using multiple organization resources

Use multiple organization resources when you don't want users from one Google Workspace or Cloud Identity account to access resources created by users from another Google Workspace or Cloud Identity account. Separating resources into multiple organization resources comes with several consequences:

By default, no single user will have central visibility and control over all resources.
Policies that are common across sub-organizations will need to be replicated on each organization resource.
Moving folders from one organization resource to another is not a supported operation. Moving projects from one organization resource to another can be accomplished following the guide here.
Each organization resource requires a Google Workspace account. Operating multiple organization resources therefore requires multiple Google Workspace accounts and the ability to manage identities across them.

Note: If you have a Cloud Identity domain, a Google Workspace domain is not required.

Using a single organization resource

Most organizations that want to maintain separate sub-organizations can do so using a single organization resource and folders. If you have a single Google Workspace account, this account maps to the organization resource, and sub-organizations map to folders.

Choose an Organization Administrator

Choose one or more users to act as the IAM Organization Administrator for the organization resource.

Console

To add an Organization Administrator:

Sign in to the Google Cloud console as a Google Workspace or Cloud Identity super administrator and navigate to the IAM & Admin page:
Open the IAM & admin page
Select the organization resource you want to edit:
1. Click the project drop-down list at the top of the page.
2. In the Select from dialog, click the organization drop-down list, and select the organization resource to which you want to add an Organization Administrator.
3. On the list that appears, click the organization resource to open its IAM Permissions page.
Click Add, and then enter the email address of one or more users you want to set as Organization Administrators.
In the Select a role drop-down list, select Resource Manager > Organization Administrator, and then click Save.

The Organization Administrator can do the following:
- Take full control of the organization resource. Separation of responsibilities between Google Workspace or Cloud Identity super administrator and Google Cloud administrator is established.
- Delegate responsibility over critical functions by assigning the relevant IAM roles.

Create folders for sub-organizations

Create a folder under the organization resource for each sub-organization.

To create folders, you must have the Folder Admin or Folder Creator role at the parent level. For example, to create folders at the organization level, you must have one of these roles at the organization level.

As part of creating a folder, you must assign it a name. Folder names must meet the following requirements:

The name may contain letters, digits, spaces, hyphens and underscores.
The folder's display name must start and end with a letter or digit.
The name must be between 3 and 30 characters.
The name must be distinct from all other folders that share its parent.

To create a folder:

Console

Folders can be created in the UI using the "Manage Projects and Folders" section.

Go to the Manage resources page in the Google Cloud console:
Open the Manage resources page
Make sure that your organization resource name is selected in the organization drop-down list at the top of the page.
Click Create folder, and select one of the following options:
- Standard folder: A standard folder resource.
- Compliant folder: An Assured Workloads folder, which provides additional regulatory, regional, or sovereign controls for Google Cloud resources. Selecting this option will take you to Assured Workloads to create a folder.
In the Folder name box, enter your new folder's name.
Under Destination, click Browse, then select the organization resource or folder under which you want to create your new folder.
1. Click Create.

gcloud

Folders can be created programmatically using the Google Cloud CLI.

To create a folder under the organization resource using the gcloud command-line tool, run the following command.

gcloud resource-manager folders create \
   --display-name=[DISPLAY_NAME] \
   --organization=[ORGANIZATION_ID]

To create a folder whose parent is another folder:

gcloud resource-manager folders create \
   --display-name=[DISPLAY_NAME] \
   --folder=[FOLDER_ID]

Where:

[DISPLAY_NAME] is the folder's display name. No two folders with the same parent can share a display name. The display name must start and end with a letter or digit, may contain letters, digits, spaces, hyphens and underscores, and can be no longer than 30 characters.
[ORGANIZATION_ID]is the ID of the parent organization resource if the parent is an organization resource.
[FOLDER_ID] is the ID of the parent folder, if the parent is a folder.

API

Folders can be created with an API request.

The request JSON:

request_json= '{
  display_name: DISPLAY_NAME,
  parent: ORGANIZATION_NAME
}'

The Create Folder curl request:

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ${bearer_token}" \
-d "$request_json" \
https://cloudresourcemanager.googleapis.com/v3/folders

Where:

[DISPLAY_NAME] is the new folder's display name, for example "My Awesome Folder."
[ORGANIZATION_NAME] is the name of the organization resource under which you're creating the folder, for example organizations/123.

The Create Folder response:

{
  "name": "operations/fc.123456789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "CREATE"
  }
}

The Get Operation curl request:

curl -H "Authorization: Bearer ${bearer_token}" \
https://cloudresourcemanager.googleapis.com/v3/operations/fc.123456789

The Get Operation response:

{
  "name": "operations/fc.123456789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "CREATE"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.Folder",
    "name": "folders/12345",
    "parent": "organizations/123",
    "displayName": "[DISPLAY_NAME]",
    "lifecycleState": "ACTIVE",
    "createTime": "2017-07-19T23:29:26.018Z",
    "updateTime": "2017-07-19T23:29:26.046Z"
  }
}

Grant folder administrator roles

For each sub-organization folder you create, grant one or more users the Folder Admin role. These users will have administrative control over the folder and the sub-organization it represents.

To configure access to folders, you must have the Folder IAM Administrator or Folder Admin role at the parent level.

Console

In the Google Cloud console, open the Manage Resources page.
Open the Manage Resources page
Click the Organization drop-down list in the upper left and then select your organization resource.
Select the checkbox next to the project for which you want to change permissions.
1. On the right side Info panel, under Permissions, enter the email addresses of the members you want to add.
2. In the Select a role drop-down list, select the role you want to grant to those members.
3. Click Add. A notification appears to confirm the addition or update of the members' new role.

gcloud

You can configure access to Folders programmatically using the Google Cloud CLI or the API.

gcloud resource-manager folders \
  add-iam-policy-binding [FOLDER_ID] \
  --member=user:email1@example.com \
  --role=roles/resourcemanager.folderEditor

gcloud resource-manager folders \
  add-iam-policy-binding [FOLDER_ID] \
  --member=user:email1@example.com \
  --role=roles/resourcemanager.folderViewer

Alternatively:

gcloud resource-manager folders \
  set-iam-policy [FOLDER_ID] [POLICY_FILE]

Where:

[FOLDER_ID] is the new folder's ID.
[POLICY_FILE] is the path to a policy file for the folder.

API

The setIamPolicy method sets the access control policy on a folder, replacing any existing policy. The resource field should be the folder's resource name, for example, folders/1234.

 request_json= '{
   policy: {
     version: "1",
     bindings: [
       {
         role: "roles/resourcemanager.folderEditor",
         members: [
           "user:email1@example.com",
           "user:email2@example.com",
         ]
       }
     ]
   }
 }'

The curl request:

   curl -X POST -H "Content-Type: application/json" \
   -H "Authorization: Bearer ${bearer_token}" \
   -d "$request_json" \
   https://cloudresourcemanager.googleapis.com/v3/[FOLDER_NAME]:setIamPolicy

Where:

[FOLDER_NAME] is the name of the folder whose IAM policy is being set, for example folders/123.

Restricting sub-organization roles

Each Folder Admin can restrict the Project Creator role to members of its sub-organization. They can remove the domain from the Project Creator role in the organization resource's IAM policy as well.

Google Workspace super administrators have irrevocable Organization Administrator privileges. These super admins typically manage the identities and identity policies, rather than managing Google Cloud resources and resource policies.

Console

To remove the roles assigned to users by default using the Google Cloud console:

Go to the Manage resources page in the Google Cloud console:
Open the Manage resources page
Click the Organization drop-down list at the top of the page and then select your organization resource.
Select the check box for the organization resource for which you want to change permissions. If you do not have a Folder resource, the organization resource will not be visible. To continue, see the instructions for revoking roles through the IAM page.
On the right side Info Panel, under Permissions, click to expand the role from which you want to remove users.
Under the expanded role list, next to the principal you want to remove from the role, click remove.
On the Remove principal? dialog that appears, click Remove to confirm removing the role from the specified principal.
Repeat the above two steps for each role you want to remove.

Example

The diagram below illustrates an organization that has used folders to separate two departments. The heads of the engineering and finance departments have administrative control, and other users are prevented from creating projects.

Diagram of hierarchy

Managing multiple organizations under a primary organization resource

If your organization has multiple Google Workspace accounts, you will have multiple organization resources by default. To maintain central visibility and control, you should choose one organization resource to be the primary organization resource. The super administrators of the Google Workspace account associated with your primary organization resource will have administrative control over all resources, including those created by users from the other Google Workspace accounts. Users from those Google Workspace accounts will be granted access to a folder under the primary organization resource, in which they will be able to create projects.

Choose an Organization Administrator

Choose one or more users to act as the IAM Organization Administrator for the organization resource.

Console

To add an Organization Administrator:

Sign in to the Google Cloud console as a Google Workspace or Cloud Identity super administrator and navigate to the IAM & Admin page:
Open the IAM & admin page
Select the organization resource you want to edit:
1. Click the project drop-down list at the top of the page.
2. In the Select from dialog, click the organization drop-down list, and select the organization resource to which you want to add an Organization Administrator.
3. On the list that appears, click the organization resource to open its IAM Permissions page.
Click Add, and then enter the email address of one or more users you want to set as Organization Administrators.
In the Select a role drop-down list, select Resource Manager > Organization Administrator, and then click Save.

The Organization Administrator can do the following:
- Take full control of the organization resource. Separation of responsibilities between Google Workspace or Cloud Identity super administrator and Google Cloud administrator is established.
- Delegate responsibility over critical functions by assigning the relevant IAM roles.

Remove Project Creator role

Remove the Project Creator role from the organization resource to ensure that resources are not created in the other organization resources.

Console

To remove the roles assigned to users by default using the Google Cloud console:

Go to the Manage resources page in the Google Cloud console:
Open the Manage resources page
Click the Organization drop-down list at the top of the page and then select your organization resource.
Select the check box for the organization resource for which you want to change permissions. If you do not have a Folder resource, the organization resource will not be visible. To continue, see the instructions for revoking roles through the IAM page.
On the right side Info Panel, under Permissions, click to expand the role from which you want to remove users.
Under the expanded role list, next to the principal you want to remove from the role, click remove.
On the Remove principal? dialog that appears, click Remove to confirm removing the role from the specified principal.
Repeat the above two steps for each role you want to remove.

Create folders for Google Workspace accounts

Create a folder under the organization resource for each Google Workspace account.

As part of creating a folder, you must assign it a name. Folder names must meet the following requirements:

The name may contain letters, digits, spaces, hyphens and underscores.
The folder's display name must start and end with a letter or digit.
The name must be between 3 and 30 characters.
The name must be distinct from all other folders that share its parent.

To create a folder:

Console

Folders can be created in the UI using the "Manage Projects and Folders" section.

Go to the Manage resources page in the Google Cloud console:
Open the Manage resources page
Make sure that your organization resource name is selected in the organization drop-down list at the top of the page.
Click Create folder, and select one of the following options:
- Standard folder: A standard folder resource.
- Compliant folder: An Assured Workloads folder, which provides additional regulatory, regional, or sovereign controls for Google Cloud resources. Selecting this option will take you to Assured Workloads to create a folder.
In the Folder name box, enter your new folder's name.
Under Destination, click Browse, then select the organization resource or folder under which you want to create your new folder.
1. Click Create.

gcloud

Folders can be created programmatically using the Google Cloud CLI.

To create a folder under the organization resource using the gcloud command-line tool, run the following command.

gcloud resource-manager folders create \
   --display-name=[DISPLAY_NAME] \
   --organization=[ORGANIZATION_ID]

To create a folder whose parent is another folder:

gcloud resource-manager folders create \
   --display-name=[DISPLAY_NAME] \
   --folder=[FOLDER_ID]

Where:

[DISPLAY_NAME] is the folder's display name. No two folders with the same parent can share a display name. The display name must start and end with a letter or digit, may contain letters, digits, spaces, hyphens and underscores, and can be no longer than 30 characters.
[ORGANIZATION_ID]is the ID of the parent organization resource if the parent is an organization resource.
[FOLDER_ID] is the ID of the parent folder, if the parent is a folder.

API

Folders can be created with an API request.

The request JSON:

request_json= '{
  display_name: DISPLAY_NAME,
  parent: ORGANIZATION_NAME
}'

The Create Folder curl request:

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ${bearer_token}" \
-d "$request_json" \
https://cloudresourcemanager.googleapis.com/v3/folders

Where:

[DISPLAY_NAME] is the new folder's display name, for example "My Awesome Folder."
[ORGANIZATION_NAME] is the name of the organization resource under which you're creating the folder, for example organizations/123.

The Create Folder response:

{
  "name": "operations/fc.123456789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "CREATE"
  }
}

The Get Operation curl request:

curl -H "Authorization: Bearer ${bearer_token}" \
https://cloudresourcemanager.googleapis.com/v3/operations/fc.123456789

The Get Operation response:

{
  "name": "operations/fc.123456789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "CREATE"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.Folder",
    "name": "folders/12345",
    "parent": "organizations/123",
    "displayName": "[DISPLAY_NAME]",
    "lifecycleState": "ACTIVE",
    "createTime": "2017-07-19T23:29:26.018Z",
    "updateTime": "2017-07-19T23:29:26.046Z"
  }
}

Grant folder administrator roles

For each of the folders created, grant one or more users the Folder Admin role. These users will be delegated administrative control over the folder and the sub-organization it represents.

To configure access to folders, you must have the Folder IAM Administrator or Folder Admin role at the parent level.

Console

In the Google Cloud console, open the Manage Resources page.
Open the Manage Resources page
Click the Organization drop-down list in the upper left and then select your organization resource.
Select the checkbox next to the project for which you want to change permissions.
1. On the right side Info panel, under Permissions, enter the email addresses of the members you want to add.
2. In the Select a role drop-down list, select the role you want to grant to those members.
3. Click Add. A notification appears to confirm the addition or update of the members' new role.

gcloud

You can configure access to Folders programmatically using the Google Cloud CLI or the API.

gcloud resource-manager folders \
  add-iam-policy-binding [FOLDER_ID] \
  --member=user:email1@example.com \
  --role=roles/resourcemanager.folderEditor

gcloud resource-manager folders \
  add-iam-policy-binding [FOLDER_ID] \
  --member=user:email1@example.com \
  --role=roles/resourcemanager.folderViewer

Alternatively:

gcloud resource-manager folders \
  set-iam-policy [FOLDER_ID] [POLICY_FILE]

Where:

[FOLDER_ID] is the new folder's ID.
[POLICY_FILE] is the path to a policy file for the folder.

API

The setIamPolicy method sets the access control policy on a folder, replacing any existing policy. The resource field should be the folder's resource name, for example, folders/1234.

 request_json= '{
   policy: {
     version: "1",
     bindings: [
       {
         role: "roles/resourcemanager.folderEditor",
         members: [
           "user:email1@example.com",
           "user:email2@example.com",
         ]
       }
     ]
   }
 }'

The curl request:

   curl -X POST -H "Content-Type: application/json" \
   -H "Authorization: Bearer ${bearer_token}" \
   -d "$request_json" \
   https://cloudresourcemanager.googleapis.com/v3/[FOLDER_NAME]:setIamPolicy

Where:

[FOLDER_NAME] is the name of the folder whose IAM policy is being set, for example folders/123.

Each Folder Admin can then grant users from the associated domain the Project Creator role.

Example

The diagram below illustrates an organization with a primary domain that is kept isolated from an acquired secondary domain. Each of the two domains have their own Google Workspace accounts, with hypothetical.com being the primary organization resource.

Diagram of hierarchy