Microservices Engine:Implement frontend canary releases using an MSE cloud-native gateway

Step 1: Deploy the base and canary applications

Deploy two versions of your frontend application in the ACK cluster: a base Deployment and a canary Deployment, each with its own Service and Ingress resource. For details, see Create a stateless application using a Deployment.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: frontend
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
        - image: 'registry.cn-hangzhou.aliyuncs.com/mse-demo-hz/user-gray:base'
          imagePullPolicy: Always
          name: frontend
          resources: {}
---
apiVersion: v1
kind: Service
metadata:
  name: frontend-base-svc
  namespace: default
spec:
  ports:
    - port: 80
      protocol: TCP
      targetPort: 80
  selector:
    app: frontend
  type: ClusterIP

---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  labels:
    ingress-controller: mse
  namespace: default
  name: frontend-base-ingress
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: frontend-base-svc
                port:
                  number: 80
            path: /
            pathType: Prefix

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend-gray
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: frontend-gray
  template:
    metadata:
      labels:
        app: frontend-gray
    spec:
      containers:
        - image: 'registry.cn-hangzhou.aliyuncs.com/mse-demo-hz/user-gray:gray'
          imagePullPolicy: Always
          name: frontend-gray
          resources: {}
---
apiVersion: v1
kind: Service
metadata:
  name: frontend-gray-svc
  namespace: default
spec:
  ports:
    - port: 80
      protocol: TCP
      targetPort: 80
  selector:
    app: frontend-gray
  type: ClusterIP

---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  labels:
    ingress-controller: mse
  annotations:
    nginx.ingress.kubernetes.io/canary: 'true'
    nginx.ingress.kubernetes.io/canary-by-header: x-higress-tag
    nginx.ingress.kubernetes.io/canary-by-header-value: gray
  name: frontend-gray-ingress
  namespace: default
spec:
  ingressClassName: mse
  rules:
    - http:
        paths:
          - backend:
              service:
                name: frontend-gray-svc
                port:
                  number: 80
            path: /
            pathType: Prefix

The canary Ingress uses three annotations to enable header-based traffic splitting:

Step 2: Configure the frontend-gray plug-in

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. On the Gateways page, click the ID of the gateway.

3. In the left-side navigation pane, click Plug-in Marketplace.

4. On the Plug-in Marketplace page, search for frontend-gray and click the frontend-gray plug-in card.

5. Click the Plug-in Configuration tab, choose Domain-level plug-in rules, and then click Add Rule. Configure the following rule: This rule routes users with userid values 00000002 and 00000003 to the canary (gray) version. All other users see the base version. For all available configuration fields, see Plug-in configuration reference and the Higress frontend-gray plug-in documentation.

      grayKey: userid
      rules:
        - name: beta-user
          grayKeyValue:
            - "00000002"
            - "00000003"
      baseDeployment:
        version: base
      grayDeployments:
        - name: beta-user
          version: gray
          enabled: true

   

Step 3: Verify the result

1. Log on to the ACK console. In the left-side navigation pane, click Clusters. Click the cluster that you created. In the left-side navigation pane, choose Network > Ingresses to find the public endpoint.

   

2. Open the public endpoint (for example, nlb-qv04p*******cn-hangzhou.nlb.aliyuncsslb.com). Log on with the admin/ice account. Confirm that the user ID is 00000001 and you see the base version.

3. Log on with the user/ice account. Confirm that the user ID is 00000002 and you see the canary version.

Step 1: Deploy the base and canary applications

Deploy the base and canary Deployments and Services in the ACK cluster. Use the same Deployment and Service manifests as the MSE Ingress gateway approach, but omit the Ingress resources. For details, see Create a stateless application using a Deployment.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: frontend
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
        - image: 'registry.cn-hangzhou.aliyuncs.com/mse-demo-hz/user-gray:base'
          imagePullPolicy: Always
          name: frontend
          resources: {}
---
apiVersion: v1
kind: Service
metadata:
  name: frontend-base-svc
  namespace: default
spec:
  ports:
    - port: 80
      protocol: TCP
      targetPort: 80
  selector:
    app: frontend
  type: ClusterIP

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend-gray
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: frontend-gray
  template:
    metadata:
      labels:
        app: frontend-gray
    spec:
      containers:
        - image: 'registry.cn-hangzhou.aliyuncs.com/mse-demo-hz/user-gray:gray'
          imagePullPolicy: Always
          name: frontend-gray
          resources: {}
---
apiVersion: v1
kind: Service
metadata:
  name: frontend-gray-svc
  namespace: default
spec:
  ports:
    - port: 80
      protocol: TCP
      targetPort: 80
  selector:
    app: frontend-gray
  type: ClusterIP

Step 2: Configure the frontend-gray plug-in

