CustomLocalReply plug-in - Alibaba Cloud Service Mesh - Centro de documentación de Alibaba Cloud

Cuando una puerta de enlace de ASM o un proxy sidecar intercepta una solicitud y devuelve una respuesta HTTP directamente, sin reenviarla al servicio upstream, el cuerpo de la respuesta predeterminado es un mensaje genérico como not found o RBAC: Access Denied. El plug-in CustomLocalReply reemplaza estas respuestas predeterminadas con códigos de estado, encabezados y contenido de cuerpo personalizados. Esto le permite redirigir URL obsoletas, aplicar su marca a las páginas de error o estandarizar los formatos de error de API en toda su malla de servicios.

Escenarios

Si desea...	Consulte
Redirigir URL obsoletas a una nueva ubicación	Redirigir un error 404 a otra URL
Devolver una página de error HTML con su marca en lugar de texto sin formato	Devolver una página 403 personalizada
Estandarizar las respuestas de error de API en formato JSON	Devolver una respuesta de error en JSON

Cuándo se generan respuestas locales

ASM genera una respuesta local (sin pasar por el servicio upstream) en las siguientes situaciones:

Desencadenante	Código de estado predeterminado	Cuerpo predeterminado
Ninguna regla de enrutamiento coincide con la solicitud	`404`	`not found`
Una política de autorización rechaza la solicitud	`403`	`RBAC: Access Denied`
Se configura una `directResponse` en el servicio virtual	Definido por el usuario	Definido por el usuario

El plug-in CustomLocalReply intercepta estas respuestas antes de que lleguen al servicio downstream y aplica sus anulaciones.

Requisitos previos

Antes de empezar, asegúrese de cumplir con lo siguiente:

Tener una puerta de enlace de entrada desplegada. Para obtener más información, consulte Create an ingress gateway.
Tener el servicio HTTPBin ejecutándose en el clúster del plano de datos. Consulte Deploy the HTTPBin application

Referencia de configuración

Campos de nivel superior

Campo	Tipo	Obligatorio	Valores válidos	Descripción
`patch_context`	String	Sí	`GATEWAY`, `SIDECAR_INBOUND`	Contexto de ejecución. Establezca este valor en `GATEWAY` para una puerta de enlace de ASM, o en `SIDECAR_INBOUND` para un proxy sidecar.
`custom_error_pages`	CustomErrorPage[]	Sí	--	Lista de anulaciones de páginas de error. Cada entrada asigna un código de estado generado localmente a una respuesta personalizada.

Campos de CustomErrorPage

Campo	Tipo	Obligatorio	Predeterminado	Descripción
`match_status_code`	Integer	Sí	--	Código de estado generado localmente que se debe interceptar. Cuando la puerta de enlace o el sidecar genera este código, se aplica la anulación correspondiente.
`return_status_code`	Integer	Sí	--	Código de estado que se devuelve al servicio downstream en lugar del código coincidente.
`content_type`	String	Sí	--	Valor del encabezado de respuesta `content-type` (por ejemplo, `text/html; charset=UTF-8` o `application/json`).
`headers`	Map[string]string	No	null	Encabezados de respuesta adicionales que se incluyen en la respuesta personalizada.
`body`	String	Sí	--	Cuerpo de la respuesta que se devuelve al servicio downstream.

Redirigir un error 404 a otra URL

Este ejemplo intercepta la respuesta 404 generada por una regla directResponse y la convierte en una redirección 301.

Paso 1: Desplegar un VirtualService con una respuesta directa

Aplique el siguiente VirtualService a su instancia de ASM. Esta configuración indica a la puerta de enlace que devuelva un código de estado 404 con el cuerpo not found para todas las solicitudes.

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

Paso 2: Habilitar el plug-in CustomLocalReply

Aplique la siguiente configuración del plug-in a la puerta de enlace de entrada de ASM llamada ingressgateway. Esta configuración coincide con el código de estado 404 y lo reemplaza por una redirección 301 hacia https://www.aliyun.com.

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

Comprobar la redirección

Abra un navegador y vaya a la dirección IP de la puerta de enlace de ASM. El navegador redirige a https://www.aliyun.com, lo que confirma que la configuración del plug-in está activa.

Devolver una página 403 personalizada

Este ejemplo reemplaza el mensaje predeterminado RBAC: Access Denied con una página de error HTML con su marca cuando una política de autorización rechaza una solicitud.

Aplique la siguiente configuración del plug-in a la puerta de enlace de entrada de ASM llamada ingressgateway:

patch_context: GATEWAY
custom_error_pages:
  - match_status_code: 403
    return_status_code: 403
    content_type: text/html; charset=UTF-8
    body: |
      <!DOCTYPE html>
      <html>
      <head><title>Access Denied</title></head>
      <body>
        <h1>403 - Access Denied</h1>
        <p>You do not have permission to access this resource.
           Contact your administrator if you believe this is an error.</p>
      </body>
      </html>

Cuando una política de autorización rechaza una solicitud, la puerta de enlace devuelve esta página HTML en lugar del mensaje de texto sin formato RBAC: Access Denied.

Devolver una respuesta de error en JSON

Este ejemplo devuelve un cuerpo de error JSON estructurado para las respuestas 404. Resulta útil para servicios de API que requieren un formato de error consistente.

Aplique la siguiente configuración del plug-in a la puerta de enlace de entrada de ASM llamada ingressgateway:

patch_context: GATEWAY
custom_error_pages:
  - match_status_code: 404
    return_status_code: 404
    content_type: application/json
    body: |
      {
        "error": {
          "code": 404,
          "message": "The requested resource was not found.",
          "status": "NOT_FOUND"
        }
      }

Cuando la puerta de enlace genera una respuesta 404, el servicio downstream recibe un cuerpo JSON con una estructura de error estandarizada en lugar del mensaje de texto sin formato not found.

Varias anulaciones en una sola configuración

Defina varias entradas en custom_error_pages para gestionar distintos códigos de estado en una única configuración del plug-in. El siguiente ejemplo anula tanto las respuestas 404 como las 403:

patch_context: GATEWAY
custom_error_pages:
  - match_status_code: 404
    return_status_code: 404
    content_type: application/json
    body: |
      {
        "error": {
          "code": 404,
          "message": "The requested resource was not found.",
          "status": "NOT_FOUND"
        }
      }
  - match_status_code: 403
    return_status_code: 403
    content_type: application/json
    body: |
      {
        "error": {
          "code": 403,
          "message": "Access denied by authorization policy.",
          "status": "FORBIDDEN"
        }
      }