Moving and renaming buckets

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.

Important: Moving data between buckets may incur costs for network usage within Google Cloud, if the source and destination buckets are in different locations. In addition, moving data between buckets may incur retrieval and early deletion fees, if the objects being moved are Nearline Storage, Coldline Storage, or Archive Storage objects.

To move your data from one bucket to another:

Step 1) Create a new bucket

Console

1. Open the Cloud Storage browser in the Google Cloud Console.
   Open the Cloud Storage browser
2. Click Create bucket to open the bucket creation form.



3. 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.
4. 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

Note: Other options for creating a new bucket can be found in the JSON API reference for bucket.insert

C++

For more information, see the Cloud Storage C++ API reference documentation .

View on GitHub Feedback

namespace gcs = google::cloud::storage;
using ::google::cloud::StatusOr;
[](gcs::Client client, std::string bucket_name) {
  StatusOr<gcs::BucketMetadata> bucket_metadata =
      client.CreateBucket(bucket_name, gcs::BucketMetadata());

  if (!bucket_metadata) {
    throw std::runtime_error(bucket_metadata.status().message());
  }

  std::cout << "Bucket " << bucket_metadata->name() << " created."
            << "\nFull Metadata: " << *bucket_metadata << "\n";
}

C#

For more information, see the Cloud Storage C# API reference documentation .

View on GitHub Feedback

private void CreateBucket(string bucketName)
{
    var storage = StorageClient.Create();
    storage.CreateBucket(s_projectId, bucketName);
    Console.WriteLine($"Created {bucketName}.");
}

Go

For more information, see the Cloud Storage Go API reference documentation .

View on GitHub Feedback

ctx := context.Background()
bucket := client.Bucket(bucketName)

ctx, cancel := context.WithTimeout(ctx, time.Second*10)
defer cancel()
if err := bucket.Create(ctx, projectID, &storage.BucketAttrs{
	StorageClass: "COLDLINE",
	Location:     "asia",
}); err != nil {
	return err
}

Java

For more information, see the Cloud Storage Java API reference documentation .

View on GitHub Feedback

Bucket bucket =
    storage.create(
        BucketInfo.newBuilder(bucketName)
            // See here for possible values: http://g.co/cloud/storage/docs/storage-classes
            .setStorageClass(StorageClass.COLDLINE)
            // Possible values: http://g.co/cloud/storage/docs/bucket-locations#location-mr
            .setLocation("asia")
            .build());

Node.js

For more information, see the Cloud Storage Node.js API reference documentation .

View on GitHub Feedback

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

async function createBucket() {
  // Creates a new bucket in the Asia region with the coldline default storage
  // class. Leave the second argument blank for default settings.
  //
  // For default values see: https://cloud.google.com/storage/docs/locations and
  // https://cloud.google.com/storage/docs/storage-classes

  const [bucket] = await storage.createBucket(bucketName, {
    location: 'ASIA',
    storageClass: 'COLDLINE',
  });

  console.log(`Bucket ${bucket.name} created.`);
}

createBucket().catch(console.error);

PHP

For more information, see the Cloud Storage PHP API reference documentation .

View on GitHub Feedback

use Google\Cloud\Storage\StorageClient;

/**
 * Create a Cloud Storage Bucket.
 *
 * @param string $bucketName name of the bucket to create.
 * @param string $options options for the new bucket.
 *
 */
function create_bucket($bucketName, $options = [])
{
    $storage = new StorageClient();
    $bucket = $storage->createBucket($bucketName, $options);
    printf('Bucket created: %s' . PHP_EOL, $bucket->name());
}

Python

For more information, see the Cloud Storage Python API reference documentation .

View on GitHub Feedback

from google.cloud import storage


def create_bucket(bucket_name):
    """Creates a new bucket."""
    # bucket_name = "your-new-bucket-name"

    storage_client = storage.Client()

    bucket = storage_client.create_bucket(bucket_name)

    print("Bucket {} created".format(bucket.name))

Ruby

For more information, see the Cloud Storage Ruby API reference documentation .

View on GitHub Feedback

# project_id    = "Your Google Cloud project ID"
# bucket_name   = "Name of Google Cloud Storage bucket to create"
# location      = "Location of where to create Cloud Storage bucket"
# storage_class = "Storage class of Cloud Storage bucket"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project_id: project_id
bucket  = storage.create_bucket bucket_name,
                                location:      location,
                                storage_class: storage_class

puts "Created bucket #{bucket.name} in #{location}" +
     " with #{storage_class} class"

REST APIS

JSON API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
2. Create a .json file that contains the following information:

{
  "name": "[BUCKET_NAME]",
  "location": "[BUCKET_LOCATION]",
  "storageClass": "[STORAGE_CLASS]"
}

Where:

• [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.
3. 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.

XML API

1. Get an authorization access token from the OAuth 2.0 Playground. Configure the playground to use your own OAuth credentials.
2. Create a .xml file that contains the following information:

<CreateBucketConfiguration>
   <LocationConstraint>[BUCKET_LOCATION]</LocationConstraint>
   <StorageClass>[STORAGE_CLASS]</StorageClass>
</CreateBucketConfiguration>

Where:

• [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.
3. 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.

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:

1. Open the Transfer page in the Google Cloud Console.

   Open the Transfer page

2. Click Create transfer job.

3. 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.

4. 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.

Open the Transfer page

gsutil

1. Make sure you have at least gsutil 4.12 installed.

2. 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:

1. Use cURL and the JSON API rewrite 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]
   }

2. 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 the rewriteToken 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 API delete 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.