Create and manage managed folders

This guide describes how to create, list, and delete managed folders.

Before you begin

Before you begin, make sure you have the required Identity and Access Management (IAM) role to create and manage managed folders, and enable uniform bucket-level access.

Get required roles

To get the permissions that you need to create and manage managed folders, ask your administrator to grant you the Storage Folder Admin (roles/storage.folderAdmin) IAM role for the bucket.

This predefined role contains the permissions required to create and manage managed folders. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

• storage.managedfolders.create
• storage.managedfolders.delete
• storage.managedfolders.get
• storage.managedfolders.list
• storage.objects.list
  • This permission is only required if you want to validate newly created managed folders by listing them.

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

For information about granting roles on buckets, see Use IAM with buckets.

Enable uniform bucket-level access

If you haven't already, enable uniform bucket-level access.

Create a managed folder

Console

When using the Google Cloud console, you create managed folders by converting simulated folders. The following steps describe how to create a simulated folder and convert it to a managed folder.

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   

   Go to Buckets

2. In the list of buckets, click the name of the bucket you want to create managed folders in.

3. In the Bucket details page, click Create folder to create a new folder. If the folder you want to convert to a managed folder already exists, skip to the step describing how to access the More options menu.

4. In the Name field, enter a name for your folder. For naming considerations, see Managed folder names.

5. Click Create.

   Your newly created folder appears in the Folder browser pane.

6. In the Folder browser pane, click the More options menu next to the folder you want to convert to a managed folder and click Edit access.

   The Create managed folder dialog appears.

7. Click Attach managed folder.

   Your folder converts to a managed folder. A Permissions for MANAGED_FOLDER_NAME pane appears that displays the IAM policies on the folder by principal and role. To create new IAM policies, see Set an IAM policy on a managed folder.

Command line

To create a managed folder, run the gcloud storage managed-folders create command:

gcloud storage managed-folders create gs://BUCKET_NAME/MANAGED_FOLDER_NAME

Where:

• BUCKET_NAME is the name of the bucket in which you want to create a managed folder. For example, my-bucket.

• MANAGED_FOLDER_NAME is the name of the managed folder you want to create. For example, my-managed-folder/.

To confirm that the managed folder was created, run the gcloud storage managed-folders describe command:

gcloud storage managed-folders describe gs://BUCKET_NAME/MANAGED_FOLDER_NAME

Where:

• BUCKET_NAME is the name of the bucket in which you created a managed folder.

• MANAGED_FOLDER_NAME is the name of the managed folder you created.

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, in order to generate an access token for the Authorization header.

   Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.

2. Use cURL to call the JSON API with a POST ManagedFolder request:

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -d '{ "name": "MANAGED_FOLDER_NAME" }' \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/managedFolders"

   Where:

   • BUCKET_NAME is the name of the bucket in which you want to create a managed folder. For example, my-bucket.

   • MANAGED_FOLDER_NAME is the name of the managed folder you want to create. For example, my-managed-folder/.

List managed folders

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   

   Go to Buckets

2. From the Folder browser pane, use the toggle node to expand the list of folders within your bucket.

A list displays the simulated and managed folders in your bucket.

Command line

To list managed folders, run the gcloud storage managed-folders list command:

gcloud storage managed-folders list gs://BUCKET_NAME

Where:

• BUCKET_NAME is the name of the bucket that contains the managed folders you want to list. For example, my-bucket.

Note that you can also specify a folder path instead of a bucket name. For example:

gcloud storage managed-folders list gs://my-bucket/folder/

REST APIs

JSON API

1. Have gcloud CLI installed and initialized, in order to generate an access token for the Authorization header.

   Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.

2. Use cURL to call the JSON API with a request to list managed folders:

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/managedFolders"

   Where BUCKET_NAME is the name of the bucket that contains the managed folders you want to list. For example, my-bucket.

Move a managed folder

Console

1. Create a new managed folder in the destination bucket.

2. Copy the IAM policies from the original managed folder in the source bucket into the new managed folder in the destination bucket.

3. Copy the objects from the original managed folder in the source bucket to the new managed folder in the destination bucket.

4. Delete the original managed folder from the source bucket.

Command line

To move managed folders and the objects they contain, run the gcloud storage mv command with the --include-managed-folders option:

gcloud storage mv --include-managed-folders gs://SOURCE_BUCKET_NAME/MANAGED_FOLDER_NAME gs://DESTINATION_BUCKET_NAME/MANAGED_FOLDER_NAME

Where:

• SOURCE_BUCKET is the name of your original bucket. For example, my-source-bucket`.

• DESTINATION_BUCKET is the name of the bucket you are moving your managed folder to. For example, my-destination-bucket.

• MANAGED_FOLDER_NAME is the name of the managed folder you're moving. For example, my-managed-folder/.

REST APIs

JSON API

To move managed folders from one bucket to another, complete the following steps:

1. Create a new managed folder in the destination bucket.

2. Copy the IAM policies from the original managed folder in the source bucket to the new managed folder in the destination bucket.

3. Copy the objects from the original managed folder in the source bucket to the new managed folder in the destination bucket.

4. Delete the original managed folder from the source bucket.

Delete a managed folder

Console

1. In the Google Cloud console, go to the Cloud Storage Buckets page.
   

   Go to Buckets

2. In the Bucket details page, click the More options icon next to the managed folder you want to delete.

3. Click Delete folder.

4. To confirm that you want to delete the managed folder, type DELETE in Delete field.

5. Click Delete.

   The managed folder and its contents, including stored objects and other managed folders, are deleted from your Cloud Storage bucket.

Command line

To delete a managed folder and the objects it contains, run the gcloud storage rm command:

gcloud storage rm -r gs://BUCKET_NAME/MANAGED_FOLDER_NAME

Where:

• BUCKET_NAME is the name of the bucket that contains the managed folder you want to delete. For example, my-bucket.

• MANAGED_FOLDER_NAME is the name of the managed folder you want to delete. For example, my-managed-folder/.

REST APIs

JSON API

To delete a managed folder, you must first delete the objects within the managed folder.

1. Have gcloud CLI installed and initialized, in order to generate an access token for the Authorization header.

   Alternatively, you can create an access token using the OAuth 2.0 Playground and include it in the Authorization header.

2. Use cURL to call the JSON API with a DELETE ManagedFolder request:

   curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/managedFolders/MANAGED_FOLDER_NAME"

   Where:

   • BUCKET_NAME is the name of the bucket that contains the managed folder you want to delete. For example, my-bucket.

   • MANAGED_FOLDER_NAME is the name of the managed folder you want to delete. For example, my-managed-folder/.

   By default, managed folders must be empty before they can be deleted. To delete a non-empty managed folder, include allowNonEmpty=true as a query parameter in your request.

Troubleshooting

For help creating and managing managed folders, refer to the Troubleshooting page.

Next steps

• Set an IAM policy on a managed folder.

• List objects in managed folders.