Creating and managing Folders

Folders are nodes in the Cloud Platform Resource Hierarchy. A folder can contain projects, other folders, or a combination of both. Organization resources can use folders to group projects under the organization resource node in a hierarchy. For example, your organization resource might contain multiple departments, each with its own set of Google Cloud resources. Folders allow you to group these resources on a per-department basis. Folders are used to group resources that share common IAM policies. While a folder can contain multiple folders or resources, a given folder or resource can have exactly one parent.

In the diagram below, the organization resource, "Company", has folders representing two departments, "Dept X" and "Dept Y", and a folder, "Shared Infrastructure", for items that might be common to both departments. Under "Dept Y", they have organized into two teams, and within the team folders, they further organize by products. The folder for "Product 1" further contains three projects, each with the resources needed for the project. This provides them with a high degree of flexibility in assigning IAM policies and Organization policies at the right level of granularity.

You can use folder-level IAM policies to control access to the resources the folder contains. For example, if a user is granted the Compute Instance Admin role on a folder, that user has the Compute Instance Admin role for all of the projects in the folder.

Before you begin

Folder functionality is only available to Google Workspace and Cloud Identity customers that have an organization resource. For more information about acquiring an organization resource, see Creating and managing organizations.

If you're exploring how to best use folders, we recommend that you:

1. Review Access Control for Folders Using IAM. The topic describes how you can control who has what access to folders and the resources they contain.
2. Understand how to set folder permissions. Folders support a number of different IAM roles. If you want to broadly set up permissions so users can see the structure of their projects, grant the entire domain the Organization Viewer and Folder Viewer roles at the organization resource level. To restrict visibility to branches of your folder hierarchy, grant the Folder Viewer role on the folder or folders you want users to see.
3. Create folders. As you plan how to organize your Cloud resources, we recommend that you start with a single folder as a sandbox where you can experiment with which hierarchy makes the most sense for your organization resource. Think of folders in terms of isolation boundaries between resources and attach points for access and configuration policies. You may choose to create folders to contain resources that belong to different departments and assign Admin roles on folders to delegate administrator privilege. Folders can also be used to group resources that belong to applications or different environments, such as development, production, test. Use nested folders to model these different scenarios.

A common situation is to create folders that in turn contain additional folders or projects, as shown in the image above. This structure is referred to as a folder hierarchy. When creating a folder hierarchy, keep in mind the following:

• You can nest folders up to 10 (ten) levels deep.
• A parent folder cannot contain more than 300 folders. This refers to direct child folders only. Those child folders can, in turn, contain additional folders or projects.
• Folder display names must be unique within the same level of the hierarchy.

Setting permissions to manage folders

To access and manage folders, you need to assign folder-specific IAM roles to specific groups of users. To learn more about these roles, see Access Control for Folders using IAM. We also recommend you review our best practices to help you identify the optimal configuration for your folder permissions.

Tip: To manage folders for your entire organization resource, you need the Folder Admin role. This role grants the user permission to create, edit, delete, move, and change IAM permissions on folders, as well as permission to move projects between folders.

Initially, only the Organization Admin can assign the Folder Admin role for the organization resource. Subsequent accounts that are assigned this role can grant it to other accounts.

To set up folder permissions:

console

1. In the Google Cloud console, open the Manage resources page.

   Open Manage resources page

2. Click the Organization drop-down list in the upper left and then select your Organization from the list of resources.

3. In the Add members text box on the right, enter your email address.

4. In the Select a role drop-down list box, go to the Resource Manager category, and select the Folder Admin role.

5. Click Add to grant the new role.

gcloud

Folders can be created programmatically using the Google Cloud CLI. To do so, run the following command:

gcloud organizations add-iam-policy-binding [ORGANIZATION_ID] \
--member=user:[USER_ID] \
--role=roles/resourcemanager.folderAdmin

API

The request JSON:

request_json= '{ policy: { version: "1", bindings: [ { role: "roles/folderAdmin",
members: [ "user:[e-mail]", ] }, { role: "roles/folderCreator",
members: [   "user:[e-mail]", ] } , { role: "roles/folderMover",
members: [ "user:[e-mail]", ] } , ] } }'

The curl request:

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

Where:

• [ORGANIZATION_NAME] is the name of the org whose IAM policy is being set, for example organizations/123.

Creating folders

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.

1. Go to the Manage resources page in the Google Cloud console:

   Open the Manage resources page

2. Make sure that your organization resource name is selected in the organization drop-down list at the top of the page.

3. Click Create folder.

4. In the Folder name box, enter your new folder's name.

5. 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]"
}'

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?parent=[ORGANIZATION_NAME]

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"
  }
}

Configuring access to folders

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