Follow the same plug-in configuration steps as the MSE Ingress gateway approach.

Step 3: Add a service source

Register your ACK cluster as a service source so the gateway can discover your Kubernetes Services.

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. In the left-side navigation pane, click Routes. Click the Source tab.

4. Click Add Source. In the Add Source panel, select Container Service for Source Type, select your ACK cluster from the ACK/ASK/ACS Cluster drop-down list, and then click OK.

   

Step 4: Add services

Import the base and canary Kubernetes Services into the gateway.

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. In the left-side navigation pane, click Routes. Click the Services tab.

4. Click Add Service. In the Add Service panel, configure the parameters, and click OK.

   

Step 5: Add a base route

Create a route that directs default traffic to the base frontend Service.

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. In the left-side navigation pane, click Routes. Click Add Route.

4. On the Add Route page, configure the parameters, and click Save and Advertise.

   

Step 6: Add a canary route

Create a route that directs canary traffic to the canary frontend Service.

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. In the left-side navigation pane, click Routes. Click Add Route.

4. On the Add Route page, configure the parameters, and click Save and Advertise.

   Note

   Set the version to gray. This value corresponds to grayDeployments.version in the frontend-gray plug-in configuration.

   

Step 7: Verify the result

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. On the Overview page, click the Endpoint tab to find the public endpoint.

   

4. Open the public endpoint (for example, nlb-qv04p*******cn-hangzhou.nlb.aliyuncsslb.com). Log on with the admin/ice account. Confirm that the user ID is 00000001 and you see the base version.

5. Log on with the user/ice account. Confirm that the user ID is 00000002 and you see the canary version.

Step 1: Deploy two frontend application versions on an ECS instance

Deploy the base and canary versions on the same or separate ECS instances:

• Base version endpoint: 120.***.137.243:80

• Canary version endpoint: 120.***.137.243:8081

Step 2: Add services

Register both frontend versions as fixed-address services in the gateway.

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. In the left-side navigation pane, click Routes. Click the Services tab.

4. Click Add Service. In the Add Service panel, select Fixed Address from the Service Source drop-down list, configure the parameters, and then click OK.

   

   

Step 3: Add a base route

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. In the left-side navigation pane, click Routes. Click Add Route.

4. On the Add Route page, configure the parameters, and click Save and Advertise.

   

Step 4: Add a canary route

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. In the left-side navigation pane, click Routes. Click Add Route.

4. On the Add Route page, configure the parameters, and click Save and Advertise.

   Note

   Set the version to gray. This value corresponds to grayDeployments.version in the frontend-gray plug-in configuration.

   

Step 5: Configure the frontend-gray plug-in

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. In the left-side navigation pane, click Plug-in Marketplace.

4. On the Plug-in Marketplace page, search for frontend-gray and click the frontend-gray plug-in card.

5. Click the Plug-in Configuration tab, choose Domain-level plug-in rules, and then click Add Rule. Configure the following rule: For all available configuration fields, see Plug-in configuration reference and the Higress frontend-gray plug-in documentation.

      grayKey: userid
      rules:
        - name: beta-user
          grayKeyValue:
            - "00000002"
            - "00000003"
      baseDeployment:
        version: base
      grayDeployments:
        - name: beta-user
          version: gray
          enabled: true

   

Step 6: Verify the result

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. On the Overview page, click the Endpoint tab to find the public endpoint.

   

4. Open the public endpoint (for example, nlb-qv04p*******cn-hangzhou.nlb.aliyuncsslb.com). Log on with the admin/ice account. Confirm that the user ID is 00000001 and you see the base version.

5. Log on with the user/ice account. Confirm that the user ID is 00000002 and you see the canary version.

Step 1: Prepare your OSS file structure

Organize your frontend assets in OSS with version-based directories:

- app1                          # Application
  - dev                         # Base version (development)
    - index.html
    - js/
    - css/
    - images/
  - 0.0.1                      # Canary version 1
    - index.html
    - js/
    - css/
    - images/
  - 0.0.2                      # Canary version 2
    - index.html
    - js/
    - css/
    - images/
- app2
  - dev/
  - 0.0.1/
  - 0.0.2/

Step 2: Add a service

Register your OSS endpoint as a DNS-based service in the gateway.

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. In the left-side navigation pane, click Routes. Click the Services tab.

4. Click Add Service. In the Add Service panel, select DNS Domain Name from the Service Source drop-down list, enter the OSS endpoint, and then click OK.

   Important

   If OSS and the gateway are in the same region, use the internal OSS endpoint to avoid public network charges. If they are in different regions, use the public endpoint.

   

Step 3: Add a route

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. In the left-side navigation pane, click Routes. Click Add Route.

4. On the Add Route page, configure the parameters, and click Save and Advertise.

   

