proxy-mirror.md

title	keywords	description
proxy-mirror	Apache APISIX API Gateway Proxy Mirror	The proxy-mirror Plugin duplicates ingress traffic to APISIX and forwards them to a designated Upstream without interrupting the regular services.

Description

The proxy-mirror Plugin duplicates ingress traffic to APISIX and forwards them to a designated upstream, without interrupting the regular services. You can configure the Plugin to mirror all traffic or only a portion. The mechanism benefits a few use cases, including troubleshooting, security inspection, analytics, and more.

Note that APISIX ignores any response from the Upstream host receiving mirrored traffic.

Attributes

Name	Type	Required	Default	Valid values	Description
host	string	True			Address of the host to forward the mirrored traffic to. The address should contain the scheme but without the path, such as http://127.0.0.1:8081.
path	string	False			Path of the host to forward the mirrored traffic to. If unspecified, default to the current URI path of the Route. Not applicable if the Plugin is mirroring gRPC traffic.
path_concat_mode	string	False	replace	["replace", "prefix"]	Concatenation mode when path is specified. When set to replace, the configured path would be directly used as the path of the host to forward the mirrored traffic to. When set to prefix, the path to forward to would be the configured path, appended by the requested URI path of the Route. Not applicable if the Plugin is mirroring gRPC traffic.
sample_ratio	number	False	1	[0.00001, 1]	Ratio of the requests that will be mirrored. By default, all traffic are mirrored.

Static Configurations

By default, timeout values for the Plugin are pre-configured in the default configuration.

To customize these values, add the corresponding configurations to config.yaml. For example:

plugin_attr:
  proxy-mirror:
    timeout:
      connect: 60s
      read: 60s
      send: 60s

Reload APISIX for changes to take effect.

Examples

The examples below demonstrate how to configure proxy-mirror for different scenarios.

:::note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

:::

Mirror Partial Traffic

The following example demonstrates how you can configure proxy-mirror to mirror 50% of the traffic to a Route and forward them to another Upstream service.

Start a sample NGINX server for receiving mirrored traffic:

docker run -p 8081:80 --name nginx nginx

You should see NGINX access log and error log on the terminal session.

Open a new terminal session and create a Route with proxy-mirror to mirror 50% of the traffic:

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "traffic-mirror-route",
    "uri": "/get",
    "plugins": {
      "proxy-mirror": {
        "host": "http://127.0.0.1:8081",
        "sample_ratio": 0.5
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org": 1
      },
      "type": "roundrobin"
    }
  }'

Send Generate a few requests to the Route:

curl -i "http://127.0.0.1:9080/get"

You should receive HTTP/1.1 200 OK responses for all requests.

Navigating back to the NGINX terminal session, you should see a number of access log entries, roughly half the number of requests generated:

172.17.0.1 - - [29/Jan/2024:23:11:01 +0000] "GET /get HTTP/1.1" 404 153 "-" "curl/7.64.1" "-"

This suggests APISIX has mirrored the request to the NGINX server. Here, the HTTP response status is 404 since the sample NGINX server does not implement the Route.

Configure Mirroring Timeouts

The following example demonstrates how you can update the default connect, read, and send timeouts for the Plugin. This could be useful when mirroring traffic to a very slow backend service.

As the request mirroring was implemented as sub-requests, excessive delays in the sub-requests could lead to the blocking of the original requests. By default, the connect, read, and send timeouts are set to 60 seconds. To update these values, you can configure them in the plugin_attr section of the configuration file as such:

plugin_attr:
  proxy-mirror:
    timeout:
      connect: 2000ms
      read: 2000ms
      send: 2000ms

Reload APISIX for changes to take effect.