Console

1. In the Google Cloud console, open the Manage Resources page.

   Open the Manage Resources page

2. Click the Organization drop-down list in the upper left and then select your organization resource.

3. 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:[e-mail] \
  --role=roles/resourcemanager.folderEditor

gcloud resource-manager folders \
  add-iam-policy-binding [FOLDER_ID] \
  --member=user:[e-mail] \
  --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:[e-mail]",
           "user:[e-mail]",
         ]
       }
     ]
   }
 }'

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.

Creating a project in a folder

To create a project in a folder, you must have the Project Creator role (roles/resourcemanager.projectCreator) on the folder. This role may be inherited from a parent folder.

console

1. In the Google Cloud console, open the Manage resources page.

   Open Google Cloud console

2. Go to the Manage resources page.
3. Select your organization resource from the Organization drop-down on the top left of the page.
4. Click Create Project.
5. Enter a Project name.

6. In the Destination box, click Browse to select the folder under which you want to create the project.

7. Click Create.

gcloud

   gcloud projects create [PROJECT_ID]
      --folder [FOLDER_ID]

Where:

• [PROJECT_ID] is the ID of the project ID to create.
• [FOLDER_ID] is the ID of the folder in which the project should be created.

API

The request JSON:

   request_json= ‘{
      name: “[DISPLAY_NAME]”, projectId: “[PROJECT_ID]”, parent: {id: [PARENT_ID], type: [PARENT_TYPE] }
   }’

The curl request:

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

Where:

• [PROJECT_ID] is id of the project being created, for e.g., my-awesome-proj-123.
• [DISPLAY_NAME] is the display name of the project being created.
• [PARENT_ID] is the id of the parent being created under, for e.g. 123
• [PARENT_TYPE] is the type of the parent, like “folder” or “Organization”

Don't include sensitive information in your folder name or other resource names. Any reference to the folder or related resources exposes the folder name and resource name.

Moving a project into a folder

You must carefully consider any policy implications before you move a project into or out of a folder. Identity and Access Management policies that you define at the project level will move with the project, but policies inherited from a parent resource will not.

Note: The following instructions are only for moving a project within an organization resource. For information about migrating a project between organization resources, see Migrating projects.

When you move a project, any Identity and Access Management policies or organization policies that are directly attached will move with it. However, a project in your resource hierarchy is also affected by the policies that it inherits from parent resources. If a project inherits an IAM role that provides users permission to use a particular service, users will not have access to that service at the destination unless it would inherit the permission at the destination as well.

For example, consider a service account has the Storage Object Creator role bound to a user at Folder A. The service account has permissions to upload data to Cloud Storage in any project in Folder A. If you moved one of these projects Folder B, which does not have the same inherited permissions, the service account for that project loses the ability to upload data, resulting in a service outage.

These same considerations apply if organization policies are defined at the source and destination folders. Like IAM policies, organization policies are inherited. Consequently, you must ensure that your organization policies are consistent between source and destination folders.

To learn more about organization policies, see Introduction to the organization Policy Service.

To move a project, you need the Project Mover IAM role (roles/resourcemanager.projectMover) on both the source folder and the destination folder. If the resource is not in a folder, you need this role on the organization resource.

These roles give you the following required permissions:

• resourcemanager.projects.update on the project
• If the resource is in a folder: resourcemanager.projects.move on the source folder and the destination
• If the resource is not in a folder: resourcemanager.projects.move on the organization resource

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

Console

To move a project:

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. Select your Organization from the Organization drop-down on the top left of the page.

3. Click on your project's row to select your project from the list of resources. Note that you must not click on the name of the project, which takes you to the project's IAM page.

4. Click on the options menu (the vertical ellipsis) in the row and click Move.

5. Click Browse to select the folder to which you want to move the project.

6. Click Move.

gcloud

To move a project, run the gcloud beta projects move command:

gcloud beta projects move PROJECT_ID \
--DESTINATION_TYPE DESTINATION_ID

Where:

• PROJECT_ID is the ID or number of the project you wish to move.

• DESTINATION_TYPE is either organization or folder.

• DESTINATION_ID is the ID of the organization resource or folder to which you want to move the project. You can only specify one target.

API

You can use the v3 projects.move method to move a project.

Request:

POST https://cloudresourcemanager.googleapis.com/v3/{name=PROJECT_NAME}:move
{
  "destinationParent": DESTINATION_PARENT
}

Where:

• PROJECT_NAME is the name of the project you want to update. For example, projects/415104041262

• DESTINATION_PARENT is the new parent organization resource or folder under which you want to move the project. For example: organizations/12345678901

If successful, the request will return an Operation which can be used to track the project move.

Moving a folder into another folder