Step 4: Configure the frontend-gray plug-in

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. In the left-side navigation pane, click Plug-in Marketplace.

4. On the Plug-in Marketplace page, search for frontend-gray and click the frontend-gray plug-in card.

5. Click the Plug-in Configuration tab, choose Domain-level plug-in rules, and then click Add Rule. Configure the following rule: The CDN/OSS approach differs from the other approaches in the following fields: For all available configuration fields, see Plug-in configuration reference and the Higress frontend-gray plug-in documentation.

   Field	Description
   rewrite.host	The OSS endpoint that hosts your frontend assets
   rewrite.indexRouting	Maps URL paths to versioned index.html files in OSS. The {version} placeholder is replaced by the version string (dev or 0.0.1)
   rewrite.fileRouting	Maps URL paths to versioned static asset directories in OSS
   baseDeployment.version	Set to dev (the base version directory name in OSS)
   grayDeployments[0].version	Set to 0.0.1 (the canary version directory name in OSS)

      grayKey: userid
      rules:
        - name: beta-user
          grayKeyValue:
            - "00000002"
            - "00000003"
      rewrite:
        host: xx.oss-cn-shanghai.aliyuncs.com       ## Replace with your OSS endpoint
        indexRouting:
          "/app1": "/project-a/app1/{version}/index.html"  # Path rewrite for HTML entry pages
        fileRouting:
          "/app1": "/project-a/app1/{version}"              # Path rewrite for CSS, JavaScript, and images
      baseDeployment:
        version: dev
      grayDeployments:
        - name: beta-user
          version: 0.0.1
          enabled: true

Step 5: Verify the result

1. Log on to the MSE console. In the top navigation bar, select a region.

2. In the left-side navigation pane, choose Cloud-native Gateway > Gateways. Click the ID of the gateway.

3. On the Overview page, click the Endpoint tab to find the public endpoint.

   

4. Open the public endpoint (for example, nlb-qv04p*******cn-hangzhou.nlb.aliyuncsslb.com). Log on with the admin/ice account. Confirm that the user ID is 00000001 and you see the base version.

5. Log on with the user/ice account. Confirm that the user ID is 00000002 and you see the canary version.

Can I use rewrite policies and frontend canary release at the same time?

It depends on your service source:

• Non-CDN/OSS sources (ACK, ECS): Yes. Rewrite policies and canary release work independently and do not conflict.

• CDN or OSS sources: No. The frontend-gray plug-in handles path rewriting internally through the rewrite configuration block. Adding a separate rewrite policy causes conflicts and may return HTTP 403 errors.

Can I inject global variables into the HTML page?

Yes. Use the injection configuration block to inject JavaScript or CSS into the HTML entry page. Injection supports three positions:

Example configuration:

grayKey: userid
rules:
  - name: inner-user
    grayKeyValue:
      - '00000001'
      - '00000005'
baseDeployment:
  version: base
grayDeployments:
  - name: beta-user
    version: gray
    enabled: true
    weight: 80
injection:
  head:
    - <script>console.log('Header')</script>
  body:
    first:
      - <script>console.log('hello world before')</script>
      - <script>console.log('hello world before1')</script>
    last:
      - <script>console.log('hello world after')</script>
      - <script>console.log('hello world after2')</script>

This example also demonstrates weight-based canary release. With weight: 80, 80% of non-rule-matched traffic goes to the canary version, and 20% goes to the base version.

When does the canary version take effect for a user?

The canary version takes effect on the next full page load, not in real time. If user A is on version 0.0.1 and you publish version 0.0.2 with a canary rule that matches user A, the new version appears only after user A refreshes or re-loads the page.

This behavior is by design for two reasons:

• User experience: Switching versions mid-session could break in-progress interactions, such as making a button disappear while a user is clicking it.

• Architecture decoupling: Real-time version switching would require the backend to dynamically control frontend versions, coupling frontend and backend releases and preventing CDN caching.

When does a page refresh occur?

A page refresh typically occurs when:

• A session expires and the user re-authenticates.

• The user navigates to the login page.

To load the latest canary configuration on login, redirect with a full page navigation:

async function handleLogin(values: LoginParams) {
  try {
    const result = await login(values);
    if (result.success) {
      message.success('Logon succeeded.');
      await updateUserInfo();
      const urlParams = new URL(window.location.href).searchParams;
      // Full page redirect ensures the canary version is loaded
      window.location.href = `${urlParams.get('redirect') || '/'}`;
      return;
    }
    console.log(result);
    setLoginResult(result);
  } catch (error) {
    message.error('Logon failed. Try again.');
    console.log(error);
  }
}

The key line is window.location.href = .... This triggers a full page navigation, forcing the browser to request the page from the gateway. The frontend-gray plug-in then evaluates the canary rules and serves the correct version.