CustomLocalReply plug-in - Alibaba Cloud Service Mesh - Alibaba Cloud Documentation Center

In some cases, an ASM gateway or sidecar proxy may directly return an HTTP response with a specific status code to the downstream service, instead of forwarding the response to the upstream service. The CustomLocalReply plug-in allows you to customize the response body, response code, and response header returned by an ASM gateway or sidecar proxy to the downstream service. You can specify unique response content for each response code.

Prerequisites

An ingress gateway is deployed. For more information, see Create an ingress gateway.
The HTTPBin service is deployed in the data plane cluster. For more information, see Deploy the HTTPBin application.

Configuration fields

Name

Data type

Required

Valid value

Description

patch_context

String

Yes

GATEWAY: The plug-in runs on an ASM gateway.
SIDECAR_INBOUND: The plug-in runs on a sidecar proxy.

Configure the parameter based on the type of workload to which you attach the plug-in (ASM gateway or specific business workload).

Specifies the context and runtime environment in which a plug-in is executed.

custom_error_pages

CustomErrorPage[]

Yes

Specifies the list of CustomErrorPage objects. Each CustomErrorPage object specifies the response code that is directly returned by an ASM gateway or sidecar proxy and the response content returned when the response code is received.

CustomErrorPage field description

When the ASM gateway cannot find a routing rule that matches the request, it returns an HTTP status code404.
When the ASM gateway or sidecar proxy is configured with an authorization policy and the request is rejected by the authorization policy, it returns an HTTP status code 403, with the response content fixed as RBAC: Access Denied.
When directResponse is configured in the virtual service, the ASM gateway or sidecar proxy directly returns the specified HTTP status code and response body.

Name	Data type	Required	Default value	Description
match_status_code	Integer	Yes	-	Specifies the matching HTTP status code directly returned by an ASM gateway or sidecar proxy. When the ASM gateway or sidecar proxy returns the specified HTTP status code, the specified configuration is applied to return the predefined response body.
return_status_code	Integer	Yes	-	Specifies the HTTP status code returned to the downstream service.
content_type	String	Yes	-	Specifies the `content-type` returned to the downstream service.
headers	Map[string]string	Optional	null	Specifies the response headers in custom responses.
body	String	Yes	-	Specifies the response body in custom responses.

Sample configuration

Deploy the following virtual service in the ASM instance:

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: httpbin
  namespace: default
spec:
  gateways:
    - httpbin-gateway
  hosts:
    - '*'
  http:
    - directResponse:
        body:
          string: not found
        status: 404

For the virtual service above, configure a directResponse to enable the ASM gateway to directly return an HTTP status code 404 instead of forwarding the request to the upstream service.

Use the following configuration to enable the CustomLocalReply plug-in and apply the plug-in to the ASM ingress gateway named ingressgateway.

patch_context: GATEWAY
custom_error_pages:
  - match_status_code: 404
    return_status_code: 301
    headers:
      location: 'https://www.aliyun.com'
    content_type: text/html; charset=UTF-8
    body: moved

This configuration allows you to change the HTTP status code 404 directly returned by the ASM gateway to a HTTP status code 301 (Moved Permanently) and configure the location: https://www.aliyun.com in the response header to redirect the browser to https://www.aliyun.com.

If you access the ASM gateway IP address using a browser, you are redirected to the Alibaba Cloud official website https://www.aliyun.com. This indicates that the modified plug-in configuration has taken effect.