Create folders

This page describes how to create Google Cloud folders to group and organize projects in a resource hierarchy. You can use folders to delegate administrative duties, enforce environment-specific organization policies, and streamline cost management across your departments.

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 allow or deny policies. While a folder can contain multiple folders or resources, a given folder or resource can have exactly one parent.

In the following diagram, 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 allow, deny, or organization policies at the right level of granularity.

You can use folder-level allow and deny policies to control access to the resources the folder contains. For example, if a user is granted the Compute Instance Adminrole on a folder, that user has the Compute Instance Adminrole 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 Get an organization resource .

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 Identity and Access Management (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 Viewerand Folder Viewerroles at the organization resource level. To restrict visibility to branches of your folder hierarchy, grant the Folder Viewerrole 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 resource hierarchy earlier. 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.

Set up permissions to manage folders

To access and manage folders, you 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.

To manage folders for your entire organization resource, you need the Folder Adminrole. 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, follow these steps:

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

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

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

Create folders

To create folders, you must have the Folder Adminor Folder Creatorrole 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, follow these steps:

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

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

  reques 
 t 
 _jso 
 n 
 = 
  
 ' 
 { 
  
 display_ 
 na 
 me 
 : 
  
  DISPLAY_NAME 
 
 , 
  
 pare 
 nt 
 : 
  
  ORGANIZATION_NAME 
 
 } 
 ' 
 

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

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

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

  { 
  
 "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 Userrole. For more information on the permissions contained in this role, see Create and manage tags . You can only add the namespace for the tag key-value pairs in one of the following ways:

 gcloud resource-manager folders create \
      --display-name= DISPLAY_NAME 
\
      --organization= ORGANIZATION_ID 
\
      --tags= KEY_VALUE_PAIRS 
 

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

Configure access to folders

To configure access to folders, you must have the Folder IAM Administratoror Folder Adminrole at the parent level.

 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 

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

   
 reques 
 t 
 _jso 
 n 
 = 
  
 ' 
 { 
  
 policy 
 : 
  
 { 
  
 versio 
 n 
 : 
  
 "1" 
 , 
  
 bi 
 n 
 di 
 n 
 gs 
 : 
  
 [ 
  
 { 
  
 role 
 : 
  
 "roles/resourcemanager.folderEditor" 
 , 
  
 members 
 : 
  
 [ 
  
 "user:email1@example.com" 
 , 
  
 "user:email2@example.com" 
 , 
  
 ] 
  
 } 
  
 ] 
  
 } 
  
 } 
 ' 
 

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

Handle long-running operations

Certain folder operations, such as creation or migration, are processed asynchronously by Google Cloud because they require global propagation. To avoid blocking your terminal or automation scripts, you can use the --async flag.

When this flag is used, the command returns a Long-Running Operation (LRO) object immediately. You can then use the operation_id to poll for completion at your convenience. The --async flag is supported for the folders create and folders move commands only.

To use the flag, follow these steps:

1. Start an asynchronous task. Refer to following sample command:

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

   The output provides an operation name (e.g., fc.8572) and shows done: false .

   Sample response:

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

2. Check operation status. To verify if the task has finished, use the operations describe command with the ID provided in the previous step.

    gcloud beta resource-manager operations describe fc.8572 
   

   Once done is true, the response block will contain the full details of the newly created resource.

    name: operations/fc.8572
   done: true
   response:
     name: folders/6428
     display_name: Awe-Inspiring Async Folder
     lifecycle_state: ACTIVE
     create_time: '2024-03-20T10:00:00Z' 
   

What's next

• Learn about viewing and updating folders .
• Learn about managing projects within folders .
• Learn about roles and permissions for folders .
• Learn about listing all folders and projects in your resource hierarchy.