Google Cloud Storage

Website Configuration

The Website Configuration feature enables you to configure a Google Cloud Storage bucket to simulate the behavior of a static website. You can define main pages or directory indices (for example, index.html) for buckets and "directories". Also, you can define a custom error page in case a requested resource does not exist.


  1. How Website Configuration Works
  2. Applying Website Configuration to a Bucket

How Website Configuration Works

Website Configuration provides the following bucket properties.

  • MainPageSuffix simulates directory index behavior at both bucket and "directory" level, by enabling you to specify the following:
    • A main page for the bucket.
    • Main pages for requests to "directories" contained by the bucket.
  • NotFoundPage specifies the object to produce when site visitors request a missing resource.

Website Configuration Details

This topic uses the example bucket named where
  • The bucket contains objects index.html, 404.html and dir/index.html.
  • MainPageSuffix is assigned to index.html.
  • NotFoundPage is assigned to 404.html.
  • The domain is a CNAME alias to

Website Configuration parameters will only affect requests directed to CNAME aliases of For the example bucket described earlier, only requests to will exhibit website behavior. This preserves existing API behavior, such as bucket listing, for requests using a Google Cloud Storage domain, for example

  • MainPageSuffix
    • GET Object requests return the object specified by MainPageSuffix. For example, GET returns the object index.html.
    • GET Object requests to missing objects have their URL appended with the bucket’s MainPageSuffix value. For example, if does not exist, a request for that object returns
  • NotFoundPage
    • GET requests to missing objects, which do not correspond to a local main page return the object specified by NotFoundPage. For example, GET returns 404.html.

This behavior for the bucket is shown in the figure below.

Processing a Web Request
Processing a Web Request

Applying Website Configuration to a Bucket

The following are the steps you must follow to configure website parameters.
You may find the gsutil tool useful for creating and manipulating Google Cloud Storage buckets and objects.

  1. Verify your ownership of a custom domain and create a bucket named after that domain.
  2. Configure your domain as a CNAME alias to A CNAME alias is a DNS record that lets you use a URL from your own domain to access a resource (bucket or object) in Google Cloud Storage without revealing the Google Cloud Storage URL. For more information, see URI for CNAME Redirects.
  3. Create the desired main page(s) and error object, for example: index.html, dir/index.html and 404.html.
  4. Apply a website configuration to your bucket. Based on your requirements, you can do this using the raw XML API or the gsutil tool.

Website Configuration Using gsutil

To configure a bucket you can use the gsutil tool, please see the built-in documentation by running:

  gsutil help web

Website Configuration Using the API

Writing configuration values

Buckets are configured using PUT Bucket requests with query parameter websiteConfig and an XML body describing the two fields MainPageSuffix and NotFoundPage, as shown in the example below.

PUT / HTTP/1.1
Content-Length: 131
Authorization: Bearer 1/zVNpoQNsOSxZKqOZgckhpQ

Reading configuration values

To read a bucket configuration you use the GET Bucket method with the websiteConfig query parameter, as shown next.

GET / HTTP/1.1
Content-Length: 0
Authorization: Bearer 1/zVNpoQNsOSxZKqOZgckhpQ
Removing website configuration properties

To disable website configuration properties, simply exclude the corresponding field(s). The following example disables both the MainPageSuffix and NotFoundPage properties.

PUT / HTTP/1.1
Content-Length: 47
Authorization: Bearer 1/zVNpoQNsOSxZKqOZgckhpQ

Listing objects in a website-configured bucket

Website configurations are only used to interpret requests where the hostname is a custom domain, for example
This preserves existing API behavior for requests to Google Cloud Storage domains, for example Thus you can continue to list the bucket as shown next.

GET / HTTP/1.1
Content-Length: 0
Authorization: Bearer 1/zVNpoQNsOSxZKqOZgckhpQ

Back to top

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.