Configure an MSE cloud-native gateway for static website hosting on OSS - Microservices Engine

In a frontend-backend separation architecture, static assets (HTML, CSS, JavaScript) live in object storage while backend services run independently. When your application already uses a Microservices Engine (MSE) cloud-native gateway to route API traffic, you can add Object Storage Service (OSS) as a backend service on the same gateway. This gives you a single entry point for both static content and backend APIs, with gateway-level URL rewriting, header manipulation, and routing policies applied to all traffic.

This tutorial walks through storing static files in an OSS bucket and configuring an MSE cloud-native gateway to serve them. After you finish, the gateway routes requests such as example.com/index.html to files in OSS and requests such as example.com/app to backend services.

When to use this approach

Use an MSE cloud-native gateway to serve static content from OSS when:

Your application already uses an MSE cloud-native gateway for backend API routing, and you want a single entry point for both static assets and APIs.
You need URL rewriting, header manipulation, or other gateway-level policies for static content.

For a standalone static website without backend services, OSS static website hosting is a simpler alternative.

How it works

The following diagram shows the request flow:

Client request
     |
     v
MSE cloud-native gateway
     |
     |-- /index.html, /style.css, ...  -->  OSS bucket (static files)
     |
     +-- /app, /api/...               -->  Backend services

The gateway matches each incoming request against its route rules. Static file requests go to the OSS bucket's internal endpoint, with the host header rewritten so that OSS resolves the correct bucket. The content-disposition response header is removed so that browsers render files inline instead of downloading them.

Prerequisites

Before you begin, make sure that you have:

An MSE cloud-native gateway. For more information, see Create an MSE cloud-native gateway

Step 1: Create an OSS bucket and upload a static page

Create a public-read OSS bucket and upload a sample HTML page.

Log on to the OSS console.
In the left-side navigation pane, click Buckets, and then click Create Bucket.

In the Create Bucket panel, configure the following parameters and keep the defaults for all others. Then click OK.

A public-read ACL allows anyone to read objects in this bucket. For production workloads, evaluate whether a more restrictive ACL with signed URLs is appropriate for your security requirements.

Parameter	Value
Bucket Name	Enter a bucket name. This tutorial uses `static-demo-0`.
Storage Class	Select Standard.
ACL	Click Public Read. When the Are you sure you want to select Public Read? confirmation appears, click Continue.

On the Buckets page, click the name of the bucket you created. In the Objects pane, click Upload Object.

Set Object ACL to Inherited from Bucket and upload the following index.html file:

   <html>
      <head>
          <title>Hello OSS!</title>
          <meta charset="utf-8">
      </head>
      <body>
          <p>Configure static website hosting for Alibaba Cloud OSS.</p>
          <p>This is the index page.</p>
      </body>
   </html>

Click Upload Object. After the upload completes, the file name, size, and storage class appear in the destination directory.

Step 2 (optional): Set a default homepage and a 404 error page

Configure a default homepage so that requests to / return index.html. You can also configure a custom 404 page for unmatched paths.

Set a default homepage

In the OSS console, open your bucket settings and set index.html as the default homepage.

Set a custom 404 page

Upload a 404.html file to the bucket:

   <html>
      <head>
          <title>The page you visited does not exist</title>
          <meta charset="utf-8">
      </head>
      <body>
          <p>The page you visited does not exist.</p>
          <p>You can try to visit the homepage.</p>
      </body>
   </html>

In the bucket's static website hosting settings, set 404.html as the error page.

For detailed instructions, see Configure static website hosting.

Step 3: Get the internal endpoint of the OSS bucket

Every OSS bucket has a default domain name. You need the internal endpoint to configure the gateway service in the next step.

In the OSS console, open the bucket's Overview page and find the internal endpoint in the Port section. The endpoint follows the format <bucket-name>.oss-<region>-internal.aliyuncs.com.

For more information, see Access OSS from an ECS instance through an internal endpoint.

Step 4: Add the OSS bucket as a gateway service

The MSE cloud-native gateway treats each OSS bucket as a DNS-discovered service. Register the bucket's internal endpoint as a service on the gateway.

Log on to the MSE console.
In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the name of your gateway.
In the left-side navigation pane, click Routes. On the page that appears, click the Services tab.

Click Add Service and configure the following parameters in the Add Service panel. Then click OK.

Parameter	Value
Service Source	Select DNS Domain Name.
Service Name	Enter a name for the service. This tutorial uses `static`.
Service Port	Enter `80`.
Domain Names	Enter the internal endpoint from Step 3, for example, `static-demo-0.oss-cn-hangzhou-internal.aliyuncs.com`.
TLS mode	Select Disabled.

Step 5: Create a route and configure policies

Create a route that forwards static file requests to the OSS service, then add a rewrite policy and a header policy.

Create the route

Log on to the MSE console.
In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the name of your gateway.
In the left-side navigation pane, click Routes, and then click the Routes tab.
Click Add Route. Set the matching rule to Prefix, the path to /, and the destination service to static. For more information, see Create a route.

Add a rewrite policy

The rewrite policy rewrites the host header so that OSS resolves the correct bucket when the gateway forwards the request.

On the Routes tab, click the name of the route you created. Click the Policies tab.
In the left-side navigation pane of the Policies tab, click Rewrite. Enter the internal endpoint of the OSS bucket (for example, static-demo-0.oss-cn-hangzhou-internal.aliyuncs.com) in the Destination Host field, and click Save. For more information, see Configure a rewrite policy.

Remove the content-disposition response header

By default, OSS sets a content-disposition header that causes browsers to download files instead of rendering them. Remove this header so that static pages display correctly in the browser.

In the left-side navigation pane of the Policies tab, click Edit Header. Add a policy to delete the content-disposition header from OSS responses, and enable the policy. For more information, see Configure a header setting policy.

Verify the result

Test the setup by visiting the following URLs in a browser. Replace example.com with your service domain name.

URL	Expected result
`example.com`	Returns `index.html` (the default homepage configured in Step 2).
`example.com/index.html`	Returns `index.html` directly.
`example.com/test`	Returns `404.html` (the custom error page configured in Step 2).

Production considerations

After you verify basic functionality, consider the following before serving production traffic:

HTTPS: Configure an SSL certificate on the MSE cloud-native gateway to serve static content over HTTPS.
Caching: Add Alibaba Cloud CDN in front of the gateway, or configure cache policies on the gateway, to reduce latency and OSS access costs.
Access control: Tighten the bucket ACL and use signed URLs or gateway-level authentication instead of public-read access.