Plan your bucket relocation
To successfully relocate buckets, define your objectives and understand yourbucket's usage before initiating abucket relocation. The followingsections describe the key planning steps.
Determine your bucket relocation type
When relocating your bucket, it's important to understand that there might be awrite downtime period during the final synchronization step where you can'tupdate or upload new objects. Additionally, you won't be able to change yourbucket's configuration during the relocation process. To determine if yourrelocation involves downtime, seeRelocation types.
Review the unsupported features and the compatibility requirements
Identify any configurations in your source bucket that don't support bucketrelocation and the configurations that require action to support bucketrelocation. If your bucket uses unsupported configurations that can't bemodified, or if the source or destination is anunsupported location, youmust manually copy the objects into a different bucket in the destinationlocation, instead of relocating the bucket with its objects. For details, seeMove data between buckets.
The following sections describe the unsupported features and the compatibility requirements.
Unsupported features
The following table describes the features that aren't compatible with bucketrelocation. In some cases, you can reconfigure a feature to support bucketrelocation:
| Feature | Compatibility status | Required action before initiating the bucket relocation |
|---|---|---|
| Hierarchical namespace | Not supported for bucket relocations with write downtime. | If a bucket has hierarchical namespace enabled, you can only relocate it if the process doesn't involve write downtime |
| Appspot buckets | Not supported. | You can't relocate Appspot buckets. Consider migrating Container Registry to Artifact Registry as a workaround for default buckets created by App Engine. |
| Firebase buckets | Not supported. | You can't relocate Firebase buckets. |
| Object holds | Not supported. You can't relocate buckets containing objects with holds. | To use bucket relocation, remove the object holds. |
| Managed folders | Not supported. You can't relocate buckets containing managed folders. | To use bucket relocation, delete the managed folders. |
| Customer-managed encryption keys (CMEK) orcustomer-supplied encryption keys (CSEK) | Not supported for relocations with write downtime. | To use bucket relocation, remove the customer-managed encryption keys or customer-supplied encryption keys. After removal, Cloud Storage automatically protects your data using thestandard Cloud Storage encryption. |
| Anywhere Cache | Supported for bucket relocations without write downtime and partially supported for bucket relocations with write downtime. | For relocating buckets with write downtime, disable Anywhere Cache before thefinal synchronization step. |
| Bucket lock | Not supported when retention policies are locked. | Unlock the retention policies. |
| Tags | Not supported for relocations with write downtime. | You must detach tags that are directly attached to the bucket. Note: Tags created at the project or organizationlevel, but not directly attached to the bucket, don't prevent relocation.If any of the tagsbeing detached from your source bucket are used for access control, you must use an alternative method to set up theIAMroles to secure the data in your bucket. To do so,complete the following steps:
|
| Inventory reportconfigurations | Existing inventory reportconfigurations aren't preserved during the relocation process. | Saveyour existing inventory report configurations manually before starting therelocation process, so that you can recreate them after the relocationprocess is complete. For information about managing inventory reportconfigurations, seeCreate and manageinventory report configurations. |
Feature compatibility during bucket relocation
The following table describes how other Cloud Storage capabilities workwhen you relocate a bucket. The behavior might vary depending on the relocationmode:
| Feature | Relocation with write downtime | Relocation without write downtime |
|---|---|---|
| Autoclass behavior | Autoclass is temporarily paused during the final synchronization step. The pause might delay objects moving to colder storage classes. Fordetails, seeAutoclass object transitions when relocating buckets. | Autoclass behavior isn't affected. |
| BigQuery and BigLake tables | BigLake external tables and BigQuery tables using Apache Iceberg become inaccessible after a relocation and require manual recreation. Automatic detection of impacted tables isn't available. | Supported. |
| Object size limit | 2 TB limit applies to object sizes. | No size limit. |
| Multipart uploads | Compatibility and behavior formultipart uploads depend on the status of the upload when you start a bucket relocation:
| Compatibility and behavior for multipart uploads depend on the status of the upload when you start a bucket relocation:
|
| Resumable uploads | Not supported. In-progress resumable uploads must be finalized before the final synchronization step of the bucket relocation process to avoid data loss. | Supported. |
| Relocation across projects | Not supported. You can't relocate buckets across projects. | Supported. |
| Metadata updates | Not supported. You can't update a bucket's metadata during relocation. | Supported. |
| Request rate ramp-up | Relocated buckets are subject to the same request rate ramp-up guidelines as newly created buckets. | Not applicable. |
Analyze the bucket characteristics
To estimate your bucket relocation time, analyze your bucket's characteristicsand usage, considering the following factors:
At-rest bytes: The total amount of data stored in the bucket impactsstorage costs and transfer time.
Replication: Replicating the bucket to other regions, eithersynchronously or asynchronously, impacts data availability, durability, andcost. For details, seeData availability and durability.
Data transfer: The amount of data transferred out of the bucket duringthe relocation impacts the data transfer cost calculations. To calculateyour bucket's data transfer costs, seeCloud Storage pricing.
Usage patterns: Understanding bucket activity levels, or how busy thebucket is, through usage patterns helps you prevent unexpected conflictsduring the relocation. To understand your bucket's usage patterns, you cananalyze your logs. For details, seeUsage logs and storage logs.
Bucket write operations: Frequent bucket write operations during therelocation process increase the cost and duration. To understand howfrequently objects are being written to your bucket, seeOverview ofmonitoring in Cloud Storage.
Define your relocation goals
Based on your analysis of the bucket characteristics, identify the reasons formoving your bucket. The following are common goals for relocating a bucket:
Cost management: Reduce storage costs by moving to a lower-cost regionor minimize data transfer costs by moving data closer to its accesslocation. You'll need to calculate your Cloud Storage and data transfercosts and compare them to potential costs in different locations. Fordetails about calculating costs for your Cloud Storage, seeCloud Storage pricing.
Performance enhancement: Improve data access speed and applicationperformance by relocating the bucket closer to users or applications. To doso, identify the geographic regions where performance is critical andrelocate your buckets.
Reliability improvement: Enhance data durability and disaster recoverycapabilities by using dual- or multi-region configurations.
Decide on the bucket location
Based on your analysis and goals, choose the most suitable storage location forthe bucket you're relocating from the following options:
Single-region: Store data in a single region that is cost-effective forapplications with users concentrated in one geographic area.
Dual-region: Maintain two copies of your data in two regions within thesame continent, providing higher availability and disaster recoverycapabilities within a specific geographic area.
Multi-region: Distribute data across multiple regions, offering thehighest level of availability and durability.
To learn more about choosing a location, seeConsiderations for choosing alocation.
Understand the factors that affect the relocation time
Several factors affect the relocation time, and understanding them can helpto estimate the required time. While these factors offer a helpful starting pointfor planning and scheduling your relocation, actual relocation times might belonger or shorter than the estimated time. Therefore, when scheduling yourrelocation, add buffer time to account for potential delays. The followingsections describe the factors that affect the relocation time.
Note: When estimating the time needed for relocating buckets, include a 1-2 hoursetup time. The setup time includes validating the new bucket destination andpreparing for the move. The setup time is the same for all buckets regardless ofthe bucket size. For small buckets, the setup time makes the entire relocationseem slow. For large buckets, the actual data transfer takes longer, so thesetup time is less noticeable.Relocation service limits
The following table describes the limits that affect the relocation time:
| Factor | Value | Description |
|---|---|---|
| Maximum request rate per job | 10,000 objects per second | These are the number of copy requests the service can handle per second. A higher request rate means more files can be moved simultaneously. If your bucket has many small files, a high request rate speeds up the migration. If you have only a few large files, this factor has less impact. |
| Maximum overall bandwidth per project | 10 GBps | This is the maximum speed or bandwidth at which you can transfer data for a single project within a source location. If you're moving multiple buckets within the same project, then the buckets share the bandwidth. A higher bandwidth means more data can be transferred at once. Even with a high request rate, if the bandwidth is small, the overall transfer is slow. |
| Maximum bandwidth per single object | 8 MBps | This is the maximum speed at which you can transfer a single object. A higher bandwidth per single object means you can transfer the objects at a faster rate. This is the speed limit for moving one object at a time. Even with a high request rate and high bandwidth per bucket, if individual objects have a speed limit, they can take more time to transfer. |
| Maximum concurrent relocations per project | 30 relocations | The bucket relocation service supports up to 30 concurrent relocations from the same location within a project. |
Relocation Time to Live limit
To help with resource utilization and prevent relocations from runningindefinitely, a Time to Live (TTL) limit applies to all bucket relocations. TTLrefers to the maximum time allowed for the entire relocation process tocomplete.
The maximum time allowed to complete a bucket relocation is28 days and includes all phases of the relocation process, such as the initialcopy, incremental updates, and final synchronization.
If the relocation process exceeds the 28-day TTL limit, the relocation operationfails.
Ongoing bucket activity
If you continue to write new objects, delete existing ones, or update objectsin the bucket during the relocation, these operations compete for resourceswith the copy requests and can slow down the relocation process.
Lifecycle rules
If you have lifecycle rules configured for your bucket, such as automaticallydeleting or archiving objects after a specific time, these actions increasethe overall relocation time.
Configure Storage Intelligence
You must configure Storage Intelligence for both the source anddestination locations. You can configure Storage Intelligence atdifferent levels of yourGoogle Cloud resource hierarchy. You can also useinclusion and exclusion filters to include relevant buckets in yourStorage Intelligence configuration. For details, seeConfigureStorage Intelligence.
Enable soft delete
Bucket relocation requires that you enablesoft delete on thebucket and set theretention duration to at least seven days. Theretention duration is the amount of time that soft delete keeps deletedobjects before permanently deleting them. Forinformation about how to configure the soft delete retention duration,seeUse soft delete.
Note: When you relocate a bucket, all objects, including those that aresoft-deleted, move with it. To reduce the overall data in a bucket you plan torelocate, permanently delete any unwanted objects before enablingsoft delete on that bucket.Check quotas and limits
Quotas and cloud capacity assessments are tied to specific regions or zones. Asa result, when you move a bucket to a new location, you need to verify that thenew location has sufficient quotas to accommodate the bucket's data. For moreinformation about quotas and limits, seeQuotas and limits.
What's next
- Learn how torelocate buckets.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.