To move a folder into another folder, you must have the resourcemanager.folders.move permission for both the source and destination folders.

console

The process of moving folders into other folders in the console is similar to moving projects.

1. In the Google Cloud console, open the Manage resources page.

   Open Google Cloud console

2. Select your organization resource from the Organization drop-down on the top left of the page.
3. Click on your folder's row to select your folder from the list of projects and folders.
4. Click on the options menu (the vertical ellipsis) in the row and click Move.
5. Click Browse to select the folder to which you want to move the folder.
6. Click Move.

gcloud

To move a folder under the Organization resource, run the following command in the Google Cloud CLI:

gcloud resource-manager folders move [FOLDER_ID] \
  --organization=[PARENT_ID]

To move a folder under another folder:

gcloud resource-manager folders move [FOLDER_ID] \
  --folder=[PARENT_ID]

Where:

• [FOLDER_ID] is the ID of the folder to move.
• [PARENT_ID] is the Organization resource ID or the folder ID of the parent organization resource or folder.

API

The request JSON:

request_json= '{
   destinationParent: "folders/[DESTINATION_FOLDER_ID]"
}'

The Move 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/[DISPLAY_NAME]:move

Where:

• [DESTINATION_FOLDER_ID] is the ID of the folder under which you're moving another folder, for example 98765.
• [DISPLAY_NAME] is the display name of the folder being moved, for example "My Awesome Folder."

The Move Folder response:

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

The Get Operation curl request:

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

The Get Operation response:

{
  "name": "operations/fm.1234567890",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "MOVE"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v3.Folder",
    "name": "folders/12345",
    "parent": "folders/98765",
    "displayName": "[DISPLAY_NAME]",
    "lifecycleState": "ACTIVE",
    "createTime": "2017-07-19T23:29:26.018Z",
    "updateTime": "2017-07-20T00:54:44.295Z"
  }
}

Viewing or listing folders and projects

To view or list folders, you must have the Organization Viewer and Folder Viewer roles.

To view or list folders and projects:

console

1. In the Google Cloud console, open the Manage resources page.

   Open Manage resources page

2. From the project picker at the top of the page, select your organization resource. Folders must be created before they will appear in this list.

   Note: Up to 4000 resources can be displayed in the project picker. If you do not see a resource that should appear, go to the Manage resources page and filter the list using the name of that resource.

3. Select any row in the tree to perform folder- or project-specific operations.

   Note: the options menu (the vertical ellipsis) on the right column displays options for supported operations.

4. Enter the project or folder name/ID in the search to filter the list.

gcloud

To view a folder, use the describe command.

   gcloud resource-manager folders describe [FOLDER_ID]

   name: folders/245321 \
   parent: organizations/2518 \
   display_name: Super Fantastic Folder \
   lifecycle_state: ACTIVE \
   create_time: <timestamp info …> \
   update_time: <timestamp info …> \

Where:

• [FOLDER_ID] is the ID of the folder you want to view.

  To list the folders under an organization resource, use the list command.

  gcloud resource-manager folders list
  --organization [ORGANIZATION_ID]

  Where:

• [ORGANIZATION_ID] is the ID of the organization resource for which you want to see a list of child folders.

  The command outputs a table that displays the child folders of the organization resource ID you specified.

  The list command can also list the folders under another folder, using the --folder flag.

  gcloud resource-manager folders list
  --folder [FOLDER_ID]

  Where:

• [FOLDER_ID] is the ID of the folder for which you want to see a list of child folders.

  To list the projects under an organization resource or folder, use the projects list command and the filter argument.

  gcloud projects list
  --filter=" parent.id: '[FOLDER_OR_ORGANIZATION_ID]' "

  Where:

• [FOLDER_OR_ORGANIZATION_ID] is the ID of the folder or the organization resource for which you want to see a list of child projects.

API

The curl request to get folders:

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

Where:

• [FOLDER_NAME] is the name of the folder, for example folders/123.

The curl request to list folders:

curl -X GET -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${bearer_token}" \
  https://cloudresourcemanager.googleapis.com/v3/folders?parent=[PARENT_NAME]

Where:

• [PARENT_NAME] is the name of the parent resource under which you’re creating the folder, such as organizations/123 or folders/123.

Using the Google Cloud CLI

Commands for interacting with the Folders API with the gcloud command-line tool are available in the gcloud resource-manager folders command group.

Create

To create a new folder, use gcloud resource-manager folders create with flags setting the name of the folder and the ID of the organization resource or folder in which you'd like it created.

gcloud resource-manager folders create \
  --display-name="Super Fantastic Folder" \
  --organization=2518

Created Folder 245321.

View

