CustomLocalReply插件 - 服务网格 ASM

ASM网关或网格代理在特定情况下，可能直接向下游返回带有特定响应码的HTTP响应，而不会将请求代理到上游服务。CustomLocalReply插件可以自定义ASM网关或网格代理在直接向下游响应时的响应体、响应码以及响应内容。对于每种响应码，可以分别定义不同的响应内容。

前提条件

已部署入口网关。具体操作，请参见创建入口网关。
已在数据面集群部署httpbin服务。具体操作，请参见部署httpbin应用。

配置字段

名称

数据类型

填写要求

默认值

描述

patch_context

string

必填

指定插件运行的上下文环境，有两种可选值：

GATEWAY：插件运行与ASM网关上。
SIDECAR_INBOUND：插件运行于Sidecar代理上。

需要根据您实际将插件绑定到的工作负载类型（ASM网关或具体业务工作负载）来选择。

custom_error_pages

CustomErrorPage[]

必填

一个CustomErrorPage对象的列表，每个CustomErrorPage对象指定了匹配的直接返回响应码、以及匹配到响应码后需要返回的响应内容。

CustomErrorPage字段说明

当ASM网关无法找到能够匹配请求的路由项时，将返回404响应码
当ASM网关或网格代理配置了授权策略，且请求被授权策略拒绝时，将返回403响应码，响应内容固定为RBAC: Access Denied
当在虚拟服务中配置了directResponse时，ASM网关或网格代理会直接返回指定的响应码及响应体。

名称	数据类型	填写要求	默认值	描述
match_status_code	int	必填	-	匹配的直接返回响应码，当ASM网关或网格代理返回此处指定的响应码时，将应用指定的配置来返回预定义的响应体。
return_status_code	int	必填	-	实际向下游返回的响应码。
content_type	string	必填	-	实际向下游返回的`content-type`。
headers	map[string]string	选填	null	自定义响应中的响应头。
body	string	必填	-	自定义响应中的响应体。

配置示例

在ASM实例中部署如下的虚拟服务：

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

上述的虚拟服务通过配置一个directResponse来让ASM网关直接返回一个404响应，而不将请求转发到上游服务。

使用如下的配置数据开启CustomLocalReply插件，并将插件生效到名为ingressgateway的ASM入口网关上。

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

这个配置会在ASM网关直接返回404响应码时，将响应修改为一个301（Moved Permanently）响应，并在响应头中设置location: https://www.aliyun.com，让浏览器跳转到https://www.aliyun.com。

使用浏览器访问ASM网关IP地址，可以发现浏览器跳转到了阿里云官方网站https://www.aliyun.com，说明插件生效。