Create a bucket

This page shows you how to create a Cloud Storage bucket. If not otherwise specified in your request, buckets are created with a default storage class of Standard storage and have a seven-day soft delete retention duration.

Required roles

In order to get the required permissions for creating a Cloud Storage bucket, ask your administrator to grant you the Storage Admin (roles/storage.admin) IAM role for the project.

This predefined role contains the permission required to create a bucket. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

  • storage.buckets.create
  • storage.buckets.enableObjectRetention (only required if enabling object retention configurations for the bucket)
  • storage.buckets.list (only required if creating a bucket using the Trusted Cloud console.)
  • resourcemanager.projects.get (only required if creating a bucket using the Trusted Cloud console)

You might also be able to get these permissions with custom roles or other predefined roles. To see which roles are associated with which permissions, refer to IAM roles for Cloud Storage.

For instructions on granting roles for projects, see Manage access to projects.

Create a new bucket

If you are creating a bucket for the first time, see Discover object storage with the Trusted Cloud console or Discover object storage with the Google Cloud CLI tool.

To create a bucket with specific settings or advanced configurations, complete the following steps:

Console

  1. In the Trusted Cloud console, go to the Cloud Storage Buckets page.

    Go to Buckets

  2. Click Create.

  3. On the Create a bucket page, enter your bucket information. After each of the following steps, click Continue to proceed to the next step:

    1. In the Get started section, do the following:

      • Enter a globally unique name that meets the bucket name requirements.

      • To add a bucket label, click the expander arrow to expand the Labels section, click Add label, and specify a key and a value for your label.

    2. In the Choose where to store your data section, do the following:

      1. Select a Location type.

      2. Use the location type's drop-down menu to select a Location where object data within your bucket will be permanently stored.

    3. In the Choose how to store your data section, do the following:

      1. Select a default storage class for the bucket or Autoclass for automatic storage class management of your bucket's data.

    4. In the Optimize storage for data-intensive workloads section, do the following:

      1. To enable hierarchical namespace, select Enable Hierarchical namespace on this bucket.

      2. To enable Anywhere Cache, select Enable Anywhere Cache.

        1. To create caches, click Configure.

        2. In the Configure cache settings dialog that appears, click the drop-down arrow next to the listed regions and select the zones where you want to create caches.

        3. Click Done.

    5. Click Continue.

    6. In the Choose how to control access to objects section, select whether or not your bucket enforces public access prevention, and select an access control model for your bucket's objects.

    7. In the Choose how to protect object data section, do the following:

      • Select any of the options under Data protection that you want to set for your bucket.

      • To enable soft delete, click expander arrow labeled soft delete policy, and specify the number of days you want to retain objects after deletion.

      • To choose how your object data will be encrypted, click the expander arrow labeled Data encryption, and select a Data encryption method.

  4. Click Create.

To learn how to get detailed error information about failed Cloud Storage operations in the Trusted Cloud console, see Troubleshooting.

Command line

  1. In the Trusted Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Trusted Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. In your development environment, run the gcloud storage buckets create command:

    gcloud storage buckets create gs://BUCKET_NAME --location=BUCKET_LOCATION

    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 of your bucket. For example, U-FRANCE-EAST1.

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

    Creating gs://BUCKET_NAME/...

    Set the following flags to have greater control over the creation of your bucket:

    • --project: Specify the project ID or project number with which your bucket will be associated. For example, my-project.
    • --default-storage-class: Specify the default storage class of your bucket. For example, STANDARD.
    • --uniform-bucket-level-access: Enable uniform bucket-level access for your bucket.
    • --soft-delete-duration: Specify a soft delete retention duration, which is the number of days you want to retain objects after they get deleted. For example, 10d.

    For example:

    gcloud storage buckets create gs://BUCKET_NAME --project=PROJECT_ID --default-storage-class=STORAGE_CLASS --location=BUCKET_LOCATION --uniform-bucket-level-access
--soft-delete-duration=RETENTION_DURATION

    For a complete list of options for bucket creation use the gcloud CLI, see buckets create options.

Client libraries

