Creating storage buckets

This page shows you how to create Cloud Storage buckets. For an overview of buckets, read the Key Terms. If not otherwise specified in your request, buckets are created in the US multi-region and have a default storage class of Standard Storage.

Note: In order to create a bucket in a project, a user must have the storage.buckets.create project permission for the project. If you are working within a project that you did not create, you might need the project owner to give you a role that contains this permission, such as Storage Admin.

To create a new storage 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.

See Troubleshooting for how to get detailed error information about failed operations in the Cloud Storage browser.

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.

If the request is successful, the command returns the following message:

Creating gs://BUCKET_NAME/...

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_ID -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 const& bucket_name,
   std::string const& storage_class, std::string const& location) {
  StatusOr<gcs::BucketMetadata> bucket_metadata =
      client.CreateBucket(bucket_name, gcs::BucketMetadata()
                                           .set_storage_class(storage_class)
                                           .set_location(location));

  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

using Google.Apis.Storage.v1.Data;
using Google.Cloud.Storage.V1;
using System;

public class CreateRegionalBucketSample
{
    /// <summary>
    /// Creates a storage bucket with region.
    /// </summary>
    /// <param name="projectId">The ID of the project to create the buckets in.</param>
    /// <param name="location">The location of the bucket. Object data for objects in the bucket resides in 
    /// physical storage within this region. Defaults to US.</param>
    /// <param name="bucketName">The name of the bucket to create.</param>
    /// <param name="storageClass">The bucket's default storage class, used whenever no storageClass is specified
    /// for a newly-created object. This defines how objects in the bucket are stored
    /// and determines the SLA and the cost of storage. Values include MULTI_REGIONAL,
    /// REGIONAL, STANDARD, NEARLINE, COLDLINE, ARCHIVE, and DURABLE_REDUCED_AVAILABILITY.
    /// If this value is not specified when the bucket is created, it will default to
    /// STANDARD.</param>
    public Bucket CreateRegionalBucket(
        string projectId = "your-project-id",
        string bucketName = "your-unique-bucket-name",
        string location = "us-west1",
        string storageClass = "REGIONAL")
    {
        var storage = StorageClient.Create();
        Bucket bucket = new Bucket
        {
            Location = location,
            Name = bucketName,
            StorageClass = storageClass
        };
        var newlyCreatedBucket = storage.CreateBucket(projectId, bucket);
        Console.WriteLine($"Created {bucketName}.");
        return newlyCreatedBucket;
    }
}

Go

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

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/storage"
)

// createBucketClassLocation creates a new bucket in the project with Storage class and
// location.
func createBucketClassLocation(w io.Writer, projectID, bucketName string) error {
	// projectID := "my-project-id"
	// bucketName := "bucket-name"
	ctx := context.Background()
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*10)
	defer cancel()

	storageClassAndLocation := &storage.BucketAttrs{
		StorageClass: "COLDLINE",
		Location:     "asia",
	}
	bucket := client.Bucket(bucketName)
	if err := bucket.Create(ctx, projectID, storageClassAndLocation); err != nil {
		return fmt.Errorf("Bucket(%q).Create: %v", bucketName, err)
	}
	fmt.Fprintf(w, "Created bucket %v in %v with storage class %v\n", bucketName, storageClassAndLocation.Location, storageClassAndLocation.StorageClass)
	return nil
}

Java

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

View on GitHub Feedback

import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.BucketInfo;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageClass;
import com.google.cloud.storage.StorageOptions;

public class CreateBucketWithStorageClassAndLocation {
  public static void createBucketWithStorageClassAndLocation(String projectId, String bucketName) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The ID to give your GCS bucket
    // String bucketName = "your-unique-bucket-name";

    Storage storage = StorageOptions.newBuilder().setProjectId(projectId).build().getService();

    // See the StorageClass documentation for other valid storage classes:
    // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/StorageClass.html
    StorageClass storageClass = StorageClass.COLDLINE;

    // See this documentation for other valid locations:
    // http://g.co/cloud/storage/docs/bucket-locations#location-mr
    String location = "ASIA";

    Bucket bucket =
        storage.create(
            BucketInfo.newBuilder(bucketName)
                .setStorageClass(storageClass)
                .setLocation(location)
                .build());

    System.out.println(
        "Created bucket "
            + bucket.getName()
            + " in "
            + bucket.getLocation()
            + " with storage class "
            + bucket.getStorageClass());
  }
}

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';
// const storageClass = 'Name of a storage class, e.g. coldline';
// const location = 'Name of a location, e.g. ASIA';

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

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

async function createBucketWithStorageClassAndLocation() {
  // 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,
    [storageClass]: true,
  });

  console.log(
    `${bucket.name} created with ${storageClass} class in ${location}.`
  );
}

createBucketWithStorageClassAndLocation();

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_class_location(bucket_name):
    """Create a new bucket in specific location with storage class"""
    # bucket_name = "your-new-bucket-name"

    storage_client = storage.Client()

    bucket = storage_client.bucket(bucket_name)
    bucket.storage_class = "COLDLINE"
    new_bucket = storage_client.create_bucket(bucket, location="us")

    print(
        "Created bucket {} in {} with storage class {}".format(
            new_bucket.name, new_bucket.location, new_bucket.storage_class
        )
    )
    return new_bucket

Ruby

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

View on GitHub Feedback

def create_bucket_class_location bucket_name:
  # The ID to give your GCS bucket
  # bucket_name = "your-unique-bucket-name"

  require "google/cloud/storage"

  storage = Google::Cloud::Storage.new
  bucket  = storage.create_bucket bucket_name,
                                  location:      "ASIA",
                                  storage_class: "COLDLINE"

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

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.

What's next

• List buckets in a project.
• Get bucket information.
• Move or rename a bucket.
• Delete a bucket.
• Upload an object to your bucket.
• Learn the basics of using Cloud Storage with the Google Cloud Console.