When you create a bucket, you permanently define its name, its geographic location, and the project it is part of. However, you can effectively move or rename your bucket:
If there is no data in your old bucket, delete the bucket and create another bucket with a new name, in a new location, or in a new project.
If you have data in your old bucket, create a new bucket with the desired name, location, and/or project, copy data from the old bucket to the new bucket, and delete the old bucket and its contents. The steps below describe this process.
Note that if you want your new bucket to have the same name as your old bucket, you must move your data twice: an intermediary bucket temporarily holds your data so that you can delete the original bucket and free up the bucket name for the final bucket.
To move your data from one bucket to another:
Step 1) Create a new bucket
Console
- Open the Cloud Storage browser in the Google Cloud Console.
Open the Cloud Storage browser - Click Create bucket to open the bucket creation form.
- Enter your bucket information and click Continue to complete each step:
- Specify a Name, subject to the bucket name requirements.
- Select a Default storage class for the bucket. The default
storage class will be assigned by default to all
objects uploaded to the bucket. Next, select a Location where the bucket data
will be permanently stored.
Note: The Monthly cost estimate panel in the right pane estimates the bucket's monthly costs based on your selected storage class and location, as well as your expected data size and operations.
- Select an Access control model to determine how you control access to the bucket's objects.
- Optionally, you can add bucket labels, set a retention policy, and choose an encryption method.
- Click Done.
gsutil
Use the gsutil mb
command:
gsutil mb gs://[BUCKET_NAME]/
Where:
[BUCKET_NAME]
is the name you want to give your bucket, subject to naming requirements. For example,my-bucket
.
Set the following optional flags to have greater control over the creation of your bucket:
-p
: Specify the project with which your bucket will be associated. For example,my-project
.-c
: Specify the default storage class of your bucket. For example,NEARLINE
.-l
: Specify the location of your bucket. For example,US-EAST1
.-b
: Enable uniform bucket-level access for your bucket.
For example:
gsutil mb -p [PROJECT_NAME] -c [STORAGE_CLASS] -l [BUCKET_LOCATION] -b on gs://[BUCKET_NAME]/
Code samples
C++
For more information, see the Cloud Storage C++ API reference documentation .
C#
For more information, see the Cloud Storage C# API reference documentation .
Go
For more information, see the Cloud Storage Go API reference documentation .
Java
For more information, see the Cloud Storage Java API reference documentation .
Node.js
For more information, see the Cloud Storage Node.js API reference documentation .
PHP
For more information, see the Cloud Storage PHP API reference documentation .
Python
For more information, see the Cloud Storage Python API reference documentation .
Ruby
For more information, see the Cloud Storage Ruby API reference documentation .
REST APIS
JSON API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
- Create a .json file that contains the following information:
[BUCKET_NAME]
is the name you want to give your bucket, subject to naming requirements. For example,my-bucket
.[BUCKET_LOCATION]
is the location where you want to store your bucket's object data. For example,US-EAST1
.[STORAGE_CLASS]
is the default storage class of your bucket. For example,NEARLINE
.- Use
cURL
to call the JSON API:curl -X POST --data-binary @[JSON_FILE_NAME].json \ -H "Authorization: Bearer [OAUTH2_TOKEN]" \ -H "Content-Type: application/json" \ "https://storage.googleapis.com/storage/v1/b?project=[PROJECT_ID]"
Where:
[JSON_FILE_NAME]
is name of the JSON file you created in Step 2.[OAUTH2_TOKEN]
is the access token you generated in Step 1.[PROJECT_ID]
is the ID of the project with which your bucket will be associated. For example,my-project
.
{ "name": "[BUCKET_NAME]", "location": "[BUCKET_LOCATION]", "storageClass": "[STORAGE_CLASS]" }
Where:
XML API
- Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
- Create a .xml file that contains the following information:
[BUCKET_LOCATION]
is the location where you want to store your bucket's object data. For example,US-EAST1
.[STORAGE_CLASS]
is the default storage class of your bucket. For example,NEARLINE
.- Use
cURL
to call the XML API:curl -X PUT --data-binary @[XML_FILE_NAME].xml \ -H "Authorization: Bearer [OAUTH2_TOKEN]" \ -H "x-goog-project-id: [PROJECT_ID]" \ "https://storage.googleapis.com/[BUCKET_NAME]"
Where:
[XML_FILE_NAME]
is name of the XML file you created in Step 2.[OAUTH2_TOKEN]
is the access token you generated in Step 1.[PROJECT_ID]
is the ID of the project with which your bucket will be associated. For example,my-project
.[BUCKET_NAME]
is the name you want to give your bucket, subject to naming requirements. For example,my-bucket
.
<CreateBucketConfiguration> <LocationConstraint>[BUCKET_LOCATION]</LocationConstraint> <StorageClass>[STORAGE_CLASS]</StorageClass> </CreateBucketConfiguration>
Where:
Step 2) Copy objects from your old bucket to your new bucket
Console
Use the Cloud Storage Transfer Service from within Google Cloud Console to copy data from one Cloud Storage bucket to another:
- Open the Transfer page in the Google Cloud Console.
- Click Create transfer job.
Follow the step-by-step walkthrough, clicking Continue as you complete each step:
Select Source: Use Google Cloud Storage Bucket as your selected source, and click Browse to find and select the bucket you want to move your objects out of.
Select Destination: Click Browse to find and select the bucket you want to move your objects into.
Additionally, select the checkbox Delete source objects after the transfer completes.
Configure Transfer: You can ignore this section.
After you complete the step-by-step walkthrough, click Create.
This begins the process of copying objects from your old bucket into your new one. This process may take some time; however, after you click Create, you can navigate away from the Google Cloud Console.
To view the transfer's progress: Open the Transfer page in the Google Cloud Console.
gsutil
- Make sure you have at least
gsutil 4.12
installed. Use the
gsutil cp
command, with the-r
option, to recursively copy all your objects from the source bucket to the destination bucket:gsutil cp -r gs://[SOURCE_BUCKET]/* gs://[DESTINATION_BUCKET]
Where:
[SOURCE_BUCKET]
is the name of your original bucket. For example,old-bucket
.[DESTINATION_BUCKET]
is the name of the new bucket you created in Step 1) Create a new bucket. For example,my-bucket
.
REST APIs
JSON API
Use the JSON API's rewrite
method to copy data in limited-sized chunks
over multiple requests. When doing so, you must loop and call the
rewrite
method until all the data are moved:
Use
cURL
and the JSON APIrewrite
method to copy data from a source bucket to a destination bucket:curl -X POST \ -H "Authorization: Bearer [OAUTH2_TOKEN]" \ -H "Content-Length: 0" \ "https://storage.googleapis.com/storage/v1/b/[SOURCE_BUCKET]/o/[OBJECT_NAME]/rewriteTo/b/[DESTINATION_BUCKET]/o/[OBJECT_NAME]"
Where:
[OAUTH2_TOKEN]
is the access token you generated in Step 1 of Step 1) Create a new bucket.[SOURCE_BUCKET]
is the name of your original bucket. For example,old-bucket
.[OBJECT_NAME]
is the name of the object you want to copy. For example,pets/dog.png
.[DESTINATION_BUCKET]
is the name of the new bucket you created in Step 1) Create a new bucket. For example,my-bucket
.
If the object is, for example, 10 GB in size, the response to this request looks like the following example:
{ "kind": "storage#rewriteResponse", "totalBytesRewritten": 1048576, "objectSize": 10000000000, "done": false, "rewriteToken": [TOKEN_VALUE] }
Use the
rewriteToken
in a subsequent request to continue copying data:curl -X POST \ -H "Authorization: Bearer [OAUTH2_TOKEN]" \ -H "Content-Length: 0" \ -d '{"rewriteToken": "[TOKEN_VALUE]"}' \ "https://storage.googleapis.com/storage/v1/b/[SOURCE_BUCKET]/o/[OBJECT_NAME]/rewriteTo/b/[DESTINATION_BUCKET]/o/[OBJECT_NAME]"
Where:
[OAUTH2_TOKEN]
is the access token you generated in Step 1 of Step 1) Create a new bucket.[TOKEN_VALUE]
is therewriteToken
value returned in Step 1.[SOURCE_BUCKET]
is the name of your original bucket. For example,old-bucket
.[OBJECT_NAME]
is the name of the object you want to copy. For example,pets/bunny.png
.[DESTINATION_BUCKET]
is the name of the new bucket you created in Step 1) Create a new bucket. For example,my-bucket
.
When all of the data is copied, the last response has a done
property equal to true
, there is no rewriteToken
property, and the
metadata of the copied-to object is included in the resource
property.
{ "kind": "storage#rewriteResponse", "totalBytesRewritten": 10000000000, "objectSize": 10000000000, "done": true, "resource": objects Resource }
Step 3) Delete the objects from your old bucket
Console
You don't need to do anything to delete the objects from your old bucket: as part of copying objects using the Transfer Service, old objects are deleted automatically (this assumes you selected the "Delete source objects after the transfer completes" checkbox).
gsutil
Use the gsutil rm
command, with the -r
option, to recursively
delete all your objects from the source bucket, as well as the source
bucket itself:
gsutil rm -r gs://[SOURCE_BUCKET]
Where [SOURCE_BUCKET]
is the name of your original bucket. For example, old-bucket
.
Or, to delete the objects but keep the source bucket:
gsutil rm -a gs://[SOURCE_BUCKET]/**
REST APIs
JSON API
Use
cURL
and the and the JSON APIdelete
method to remove the original version of your data with the following command:curl -X DELETE \ -H "Authorization: Bearer [OAUTH2_TOKEN]" \ "https://storage.googleapis.com/storage/v1/b/[SOURCE_BUCKET]/o/[OBJECT_NAME]"
Where:
[OAUTH2_TOKEN]
is the access token you generated in Step 1 of Step 1) Create a new bucket.[SOURCE_BUCKET]
is the name of your original bucket. For example,old-bucket
.[OBJECT_NAME]
is the name of the object you want to delete. For example,pets/dog.png
.
If successful, the method returns an empty response.
What's next
- Rename, copy, or move individual objects.
- Change the default storage class associated with a bucket.
- Add labels to your buckets.
- Learn about available bucket locations and bucket naming guidelines.