To view a folder, use gcloud resource-manager folders describe with the ID of the folder you wish to view.

gcloud resource-manager folders describe 245321
name: folders/245321
parent: organizations/2518
display_name: Super Fantastic Folder
lifecycle_state: ACTIVE
create_time: <timestamp info …>
update_time: <timestamp info …>

List

To list the folders underneath a folder, use gcloud resource-manager folders list, passing the folder ID in the --folder flag. This can also list the top-level folders under an organization resource, using the --organization flag.

gcloud resource-manager folders list --folder 245321
<table output showing the folders underneath the folder with the specified ID>

gcloud resource-manager folders list --organization 2518
<table output showing folders in this Organization but not in any folder>

To include folders for which delete is requested in the list, add the flag --show-deleted

gcloud beta resource-manager folders list --folder 245321 --show-deleted
<table output showing all the folders including the delete requested ones underneath the folder with the specified ID>

Note: --show-deleted flag is currently supported only in alpha and beta versions of the command.

You can list projects using the gcloud projects list command, passing the parent folder or organization resource ID in the --filter flag.

gcloud projects list --filter=" parent.id: '245321' "
<table output showing the projects underneath the resource with the specified ID>

For more information about how permissions and filters interact with list commands, see Listing all Resources in your Hierarchy.

Note: Listing projects and folders will return only the direct descendants of the target resource, and does not show the children's children.

Search

To search for folders matching the specified query, use gcloud alpha resource-manager folders search, passing the condition in the --query flag. The scope of search is all the folders for which the user has view permission.

gcloud alpha resource-manager folders search --query="name:vij*"
<table output showing the folders with names starting from vij eg. vijeta, vijay-folder>

gcloud alpha resource-manager folders search --query="state:DELETE_REQUESTED"
<table output showing folders for which delete has been requested>

All folders for which the user has view permission can be shown using the gcloud folders search command.

gcloud folders search
<table output showing all viewable folders>

Note: The search command is in alpha and can be changed without notice.

Update

Folders can be updated with the gcloud resource-manager folders update command. Currently, only the display_name field of a folder can be updated.

gcloud resource-manager folders update \
  --display-name="Mega Incredible Folder" 245321
name: folders/245321
parent: organizations/2518
display_name: Mega Incredible Folder
lifecycle_state: ACTIVE
create_time: <timestamp info …>
update_time: <recent timestamp info …>

Delete

Folders can be deleted and undeleted from the command line. A user must possess either the Folder Admin or the Folder Editor role to have the permission to delete a folder. You can only delete a folder if it is empty.

gcloud resource-manager folders delete 245321
name: folders/245321
parent: organizations/2518
display_name: Mega Incredible Folder
lifecycle_state: DELETE_REQUESTED
create_time: <timestamp info …>
update_time: <recent timestamp info …>

gcloud resource-manager folders undelete 245321
name: folders/245321
parent: organizations/2518
display_name: Mega Incredible Folder
lifecycle_state: ACTIVE
create_time: <timestamp info …>
update_time: <recent timestamp info …>

Project Move

Projects can be created in folders and moved into folders using the existing gcloud projects create and gcloud projects move commands. Folders can also be moved, using gcloud resource-manager folders move.

gcloud projects create --folder=245321 fancy-folder-project
project_id: fancy-folder-project
project_number: 905283
parent:
  type: "folder"
  id: 245321
other fields …

gcloud projects move --folder=245321 soon-to-be-fancy-project
project_id: soon-to-be-fancy-project
project_number: 428714
parent:
  type: "folder"
  id: 245321
other fields …

Long-Running operations

Some folder operations such as creating folders can take a long time. To make it easier to multitask, some folder commands allow you to perform them asynchronously. These commands accept an --async flag to enable asynchronous behavior, causing them to return a Long-Running Operation immediately instead of waiting for the operation to complete. You can poll this operation yourself with the gcloud beta resource-manager operations describe command. Currently, only the folders create and folders move commands allow asynchronous use.

gcloud resource-manager folders create \
  --display-name="Awe-Inspiring Async Folder" \
  --organization=2518 \
  --async

name: operations/fc.8572
metadata:
  operation_type: CREATE
  display_name: Awe-Inspiring Async Folder
  destination_parent: organizations/2518
done: false

[wait for some time …]

gcloud beta resource-manager operations describe fc.8572
name: operations/fc.8572
metadata:
  operation_type: CREATE
  display_name: Awe-Inspiring Async Folder
  destination_parent: organizations/2518
done: true
response:
  name: folders/6428
  parent: organizations/2518
  display_name: Awe-Inspiring Async Folder
  lifecycle_state: ACTIVE
  create_time: <recent timestamp info …>
  update_time: <recent timestamp info …>