The metadata for a Cloud Storage bucket identifies the bucket's properties
and lets you control how the bucket behaves. A bucket's metadata includes
non-editable fields such as the bucket name and project number, as well as
configurable settings like the default storage class, lifecycle rules, and
IAM roles.

## Overview of bucket metadata

Metadata is stored as `key: value` pairs, where the `value` can take a variety
of forms, including strings, arrays, or even nested `key:value` pairs. For
example, the bucket name is a string, while a bucket Object Lifecycle Management
configuration is an array of rules in which each rule contains several child
`key: value` pairs.

The mutability of metadata varies:

- Some metadata is read-only.

- Some metadata can be set when the bucket is [created](https://docs.cloud.google.com/storage/docs/creating-buckets.md.txt), but can't be
  edited or removed.

- Some metadata can be added and edited, but can't be removed.

- Some metadata can be added, edited, and removed at any time.

## Non-editable metadata

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

- [Bucket name](https://docs.cloud.google.com/storage/docs/buckets.md.txt#naming)

- The [project](https://docs.cloud.google.com/storage/docs/projects.md.txt) the bucket is a part of

- Generation number

  - A bucket's generation number uniquely identifies the version of the
    bucket even if more than one version of a bucket share the same name.

  - A bucket's generation value never changes.

  - There is no guarantee that generation numbers increase for successive
    versions, only that each new version has a unique generation number.

  - There is no relationship between generation numbers of unrelated buckets.

- 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.
- Whether [hierarchical namespace](https://docs.cloud.google.com/storage/docs/hns-overview.md.txt) is enabled for the bucket

## 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](https://docs.cloud.google.com/storage/docs/org-policy-constraints.md.txt), there are restrictions on modifying
certain metadata values.

| Metadata overview | Link to guide | Notes |
|---|---|---|
| [Access Control Lists (ACLs)](https://docs.cloud.google.com/storage/docs/access-control/lists.md.txt) | [Create and managing ACLs](https://docs.cloud.google.com/storage/docs/access-control/create-manage-lists.md.txt) | Recommended only for XML users. |
| [Default ACLs](https://docs.cloud.google.com/storage/docs/access-control/lists.md.txt#default) | [Set default object ACLs](https://docs.cloud.google.com/storage/docs/access-control/create-manage-lists.md.txt#defaultobjects) |   |
| [Identity and Access Management (IAM) policies](https://docs.cloud.google.com/storage/docs/access-control/iam.md.txt)^1^ | [Use IAM permissions](https://docs.cloud.google.com/storage/docs/access-control/using-iam-permissions.md.txt) |   |
| [Billing (Requester Pays)](https://docs.cloud.google.com/storage/docs/requester-pays.md.txt) | [Use Requester Pays](https://docs.cloud.google.com/storage/docs/using-requester-pays.md.txt) |   |
| [Cross-origin resource sharing (CORS) configuration](https://docs.cloud.google.com/storage/docs/cross-origin.md.txt) | [Set up and view CORS configurations](https://docs.cloud.google.com/storage/docs/using-cors.md.txt) |   |
| [Default storage class](https://docs.cloud.google.com/storage/docs/storage-classes.md.txt) | [Change the default storage class](https://docs.cloud.google.com/storage/docs/changing-default-storage-class.md.txt) | Set during bucket creation and can be edited, but not removed. |
| [Data encryption](https://docs.cloud.google.com/storage/docs/encryption.md.txt) | [Configure which encryption methods are allowed or restricted](https://docs.cloud.google.com/storage/docs/encryption/enforce-encryption-types.md.txt) | Updating this setting doesn't affect the encryption type of any objects that already exist in the bucket. |
| [Default Cloud KMS encryption key](https://docs.cloud.google.com/storage/docs/encryption/customer-managed-keys.md.txt) | [Use default Cloud KMS keys](https://docs.cloud.google.com/storage/docs/encryption/using-customer-managed-keys.md.txt#use-default-keys) |   |
| [Default event-based holds](https://docs.cloud.google.com/storage/docs/object-holds.md.txt#default-holds)^1^ | [Work with the default event-based hold property](https://docs.cloud.google.com/storage/docs/holding-objects.md.txt#use-default-hold) |   |
| [Public access prevention](https://docs.cloud.google.com/storage/docs/public-access-prevention.md.txt)^1^ | [Use public access prevention](https://docs.cloud.google.com/storage/docs/using-public-access-prevention.md.txt) |   |
| [Uniform bucket-level access](https://docs.cloud.google.com/storage/docs/uniform-bucket-level-access.md.txt)^1^ | [Use uniform bucket-level access](https://docs.cloud.google.com/storage/docs/using-uniform-bucket-level-access.md.txt) | Only editable for the first 90 days after you enable uniform bucket-level access on a bucket. |
| [Lifecycle configuration policy](https://docs.cloud.google.com/storage/docs/lifecycle.md.txt) | [Manage object lifecycles](https://docs.cloud.google.com/storage/docs/managing-lifecycles.md.txt) |   |
| [Autoclass](https://docs.cloud.google.com/storage/docs/autoclass.md.txt) | [Use Autoclass](https://docs.cloud.google.com/storage/docs/using-autoclass.md.txt) |   |
| [Turbo replication](https://docs.cloud.google.com/storage/docs/availability-durability.md.txt#turbo-replication)^1^ | [Manage turbo replication](https://docs.cloud.google.com/storage/docs/managing-turbo-replication.md.txt) |   |
| Usage logs and storage logs | [Usage logs configuration](https://docs.cloud.google.com/storage/docs/access-logs.md.txt) |   |
| [Bucket Lock](https://docs.cloud.google.com/storage/docs/bucket-lock.md.txt)^2^ | [Use and locking retention policies](https://docs.cloud.google.com/storage/docs/using-bucket-lock.md.txt) | Only editable if you don't lock the retention policy. |
| [Object Retention Lock](https://docs.cloud.google.com/storage/docs/object-lock.md.txt) | [Enable and use object retention configurations](https://docs.cloud.google.com/storage/docs/using-object-lock.md.txt) | Once enabled for a bucket, cannot be disabled. |
| [Object Versioning configuration](https://docs.cloud.google.com/storage/docs/object-versioning.md.txt) | [Use Object Versioning](https://docs.cloud.google.com/storage/docs/using-object-versioning.md.txt) |   |
| [Bucket labels](https://docs.cloud.google.com/storage/docs/tags-and-labels.md.txt) | [Use bucket labels](https://docs.cloud.google.com/storage/docs/using-bucket-labels.md.txt) |   |
| [Soft delete retention duration](https://docs.cloud.google.com/storage/docs/soft-delete.md.txt) | [Use soft delete](https://docs.cloud.google.com/storage/docs/use-soft-delete.md.txt) |   |
| Website configuration | [Assign specialty pages for static websites](https://docs.cloud.google.com/storage/docs/hosting-static-website.md.txt#specialty-pages) |   |
| [Bucket location](https://docs.cloud.google.com/storage/docs/locations.md.txt) | [Relocate buckets](https://docs.cloud.google.com/storage/docs/bucket-relocation/relocate-buckets.md.txt) | Before you relocate a bucket, review the [Bucket relocation overview](https://docs.cloud.google.com/storage/docs/bucket-relocation/overview.md.txt) page. |

^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.

## What's next

- Learn how to [view bucket metadata](https://docs.cloud.google.com/storage/docs/getting-bucket-metadata.md.txt).
- Learn how to [get bucket size](https://docs.cloud.google.com/storage/docs/getting-bucket-size.md.txt).
- Learn more about [buckets](https://docs.cloud.google.com/storage/docs/buckets.md.txt).
- Read more about [object metadata](https://docs.cloud.google.com/storage/docs/metadata.md.txt).