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 field, 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
Replace ORGANIZATION_NAME
with the name of the organization 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, 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.
- 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 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"
}
}
Add tags during folder creation
Tags provide a way to create annotations for resources. You can add tags at the time of creating folders. To do this, you must grant the Tag User role. For more information on the permissions contained in this role, see Manage tags on resources. You can only add the namespace for the tag key-value pairs in one of the following ways:
gcloud
To add tags during folder creation, run the following command:
gcloud resource-manager folders create \
--display-name=DISPLAY_NAME \
--organization=ORGANIZATION_ID
--tags=KEY_VALUE_PAIRS
Replace the following:
DISPLAY_NAME
is the folder's display name.ORGANIZATION_ID
is the unique identifier of the parent organization resource.KEY_VALUE_PAIRS
is a comma-separated list of key-value pairs that you can assign to your resource. An example of comma-separated key-value pairs is123/environment=production, 456/create=testresource
.
API
The following snippet is a JSON request that creates a folder and adds tags to it.
POST https://cloudresourcemanager.googleapis.com/v3/projects/
Authorization: *************
Content-Type: application/json
{
"display_name": "our-folder-456",
"parent": "organizations/123",
"tags": {
"key": "123/environment"
"value": "production"
},
"tags": {
"key": "123/costCenter"
"value": "marketing"
}
}
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
Replace the following:
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
Replace the following:
PROJECT_ID
is the unique identifier of the project being created. For example,my-awesome-proj-123
.DISPLAY_NAME
is the display name of the project being created.PARENT_ID
is the unique identifier of the parent being created under. For example,123
.PARENT_TYPE
is the type of the parent, likefolder
ororganization
.
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 won't move.
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 to 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 your folder's row to select your folder from the list of projects and folders.
- Click 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]
Replace the following:
[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
Replace the following:
[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 get details of one folder, use the resource-manager folders describe
command.
gcloud resource-manager folders describe FOLDER_ID
Replace FOLDER_ID
with the ID of the folder you want
to view.
To list the child folders of an organization resource, use the
resource-manager folders list
command.
gcloud resource-manager folders list \
--organization ORGANIZATION_ID
Replace ORGANIZATION_ID
with the ID of the
organization resource for which you want to see a list of child folders.
To list the child folders of a folder resource, use the
resource-manager folders list
command.
gcloud resource-manager folders list \
--folder FOLDER_ID
Replace FOLDER_ID
with the ID of the
folder resource for which you want to see a list of child folders.
To list the projects under an organization or folder resource or folder, use
the projects list
command with the filter
argument.
gcloud projects list \
--filter=" parent.id: 'RESOURCE_ID' "
Replace RESOURCE_ID
with the ID of the
organization or folder 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]
Replace FOLDER_NAME
with the name of the folder, such as 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]
Replace PARENT_NAME
with 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>
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 …>