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.

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

    • A bucket's metageneration number uniquely identifies the metadata state of the bucket. The metageneration number is 1 at the time of bucket creation and increases each time you modify the bucket's metadata.

Editable metadata

Editable bucket metadata is metadata whose values you can typically modify at any time. In some cases, such as the bucket being subject to an organization policy constraint, there are restrictions on modifying certain metadata values.

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) policies1 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 Cloud KMS encryption key Using default Cloud KMS keys
Default event-based holds1 Working with the default event-based hold property
Uniform bucket-level access1 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 policy2 Using and locking retention policies Only editable if you don't lock the retention policy.
Object Versioning configuration Using Object Versioning
Bucket labels Using bucket labels
Website configuration Assigning specialty pages for static websites

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

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

Bucket labels

Bucket labels allow you to create arbitrary key:value pairs that are stored as part of the bucket's metadata. You can use labels to organize your buckets along with other Google Cloud resources such as virtual machine instances and persistent disks. For example, say you want a key named team that has the values alpha, beta, and delta, which you will use to indicate which team is associated with certain Google Cloud resources. You can apply the labels team:alpha, team:beta, and team:delta to the desired resources to achieve this.

Keep in mind the following when working with bucket labels:

  • Keys and values cannot be longer than 63 characters each.
  • Keys and values can only contain lowercase letters, numeric characters, underscores, and dashes. International characters are allowed.
  • Label keys must start with a lowercase letter and international characters are allowed.
  • Label keys cannot be empty.
  • Each bucket can have a maximum of 64 labels actively applied to it.
  • As is generally the case for bucket metadata, bucket labels are not associated with individual objects or object metadata.

For a general example of using labels to organize your resources in billing, see Billing Export to BigQuery Query Examples.

What's next