Static Website Hosting

Scenarios

OBS buckets can host static websites. You can configure an index page, an error page, and page redirection. To host a static website in OBS, upload the static website files to a bucket, grant anonymous users read permissions for those files, and enable static website hosting for the bucket.

Static websites contain only static web pages and some client-side scripts, such as JavaScript and Flash. In contrast, dynamic websites rely on servers to process scripts, such as PHP, JSP, and ASP.NET. OBS currently does not support scripts that run on servers.

Figure 1 Static website hosting

After static website hosting is configured, you can access OBS in either of the following ways:

• Resource management: In this method, you access OBS through a standard domain name. You can use APIs or SDKs together with the default OBS domain name that includes an endpoint to perform common bucket and object operations, such as uploading, downloading, deleting, and listing.
• Static website: In this method, you access OBS through a dedicated domain name. When static website hosting is enabled, OBS applies the configured hosting rules to display index pages or error pages and redirect requests.

The configuration of static website hosting takes about two minutes to take effect. After it takes effect, you can access static resources using the following URLs:

https://<static-website-domain-name>/object-name
http://<static-website-domain-name>/object-name

The <static-website-domain-name> is in the format of BucketName.obs-website.Endpoint. BucketName indicates the bucket name and Endpoint indicates the regional endpoint. For details about the endpoint of each region, see Regions and Endpoints. For example, suppose you want to use a static website domain name to access bucket testbucket in the CN-Hong Kong region. The endpoint for CN-Hong Kong is ap-southeast-1.myhuaweicloud.com. Therefore, the static website domain name should be testbucket.obs-website.ap-southeast-1.myhuaweicloud.com.

• Avoid using periods (.) in a bucket name, or accessing the bucket over HTTPS may result in certificate verification failures on the client.
• In static website hosting scenarios, anonymous users must be granted access to hosted static website files. When they access those files over the Internet, there will be costs for outbound Internet traffic and requests.

To enable your customers to access the content hosted on the website endpoint, you must make all your content publicly readable. You can use bucket policies or ACLs on objects to grant the required permissions.

The following table lists the differences between the resource management and static website methods.

Important Notes

For security and compliance purposes, Huawei Cloud OBS does not allow you to use static website hosting based on the default domain name (a bucket access domain name or static website domain name). When you use such a domain name to access web pages in a browser, no content will be displayed. Instead, the content is downloaded as an attachment. This restriction takes effect in different regions at the following times:

• January 1, 2022: CN North-Beijing1, CN North-Beijing4, CN East-Shanghai1, CN East-Shanghai2, and CN South-Guangzhou
• March 25, 2022: CN-Hong Kong, AP-Bangkok, AP-Singapore, AF-Johannesburg, LA-Mexico City1, LA-Mexico City2, LA-Sao Paulo1, and LA-Santiago
• Other regions follow their actual effective time.

• You can still use static website hosting with a user-defined domain name. This way, the content can still be previewed. For details, see How Do I Preview OBS Objects in My Web Browser?

Configuring Static Website Hosting

Overview

To host a static website in a bucket, you must configure the bucket with the required website settings. The settings include:

Index document

When you enter a URL such as http://example.com, you are not requesting a specific page. In this case, the web server returns the default page that contains the directory of the requested website. This default page is called an index document, and in most cases it is named index.html. When you configure a bucket for website hosting, you must specify an index document. When a request is sent to the root domain or any subfolder, OBS returns this index document.

Error document

If an error occurs, OBS returns an HTML error document. For 4XX errors, you can optionally provide your own custom error document, where you can offer additional guidance to your users.

Redirection of all requests

If your root domain is example.com and you want to respond to requests for both http://example.com and http://www.example.com, you can create two buckets named example.com and www.example.com. Then, store your website content only in one bucket (such as example.com), and configure the other bucket to redirect all requests to the example.com bucket.

Advanced conditional redirection

You can redirect requests based on a specific object name or prefix in the request, or based on the response code. If you delete or rename an object in your bucket, you can add a routing rule that redirects requests for that object to another object.

To configure redirection in website hosting, use the following syntax format:

<WebsiteConfiguration> 
    <IndexDocument> 
        <Suffix>index.html</Suffix></IndexDocument> 
    <ErrorDocument> 
        <Key>SomeErrorDocument.html</Key> 
    </ErrorDocument> 
    <RoutingRules> 
        ...RoutingRules...
    </RoutingRules> 
</WebsiteConfiguration>

The following gives the syntax format of RoutingRules. The content in square brackets ([]) is optional.

<RoutingRules> = 
    <RoutingRules> 
        <RoutingRule>...</RoutingRule> 
        [<RoutingRule>...</RoutingRule> ...] 
    </RoutingRules> 

<RoutingRule> = 
    <RoutingRule> 
        [ <Condition>...</Condition> ] 
        <Redirect>...</Redirect> 
    </RoutingRule> 

<Condition> = 
    <Condition>  
        [ <KeyPrefixEquals>...</KeyPrefixEquals> ] 
        [ <HttpErrorCodeReturnedEquals>...</HttpErrorCodeReturnedEquals> ] 
    </Condition> 

<Redirect> = 
    <Redirect> 
        [ <HostName>...</HostName> ] 
        [ <Protocol>...</Protocol> ] 
        [ <ReplaceKeyPrefixWith>...</ReplaceKeyPrefixWith> ] 
        [ <ReplaceKeyWith>...</ReplaceKeyWith> ][ 
        <HttpRedirectCode>...</HttpRedirectCode> ] 
    </Redirect>

