About Cloud Storage buckets

This page describes buckets, a resource in Cloud Storage. For a general overview of how Cloud Storage works, see the Cloud Storage product overview.

Buckets

Buckets are the basic containers that hold your data. Everything that you store in Cloud Storage must be contained in a bucket. You can use buckets to organize your data and control access to your data, but unlike directories and folders, you cannot nest buckets.

• There is no limit to the number of buckets you can have in a project or location.

  • There are, however, limits to the rate you can create or delete buckets.

• When you create a bucket, you give it a globally-unique name and a geographic location where the bucket and its contents are stored.

  • You cannot change the name or location of an existing bucket. Instead, you can create a new bucket with the properties you want and move the contents from the old bucket to the new bucket. See Moving and Renaming Buckets for a step-by-step guide.

• Pricing (such as charges for data storage, data processing, and network outbound data transfer) depends on factors such as the bucket's location and the storage classes of objects within it. For more details, see Cloud Storage pricing.

• You can use Identity and Access Management (IAM) to control access to individual buckets.

Enable hierarchical namespace in buckets

When you create a bucket, you have the option to enable hierarchical namespace (preview) for your bucket. Buckets with hierarchical namespace enabled have an optimized storage structure similar to a file system, organizing objects within a hierarchy of folders. This provides improved performance, consistency, and ease of management, especially for data-intensive and file-oriented workloads. For information about enabling hierarchical namespace, see Create and manage buckets with hierarchical namespace enabled.

Bucket names

Your bucket names must meet the following requirements:

• Bucket names can only contain lowercase letters, numeric characters, dashes (-), underscores (_), and dots (.). Spaces are not allowed. Names containing dots require verification.
• Bucket names must start and end with a number or letter.
• Bucket names must contain 3-63 characters. Names containing dots can contain up to 222 characters, but each dot-separated component can be no longer than 63 characters.
• Bucket names cannot be represented as an IP address in dotted-decimal notation (for example, 192.168.5.4).
• Bucket names cannot begin with the "goog" prefix.
• Bucket names cannot contain "google" or close misspellings, such as "g00gle".

Bucket name considerations

• Bucket names reside in a single namespace that is shared by all Cloud Storage users. This means that:

  • Every bucket name must be globally unique.

    If you try to create a bucket with a name that already belongs to an existing bucket, such as example-bucket, Cloud Storage responds with an error message.

  • Bucket names are publicly visible.

    Don't use user IDs, email addresses, project names, project numbers, or any personally identifiable information (PII) in bucket names because anyone can probe for the existence of a bucket.

• Once you delete a bucket, anyone can reuse its name for a new bucket.

  The time it takes a deleted bucket's name to become available again is typically on the order of seconds; however, keep in mind the following:

  • If you delete the project that contains the bucket, which effectively deletes the bucket as well, the bucket name may not be released for weeks or longer.
  • If a new bucket with the same name is created in a different location and within 10 minutes of the old bucket's deletion, requests made to the new bucket during this 10 minute timeframe might fail with a 404-Bucket Not Found error.
  • If your requests go through the XML API, attempts to create a bucket that reuses a name in a new location might fail with a 404-Bucket Not Found error for up to 10 minutes after the old bucket's deletion.

• You can use a bucket name in a DNS record as part of a CNAME or A redirect.

  In order to do so, your bucket name should conform to standard DNS naming conventions. This means that your bucket name should not use underscores (_) or have a period next to another period or dash. For example, .., -., and .- are invalid character combinations within DNS names.

Example bucket names

The following are examples of valid bucket names:

• my-travel-maps
• 0f75d593-8e7b-4418-a5ba-cb2970f0b91e
• test.example.com (Requires verification of ownership for example.com)

The following are examples of invalid bucket names:

• My-Travel-Maps (contains uppercase letters)
• my_google_bucket (contains "google")
• test bucket (contains a space)

What's next

• Create Cloud Storage buckets.
• Rename an existing bucket.
• Learn about the metadata associated with a bucket.
• Upload an object.