Managing Buckets

This page shows you how to change the default storage class and label metadata for your Cloud Storage buckets. For an overview of buckets, read the Key Terms. To learn more about specific bucket properties, see Storage Classes, Bucket Locations, and Bucket Labels.

Managing a bucket's default storage class

To change the default storage class of an existing bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser

  2. In the bucket list, find the bucket you want to modify, and click its more options button (three vertical dots).

  3. Click Edit default storage class.

  4. In the overlay window, select the new default storage class you would like for your bucket.

    Note that based on the location of your bucket, not all storage classes are available.

    Edit bucket storage class.

  5. Click Save.

gsutil

Use the gsutil defstorageclass set command with the desired storage class, replacing [VALUES_IN_BRACKETS] with the appropriate values:

gsutil defstorageclass set [STORAGE_CLASS] gs://[BUCKET_NAME]

The response looks like the following example:

Setting default storage class to "[STORAGE_CLASS]" for bucket gs://[BUCKET_NAME]

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
  3. {
      "storageClass": "[STORAGE_CLASS]"
    }
  4. Use cURL to call the JSON API, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PUT --data-binary @[JSON_FILE_NAME].json \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -H "Content-Type: application/json" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=storageClass"

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
  3. <StorageClass>[STORAGE_CLASS]</StorageClass>
  4. Use cURL to call the XML API, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PUT --data-binary @[XML_FILE_NAME].xml \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?storageClass"

Managing a bucket's labels

To change the labels applied to a bucket:

Console

  1. Open the Cloud Storage browser in the Google Cloud Platform Console.
    Open the Cloud Storage browser

  2. Select the checkbox of the bucket whose labels you wish to manage.

  3. In the side panel that appears, click the Labels tab.

  4. Manage the bucket labels as desired.

    1. To add a label, click the + Add label button and specify a new key:value pair.

    2. To modify a label, edit the desired text box in the Value column. Note that you should create a new label if you want to change the Key.

    3. To delete a label, click the X associated with it.

  5. Click Save.

gsutil

Use the -l flag in a label ch command. For example:

gsutil label ch -l "[KEY_1]:[VALUE_1]" gs://[BUCKET_NAME]/

Where [KEY_1] is the key name for your label, [VALUE_1] is the value for your label and [BUCKET_NAME] is the name of the bucket that the label applies to.

  • Use multiple -l flags to add/edit multiple key:value pairs in a single command.

  • Use the -d flag to delete labels that have the specified keys.

  • Use the label set command to replace all existing labels with new ones.

Client libraries

Python

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

The following sample adds a label to a bucket:

def add_bucket_label(bucket_name):
    """Add a label to a bucket."""
    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)

    labels = bucket.labels
    labels['example'] = 'label'
    bucket.labels = labels
    bucket.patch()

    print('Updated labels on {}.'.format(bucket.name))
    pprint.pprint(bucket.labels)

The following sample removes a label from a bucket:

def remove_bucket_label(bucket_name):
    """Remove a label from a bucket."""
    storage_client = storage.Client()
    bucket = storage_client.get_bucket(bucket_name)

    labels = bucket.labels

    if 'example' in labels:
        del labels['example']

    bucket.labels = labels
    bucket.patch()

    print('Updated labels on {}.'.format(bucket.name))
    pprint.pprint(bucket.labels)

Ruby

For more on installing and creating a Cloud Storage client, refer to Cloud Storage Client Libraries.

The following sample adds a label to a bucket:

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Name of your Google Cloud Storage bucket"
# label_key   = "Cloud Storage bucket Label Key"
# label_value = "Cloud Storage bucket Label Value"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project: project_id
bucket  = storage.bucket bucket_name

bucket.update do |bucket|
  bucket.labels[label_key] = label_value
end

puts "Added label #{label_key} with value #{label_value} to #{bucket_name}"

The following sample removes a label from a bucket:

# project_id  = "Your Google Cloud project ID"
# bucket_name = "Name of your Google Cloud Storage bucket"
# label_key   = "Cloud Storage bucket Label Key"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new project: project_id
bucket  = storage.bucket bucket_name

bucket.update do |bucket|
  bucket.labels[label_key] = nil
end

puts "Deleted label #{label_key} from #{bucket_name}"

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
  3. {
      "labels": {
        "[KEY_1]": "[VALUE_1]"
      }
    }
  4. Use cURL to call the JSON API with a PATCH Bucket request, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PATCH --data-binary @[JSON_FILE_NAME].json \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        -H "Content-Type: application/json" \
        "https://www.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=labels"

You can add/edit multiple key:value pairs in a request, and to delete a label, set its value to null. For example:

{
  "labels": {
    "New_Label_Key": "New_Label_Value",
    "Existing_Label_Key": "Updated_Label_Value",
    "Old_Label_Key": null
  }
}

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, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    <Tagging>
      <TagSet>
        <Tag>
          <Key>[KEY_1]</Key>
          <Value>[VALUE_1]</Value>
        </Tag>
      </TagSet>
    </Tagging>

    Note that you can add multiple <Tag> elements in a request.

  3. Use cURL to call the XML API, with a PUT Bucket request and tagging query string parameter, replacing [VALUES_IN_BRACKETS] with the appropriate values:
    curl -X PUT --data-binary @[XML_FILE_NAME].xml \
        -H "Authorization: Bearer [OAUTH2_TOKEN]" \
        "https://storage.googleapis.com/[BUCKET_NAME]?tagging"

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Storage Documentation