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:
- 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.
- 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.
- 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.
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
- In the Google Cloud console, open the Manage resources page.
Click the Organization drop-down list in the upper left and then select your Organization from the list of resources.
In the Add members text box on the right, enter your email address.
In the Select a role drop-down list box, go to the Resource Manager category, and select the Folder Admin role.
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: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/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.
Go to the Manage resources page in the Google Cloud console:
Make sure that your organization resource name is selected in the organization drop-down list at the top of the page.
Click Create 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.
- 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 exampleorganizations/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
In the Google Cloud console, 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.
On the right side Info panel, under Permissions, enter the email addresses of the members you want to add.
In the Select a role drop-down list, select the role you want to grant to those members.
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.
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
- In the Google Cloud console, open the Manage resources page.
- Go to the Manage resources page.
- Select your organization resource from the Organization drop-down on the top left of the page.
- Click Create Project.
- Enter a Project name.
In the Destination box, click Browse to select the folder under which you want to create the project.
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.
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:
In the Google Cloud console, go to the Manage resources page.
Select your Organization from the Organization drop-down on the top left of the page.
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.
Click on the options menu (the vertical ellipsis) in the row and click Move.
Click Browse to select the folder to which you want to move the project.
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
orfolder
.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.
- In the Google Cloud console, open the Manage resources page.
- Select your organization resource from the Organization drop-down on the top left of the page.
- Click on your folder's row to select your folder from the list of projects and folders.
- Click on the options menu (the vertical ellipsis) in the row and click Move.
- Click Browse to select the folder to which you want to move the folder.
- 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 example98765
.[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
In the Google Cloud console, open the Manage resources page.
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.
Select any row in the tree to perform folder- or project-specific operations.
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 thefilter
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
orfolders/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>
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.
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>
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 …>