Transfer Cloud Storage hierarchical namespace buckets
Stay organized with collectionsSave and categorize content based on your preferences.
Cloud Storage hierarchical namespace stores data in a logical file system
structure, using folders to organize objects. For details, seeHierarchical namespace.
Storage Transfer Service can transfer to and from Cloud Storage buckets that use
hierarchical namespace. To successfully transfer the folders and folder
metadata, additional permissions must be granted to the Storage Transfer Service
service agent.
Required permissions
In addition to the standard permissions required for a transfer, the
Storage Transfer Service service agent must be granted the following IAM permissions.
When the source is a hierarchical namespace bucket:
storage.folders.liston the source bucket. This permission is included in
the Storage Object Viewer (roles/storage.objectViewer) role that isrequired for all transfers. No additional role is required.
When the destination is a hierarchical namespace bucket:
storage.folders.createon the destination bucket. This permission is
included in the Storage Object User (roles/storage.objectUser) role. Grant
this role in addition to the roles listed inAgentless transfer permissions.
For instructions on adding roles to the service agent, see:
When transferring between two hierarchical namespace buckets:
Objects and object metadata are transferred.
Folders and folder metadata are transferred.
Deletion of folders at source or sink is not supported.
When transferring from a hierarchical namespace bucket to a flat namespace
bucket:
Objects and object metadata are transferred.
Folders are transferred as object prefixes. For example,object1infolderAis transferred to the destination asfolderA/object1.
Folder metadata is not transferred.
Deletion of folders at source is not supported.
When transferring from a flat namespace bucket to a hierarchical namespace
bucket:
Objects and object metadata are transferred.
Object prefixes are used to create any missing folders. For example, when
transferringfolderA/object1, Storage Transfer Service creates a new folder calledfolderAand transfersobject1into that folder.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Transfer Cloud Storage hierarchical namespace buckets\n\nCloud Storage hierarchical namespace stores data in a logical file system\nstructure, using folders to organize objects. For details, see\n[Hierarchical namespace](/storage/docs/hns-overview).\n\nStorage Transfer Service can transfer to and from Cloud Storage buckets that use\nhierarchical namespace. To successfully transfer the folders and folder\nmetadata, additional permissions must be granted to the Storage Transfer Service\nservice agent.\n| **Note:** Cross-bucket replication is not supported for hierarchical namespace buckets.\n\nRequired permissions\n--------------------\n\nIn addition to the standard permissions required for a transfer, the\nStorage Transfer Service service agent must be granted the following IAM permissions.\n\nWhen the source is a hierarchical namespace bucket:\n\n- `storage.folders.list` on the source bucket. This permission is included in the Storage Object Viewer (`roles/storage.objectViewer`) role that is [required for all transfers](/storage-transfer/docs/iam-cloud#manually_assigning_roles). No additional role is required.\n\nWhen the destination is a hierarchical namespace bucket:\n\n- `storage.folders.create` on the destination bucket. This permission is included in the Storage Object User (`roles/storage.objectUser`) role. Grant this role in addition to the roles listed in [Agentless transfer permissions](/storage-transfer/docs/iam-cloud#manually_assigning_roles).\n\nFor instructions on adding roles to the service agent, see:\n\n- [Configure access to a source: Cloud Storage](/storage-transfer/docs/source-cloud-storage#grant_the_required_permissions)\n- [Configure access to a sink: Cloud Storage](/storage-transfer/docs/sink-cloud-storage#grant_the_required_permissions)\n\nTransfer behavior\n-----------------\n\nWhen transferring between two hierarchical namespace buckets:\n\n- Objects and object metadata are transferred.\n- Folders and folder metadata are transferred.\n- Deletion of folders at source or sink is not supported.\n\nWhen transferring from a hierarchical namespace bucket to a flat namespace\nbucket:\n\n- Objects and object metadata are transferred.\n- Folders are transferred as object prefixes. For example, `object1` in `folderA` is transferred to the destination as `folderA/object1`.\n- Folder metadata is not transferred.\n- Deletion of folders at source is not supported.\n\nWhen transferring from a flat namespace bucket to a hierarchical namespace\nbucket:\n\n- Objects and object metadata are transferred.\n- Object prefixes are used to create any missing folders. For example, when transferring `folderA/object1`, Storage Transfer Service creates a new folder called `folderA` and transfers `object1` into that folder.\n- Deletion of folders at sink is not supported."]]
