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. You can use folders to group projects under an organization in a hierarchy. For example, your organization might contain multiple departments, each with its own set of GCP resources. Folders allows 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, "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 an Organization policies at the right level of granularity.

Folders hierarchy example

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

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 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. 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 four levels deep.
  • A parent folder cannot contain more the 100 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, 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. Subsequent accounts that are assigned this role can grant it to other accounts.

To set up folder permissions:

console

  1. In the Google Cloud Platform Console, open the Manage Projects and Folders page.

    Open the Google Cloud Platform Console

  2. Open the Project Picker.
  3. Click on the Organization drop-down in the upper left of the Project Picker. (Hovering over the Setting gear will provide a shortcut to the IAM Settings page.)
  4. Select your Organization in the Organization drop-down, and select IAM/Permissions. The IAM page is displayed, which lists all members and corresponding roles for the Organization.

    Select Organization

  5. Locate yourself in the list of members, and open the corresponding Role(s) drop-down.

  6. Go to the Resource Manager category, and grant yourself the Folder Admin role.

    Set the permissions

gcloud

Folders can be created programmatically using the gcloud command-line tool. To do so, run the following command:

gcloud alpha resource-manager folders 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:admin@myorganization.com", ] }, { role: "roles/folderCreator",
members: [   "user:admin@myorganization.com", ] } , { role: "roles/folderMover",
members: [ "user:admin@myorganization.com", ] } , ] } }'

The curl request:

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ${bearer_token}" \
-d "$request_json" \
https://cloudresourcemanager.googleapis.com/v1/[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 30 characters or less.
  • The name must be distinct from all other folders that share its parent.

Folders can be created in the console UI, using the gcloud command-line tool, or the API.

console

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

  1. In the Google Cloud Platform Console, open the Manage Projects and Folders page.

    Open the Google Cloud Platform Console

Screenshot of UI

  1. Click on the "Create folder" icon. Screenshot of UI

  2. Choose your new folder's name and destination. Screenshot of UI

gcloud

Folders can be created programmatically using the gcloud command-line tool or the API.

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

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

To create a folder whose parent is another folder:

$ gcloud alpha 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 if the parent is an Organization.
  • [FOLDER_ID] is the ID of the parent folder, if the parent is a folder.

API

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/v2/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 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.v2.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "CREATE"
  }
}

The Get Operation curl request:

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

The Get Operation response:

{
  "name": "operations/fc.123456789",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v2.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "CREATE"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v2.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 Platform Console, open the Manage Projects and Folders page.

    Open the Google Cloud Platform Console

  2. Open the Project Picker.
  3. Click on the Organization drop-down in the upper left of the Scope Picker and select your organization.

    Screenshot of UI

  4. Select your folder from the Project picker->All and click Open. This takes you to the IAM page for the selected folder, which shows all the users that have access to it.

  5. Click Add.
  6. Enter the email address of a new member to whom you have not granted any IAM role previously.
  7. Select a role from the drop-down menu.

Screenshot of UI

  1. Click Add.

gcloud

You can configure access to Folders programmatically using the gcloud command-line tool or the API.

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

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

Alternatively:

gcloud alpha 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

SetsIamPolicy 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/v2/[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 IAM role on the folder. This role may be inherited from a parent folder.

console

  1. In the Google Cloud Platform Console, open the Manage Projects and Folders page.

    Open the Google Cloud Platform Console

  2. Go to the Manage Projects and Folders page.
  3. Select your organization 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.

    Select the folder

  7. Click Create.

gcloud

   gcloud alpha 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/v1/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”

Moving a project into a folder

To move a project into a folder, you need specific IAM roles on both the project and the source and destination folders. In particular, you must meet one of the following criteria:

  1. Have either Project Editor or Project Owner roles on the project.
  2. Have either Project Owner or Project Mover on both the source and destination folders.

To move a project into the folder using the Google Cloud Platform Console:

console

  1. In the Google Cloud Platform Console, open the Manage Projects and Folders page.

    Open the Google Cloud Platform Console

  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 projects and folders. 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.

    Move a project

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

  6. Click Move.

gcloud

gcloud alpha projects move PROJECT_ID [OPTIONAL_FLAGS]

Where:

  • [PROJECT_ID] is the ID of the project ID to move.
  • [OPTIONAL_FLAGS] may be --folder | --help | --organization | -h

Policy considerations for moving projects into folders

You must carefully consider any policy implications before you move a project into or out of a folder because IAM policies that you define at the project level automatically move with the project, but policies that you define at the source or destination parent level do not.

This means that any users who had inherited access to the project may lose that access if the destination folder does not have the same policy. In addition, changes in IAM roles could cause some functionality to stop working until the proper permissions are reinstated.

For example, consider a service account has Storage Object Creator associated at Folder A. This folder has the appropriate permissions to upload data to Google Cloud Storage in any project in Folder A. Now, consider what happens when one of these projects moves to Folder B, which does not have the same 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.

Moving a folder into another folder

To move a folder into another folder, you must have the Folder Mover role 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 Platform Console, open the Manage Projects and Folders page.

    Open the Google Cloud Platform Console

  2. Select your Organization 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 gcloud command-line tool:

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

To move a folder under another folder:

$ gcloud alpha 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 ID or the folder ID of the parent Organization 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/v2/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.v2.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "MOVE"
  }
}

The Get Operation curl request:

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

The Get Operation response:

{
  "name": "operations/fm.1234567890",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v2.FolderOperation",
    "displayName": "[DISPLAY_NAME]",
    "operationType": "MOVE"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.resourcemanager.v2.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 using the Google Cloud Platform Console:

console

  1. In the Google Cloud Platform Console, open the Manage Projects and Folders page.

    Go to Manage Projects and Folders page

  2. Select your Organization from the Organization drop-down on the top left of the page. All projects and folders under the Organization are displayed on the page. Note that folders must be created before they will appear in this list.
  3. Select any row in the tree to perform folder- or project-specific 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 alpha 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 wish to view.

To list the contents of a folder, use the list command.

   $ gcloud alpha resource-manager folders list \
       --folder [FOLDER_ID]

Where:

  • [FOLDER_ID] is the ID of the folder to move.

The output of the command is a table showing the contents of the folder with the ID specified.

The list command can also list the top-level folders and projects in an Organization, using the --organization flag.

   $ gcloud alpha resource-manager folders list \
       --organization [ORGANIZATION_ID]

Where:

  • [ORGANIZATION_ID] is the ID of the parent Organization if the parent is an Organization. The output of the command is a table showing any projects in this Organization but not in any folder.

API

The curl request to get folders:

curl -X GET -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${bearer_token}" \
  https://cloudresourcemanager.googleapis.com/v2/[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/v2/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 gcloud command line interface

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

Create

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

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

Created Folder 245321.

View

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

$ gcloud alpha 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 contents of a folder, use gcloud alpha resource-manager folders list, passing the folder ID in the --folder flag. This can also list the top- level folders and projects of an Organization, using the --organization flag.

$ gcloud alpha resource-manager folders list --folder 245321
<table output showing the contents of the folder with the specified ID>

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

Update

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

$ gcloud alpha 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.

$ gcloud alpha 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 alpha 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 alpha resource-manager folders move.

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

$ gcloud alpha 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 alpha resource-manager operations describe command. Currently, only the folders create and folders move commands allow asynchronous use.

$ gcloud alpha 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 alpha 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 …>

Send feedback about...

Google Cloud Resource Manager Documentation