Bucket metadata

Go to examples

This page discusses the metadata fields that are stored along with buckets in Cloud Storage.

Introduction

Buckets created in Cloud Storage have metadata associated with them. Metadata identifies properties of the bucket and specifies how the bucket should be handled when it's accessed.

Some metadata exists as key: value pairs. For example, the name of a bucket is represented by the metadata entry name: my-bucket-name for the JSON API. The XML API presents such metadata as <elements></elements>, such as <LocationConstraint>US</LocationConstraint> for the bucket location.

Other metadata can have an array of data associated with the key. For example, the lifecycle management metadata can contain a set of rules that apply to current and future objects in a bucket.

The mutability of metadata varies:

• Some you can only view.

• Some you can only set when the bucket is first created, and cannot edit or remove.

• Some you can add and edit, but not remove.

• Some you can add, edit, and remove at any time.

Note: Some metadata, such as the uniform bucket-level access setting, cannot be viewed or managed using the XML API.

Non-editable metadata

The following metadata is set during bucket creation, and cannot be edited or removed:

• Bucket name

• Bucket location

• The project the bucket is a part of

• Metageneration number (automatically generated by Cloud Storage)

Editable metadata

There are two categories of metadata that you can change for buckets:

Fixed-key metadata

Fixed-key metadata is metadata whose keys are set, but for which you can specify a value.

Metadata overview	Link to guide	Notes
Access Control Lists (ACLs)	Creating and managing ACLs	Recommended only for XML users.
Default ACLs	Setting default object ACLs
Identity and Access Management (IAM) policies^1	Using IAM permissions
Billing (Requester Pays)	Using Requester Pays
Cross-origin resource sharing (CORS) configuration	Configuring CORS
Default storage class	Changing the default storage class	Set during bucket creation and can be edited, but not removed.
Default KMS encryption key	Using default Cloud KMS keys
Default event-based holds^1	Working with the default event-based hold property
Uniform bucket-level access^1	Using uniform bucket-level access	Only editable for the first 90 days after you enable uniform bucket-level access on a bucket.
Lifecycle configuration policy	Managing object lifecycles
Usage logs and storage logs	Usage logs configuration
Retention policy^2	Using and locking retention policies	Only editable if you don't lock the retention policy.
Object Versioning configuration	Using Object Versioning
Website configuration	Assigning specialty pages for static websites

¹ This metadata cannot be viewed or managed using the XML API.

² You can use the XML API to set this metadata during bucket creation, but not to view or manage this metadata.

Custom-key metadata

Custom-key metadata is metadata that you add by specifying both a key and a value associated with the key. For buckets, custom-key metadata is known as labels, which you use to organize your buckets.

What's next

• Learn how to view bucket metadata.
• Read more about object metadata.