C++

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr. 

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::move(bucket_metadata).status();

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

C#

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr. 


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.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr. 

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: %w", err)
	}
	defer client.Close()

	ctx, cancel := context.WithTimeout(ctx, time.Second*30)
	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: %w", 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.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr. 

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.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr. 

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The ID of your GCS bucket
// const bucketName = 'your-unique-bucket-name';

// The name of a storage class
// See the StorageClass documentation for other valid storage classes:
// https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/storage/StorageClass.html
// const storageClass = 'coldline';

// The name of a location
// See this documentation for other valid locations:
// http://g.co/cloud/storage/docs/locations#location-mr
// const location = 'ASIA';

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

// Creates a client
// The bucket in the sample below will be created in the project associated with this client.
// For more information, please see https://cloud.google.com/docs/authentication/production or https://googleapis.dev/nodejs/storage/latest/Storage.html
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().catch(console.error);

PHP

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr. 

use Google\Cloud\Storage\StorageClient;

/**
 * Create a new bucket with a custom default storage class and location.
 *
 * @param string $bucketName The name of your Cloud Storage bucket.
 *        (e.g. 'my-bucket')
 */
function create_bucket_class_location(string $bucketName): void
{
    $storage = new StorageClient();
    $storageClass = 'COLDLINE';
    $location = 'ASIA';
    $bucket = $storage->createBucket($bucketName, [
        'storageClass' => $storageClass,
        'location' => $location,
    ]);

    $objects = $bucket->objects([
        'encryption' => [
            'defaultKmsKeyName' => null,
        ]
    ]);

    printf('Created bucket %s in %s with storage class %s', $bucketName, $storageClass, $location);
}

Python

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

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr. 

from google.cloud import storage


def create_bucket_class_location(bucket_name):
    """
    Create a new bucket in the US region with the coldline 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.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, see Set up authentication for client libraries.

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr. 

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

Terraform

You can use a Terraform resource to create a storage bucket.

# Create new storage bucket in the US multi-region
# with coldline storage
resource "random_id" "bucket_prefix" {
  byte_length = 8
}

resource "google_storage_bucket" "static" {
  name          = "${random_id.bucket_prefix.hex}-new-bucket"
  location      = "US"
  storage_class = "COLDLINE"

  uniform_bucket_level_access = true
}

REST APIs

JSON API

  1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.

  2. Create a JSON file that contains the settings for the bucket, which must include a name for the bucket. See the Buckets:Insert documentation for a complete list of settings. The following are common settings to include:

    {
  "name": "BUCKET_NAME",
  "location": "BUCKET_LOCATION",
  "storageClass": "STORAGE_CLASS",
  "iamConfiguration": {
    "uniformBucketLevelAccess": {
      "enabled": true
    },
  }
}

    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, U-FRANCE-EAST1.

    • STORAGE_CLASS is the default storage class of your bucket. For example, STANDARD.

  3. Use cURL to call the JSON API:

    curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 "https://storage.s3nsapis.fr/storage/v1/b?project=PROJECT_IDENTIFIER"

    Where:

    • JSON_FILE_NAME is name of the JSON file you created in Step 2.
    • PROJECT_IDENTIFIER is the ID or number of the project with which your bucket will be associated. For example, my-project.

XML API

  1. Have gcloud CLI installed and initialized, which lets you generate an access token for the Authorization header.

  2. Create an XML file that contains settings for the bucket. See the XML: Create a bucket documentation for a complete list of settings. The following are common settings to include:

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

    Where:

    • STORAGE_CLASS is the default storage class of your bucket. For example, STANDARD.

    • BUCKET_LOCATION is the location where you want to store your bucket's object data. For example, U-FRANCE-EAST1.

  3. Use cURL to call the XML API:

    curl -X PUT --data-binary @XML_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "x-goog-project-id: PROJECT_ID" \
  "https://storage.s3nsapis.fr/BUCKET_NAME"

    Where:

    • XML_FILE_NAME is name of the XML file you created in Step 2.
    • 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.

    If the request was successful, a response is not returned.

What's next