For details on redirecting all requests and configuring redirection rules, see the "Request Elements" section in Configuring Static Website Hosting for a Bucket.

Examples:

Example 1: Redirecting requests by changing the object name prefix

Assume your bucket contains the following objects:

index.html

docs/article1.html

docs/article2.html

You decide to rename the folder from docs/ to documents/. After the change, any request that uses prefix /docs needs to be redirected to documents/. For example, a request for docs/article1.html should be redirected to documents/article1.html.

To achieve this, you can add the following routing rule to your website configuration.

 <RoutingRules> 
    <RoutingRule> 
    <Condition> 
      <KeyPrefixEquals>docs/</KeyPrefixEquals> 
    </Condition> 
    <Redirect> 
      <ReplaceKeyPrefixWith>documents/</ReplaceKeyPrefixWith> 
    </Redirect> 
    </RoutingRule> 
  </RoutingRules>

Example 2: Redirecting requests for a deleted folder to a specific page

Assume you have deleted the images/ folder (meaning all objects with the images/ prefix). You can add a routing rule that redirects any request for those deleted objects to a page named folderdeleted.html.

<RoutingRules> 
    <RoutingRule> 
    <Condition> 
       <KeyPrefixEquals>images/</KeyPrefixEquals> 
    </Condition> 
    <Redirect> 
      <ReplaceKeyWith>folderdeleted.html</ReplaceKeyWith> 
    </Redirect> 
    </RoutingRule> 
  </RoutingRules>

Example 3: Redirecting requests when an HTTP error occurs

Assume you want to redirect requests to www.example.com whenever a requested object cannot be found. You can add a routing rule that triggers when HTTP status code 404 (Not Found) is returned. In the following example, the rule adds the prefix report-404/ to the redirected object name. For example, if someone requests ExamplePage.html and receives an HTTP 404 error, they will be redirected to the page report-404/ExamplePage.html on the www.example.com. If there is no routing rule and an HTTP 404 error occurs, the error document defined in your website configuration will be returned.

<RoutingRules> 
    <RoutingRule> 
    <Condition> 
      <HttpErrorCodeReturnedEquals>404</HttpErrorCodeReturnedEquals > 
    </Condition> 
    <Redirect> 
      <HostName>www.example.com</HostName> 
      <ReplaceKeyPrefixWith>report-404/</ReplaceKeyPrefixWith> 
    </Redirect> 
    </RoutingRule> 
  </RoutingRules>

Index Document Support

An index document is the web page that a website returns when a request is made to the root directory or any subfolder. For example, if a user enters http://www.example.com in a browser, they are not requesting any specific page. In this case, OBS returns the index document, also known as the default page.

When configuring website hosting for your bucket, you must specify the name of the index document. You also need to upload an object with that name and ensure it is publicly accessible.

The trailing slash (/) in the root URL is optional. If your website uses index.html as its index document, any of the following URLs will return index.html.

http://bucketname.obs-website.example.com/
http://bucketname.obs-website.example.com

In OBS, objects are stored in buckets in a flat structure rather than in a hierarchical file-system layout. However, you can create a logical hierarchy by using object names that resemble folder paths. For example, consider a bucket that contains the following three objects:

• sample1.jpg
• photos/2006/Jan/sample2.jpg
• photos/2006/Feb/sample3.jpg

Although these objects are not stored in actual folders, their names imply the following logical structure:

• sample1.jpg is located at the root level of the bucket.
• sample2.jpg is located in the photos/2006/Jan subfolder.
• sample3.jpg is located in the photos/2006/Feb subfolder.

Custom Error Document Support

Table 1 lists the HTTP status codes that OBS returns when an error occurs.

Permissions Required for Website Access

When you configure a bucket for website hosting, you must make the objects publicly readable. To achieve this, you need to add a bucket policy that grants the GetObject permission to everyone. If the requested object does not exist on the website endpoint, OBS returns an HTTP 404 Not Found response. If the object exists but does not have public read permission, the website endpoint returns an HTTP 403 Access Denied response. The requester can use the response code to determine whether the requested object exists. If you do not need this behavior, do not enable website hosting for the bucket.

In static website hosting scenarios, anonymous users must be granted access to hosted static website files. When they access those files, there will be costs for outbound Internet traffic and requests.

The following example bucket policy grants everyone the permission to access objects in a specified folder. For more information about bucket policies, see Bucket Policy Overview.

{ 
   "Statement":[{ 
    "Sid":"PublicReadGetObject", 
      "Effect":"Allow", 
      "Principal": {"ID":"*"}, 
      "Action":["GetObject"], 
      "Resource":["example-bucket/*"  ] 
    } 
  ] 
}

A bucket policy applies only to objects owned by the bucket owner. If the bucket contains objects that are not owned by the bucket owner, object ACLs should be used to grant public read access to those objects.

You can use bucket policies or object ACLs to grant public read access to your objects. To make objects publicly accessible using ACLs, grant the read permission to everyone, as shown in the following example. You can add the authorization elements below to an object ACL. For details, see ACLs.

<Grant> 
  <Grantee> 
    <Canned>Everyone</Canned> 
  </Grantee> 
  <Permission>READ</Permission> 
</Grant>

Related Functions

Prerequisites

Web page files required for static website hosting have been uploaded to the specified bucket.

The static website files hosted in the bucket are accessible to all users.

Static web page files in the Archive or Deep Archive storage class have been restored. For more information, see Restoring Archive or Deep Archive Objects.

Ways to Configure Static Website Hosting

You can use OBS Console, APIs, or SDKs to configure static website hosting. You cannot use OBS Browser+ or obsutil to do so.