You must follow bucket and object naming guidelines when you use the Google Cloud Storage API. Requests that use malformed or disallowed names will often fail.
Bucket Name Requirements
Bucket names reside in a single Google Cloud Storage namespace. As a consequence, every bucket name must be unique across the entire Google Cloud Storage namespace. If you try to create a bucket with a bucket name that is already taken, Google Cloud Storage responds with an error message.
As a best practice, bucket names must conform to standard DNS naming conventions. This is because a bucket name can appear in a DNS record as part of a CNAME redirect. In addition to meeting DNS naming requirements, Google Cloud Storage imposes other requirements on bucket naming as well. At a minimum, your bucket names must meet the following requirements:
- Bucket names must contain only lowercase letters, numbers, dashes (
-), underscores (
_), and dots (
.). Names containing dots require verification.
- Bucket names must start and end with a number or letter.
- Bucket names must contain 3 to 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 of "google".
Also, for DNS compliance and future compatibility, you should not use underscores
_) or have a period adjacent to another period or dash. For example, ".." or "-." or
".-" are not valid in DNS names.
See also the Naming Best Practices section, which includes recommendations about excluding proprietary information from bucket and object names.
Object Name Requirements
Object names can contain any sequence of valid Unicode characters, of length 1-1024 bytes when UTF-8 encoded, and must not contain Carriage Return or Line Feed characters.
For more information about Carriage Return and Line Feed characters, see Newline.
We strongly recommend that you abide by the following object naming conventions:
- Avoid using control characters that are illegal in XML 1.0 in your object names (#x7F–#x84 and #x86–#x9F). These characters will cause XML listing issues when you try to list your objects.
- Avoid using "#" in your object names. gsutil interprets object names ending with #<numeric string> as version identifiers, so including "#" in object names can make it difficult or impossible to perform various operations on such objects using gsutil (see Object Versioning and Concurrency Control).
- Avoid using "[", "]", "*", or "?" in your object names. gsutil interprets these characters as wildcards, so including any of these characters in object names can make it difficult or impossible to perform various wildcard operations using gsutil (see Wildcard Names).
Bucket Name Verification
Google Cloud Storage considers bucket names that contain dots to be domain names, and as such bucket names must:
- Be syntactically valid DNS names (for example, bucket..example.com is not valid because it contains two dots in a row)
- End with a currently-recognized top-level domain, such as .com
- Pass domain ownership verification
If your project needs to have a domain-named bucket, the team member creating the bucket must demonstrate that he or she is an owner or manager of the domain before creating the bucket. Google Cloud Storage verifies that the user is an owner or manager of that domain before permitting creation of a domain-named bucket.
To demonstrate that you are an owner or manager of a domain, use the Search Console verification process. The verification process provides a number of ways to demonstrate ownership of a site or domain, including:
- Adding a special Meta tag to the site's homepage.
- Uploading a special HTML file to the site.
- Adding a DNS TXT record to the domain's DNS configuration.
Meta tag verification and HTML file verification are easier to perform and are probably adequate for most situations. They demonstrate ownership of the web site for the domain or its parent. DNS TXT record verification demonstrates ownership of the domain itself, and is how you must verify ownership when you want to create a domain-named bucket, for example, to host content. For more information, see Domain-based Verification below.
If a domain has one or more verified owners, then Google Cloud Storage requires domain ownership to create a domain-named bucket within that domain. If a domain does not have any verified owners, then verified web site owners may create domain-named buckets within that domain. If neither the domain nor its web site have any verified owners, then domain-named buckets may not be created within that domain. Domain ownership is a higher level of control than web site ownership and may be useful in situations where a site wants to tightly control who can create domain-named buckets.
For example, you might have two IT staff members who are responsible for managing your site, called "example.com". If they complete the DNS TXT record verification, only they would be able to create buckets called "example.com", "reports.example.com", "downloads.example.com", and other domain-named buckets.
Verified web site and domain owners can use Search Console to add additional web site or domain owners. From the Search Console dashboard, find the web site you want to manage and select Manage property > Add or remove users. To add a domain owner, select Manage property owners link. If you are a domain owner, you can add additional domain owners.
Authorizing Service AccountsOnce you have performed domain verification, you can authorize a service account to create buckets under that domain. Go to the Search Console's verification process at
https://www.google.com/webmasters/verification/details?hl=en&domain=<your-domain.com>. Click the button Add an owner at the end of the page to add the email address for your service account.
If you have administrative control over the HTML files that make up a site, you can use one of the site-based verification methods to verify that you control or own a site. When you do this, Google Cloud Storage lets you create buckets representing the verified site and any subsites—provided nobody has used the DNS TXT record method to verify domain ownership of a parent of the site.
As an example, assume that nobody has used the DNS TXT record method to verify ownership of the following domains: abc.def.example.com, def.example.com, and example.com. In this case, Google Cloud Storage lets you create a bucket named abc.def.example.com if you verify that you own or control any of the following sites:
If you have administrative control over a domain's DNS configuration, you can use the DNS TXT record verification method to verify that you own or control a domain. When you use the domain-based verification method to verify that you own or control a domain, Google Cloud Storage lets you create buckets that represent any subdomain under the verified domain. Furthermore, Google Cloud Storage prevents anybody else from creating buckets under that domain unless you add their name to the list of verified domain owners or they have verified their domain ownership by using the DNS TXT record verification method.
For example, if you use the DNS TXT record verification method to verify your ownership of the domain example.com, Google Cloud Storage will let you create bucket names that represent any subdomain under the example.com domain, such as abc.def.example.com, example.com, or abc.example.com.
Using the DNS TXT record method to verify domain ownership supersedes verification by site-based verification methods. For example, if you use the Meta tag method or HTML file method to verify domain ownership of http://example.com, but someone else uses the DNS TXT record method to verify ownership of the example.com domain, Google Cloud Storage will not allow you to create a bucket named example.com. To create the bucket example.com, the domain owner who used the DNS TXT method to verify domain ownership must add you to the list of verified domain owners for example.com.
The DNS TXT record verification method is particularly useful if you manage a domain for a large organization that has numerous subdomains because it lets you control who can create buckets representing those domain names.
You must use DNS TXT record verification before creating a domain-named bucket to host content.