Skip to content

docs: add ADC and Ingress Controller tabs to proxy-mirror plugin docs #13218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Yilialinn merged 1 commit into from
Apr 17, 2026
+321 −3
Merged

docs: add ADC and Ingress Controller tabs to proxy-mirror plugin docs #13218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 161 additions & 2 deletions docs/en/latest/plugins/proxy-mirror.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ description: The proxy-mirror Plugin duplicates ingress traffic to APISIX and fo
<link rel="canonical" href="https://docs.api7.ai/hub/proxy-mirror" />
</head>

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## 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.
Expand Down Expand Up @@ -88,7 +91,18 @@ 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:
Open a new terminal session and create a Route with `proxy-mirror`:

<Tabs
groupId="api"
defaultValue="admin-api"
values={[
{label: 'Admin API', value: 'admin-api'},
{label: 'ADC', value: 'adc'},
{label: 'Ingress Controller', value: 'aic'}
]}>

<TabItem value="admin-api">

```shell
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
Expand All @@ -111,7 +125,152 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
}'
```

Send Generate a few requests to the Route:
</TabItem>

<TabItem value="adc">

```yaml title="adc.yaml"
services:
- name: proxy-mirror-service
routes:
- name: traffic-mirror-route
uris:
- /get
plugins:
proxy-mirror:
host: "http://127.0.0.1:8081"
sample_ratio: 0.5
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
```

Synchronize the configuration to the gateway:

```shell
adc sync -f adc.yaml
```

</TabItem>

<TabItem value="aic">

<Tabs
groupId="k8s-api"
defaultValue="gateway-api"
values={[
{label: 'Gateway API', value: 'gateway-api'},
{label: 'APISIX CRD', value: 'apisix-crd'}
]}>

<TabItem value="gateway-api">

```yaml title="proxy-mirror-ic.yaml"
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: proxy-mirror-plugin-config
spec:
plugins:
- name: proxy-mirror
config:
host: "http://nginx.aic.svc"
sample_ratio: 0.5
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: traffic-mirror-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /get
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: proxy-mirror-plugin-config
backendRefs:
- name: httpbin-external-domain
port: 80
```

</TabItem>

<TabItem value="apisix-crd">

```yaml title="proxy-mirror-ic.yaml"
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: httpbin-external-domain
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: traffic-mirror-route
spec:
ingressClassName: apisix
http:
- name: traffic-mirror-route
match:
paths:
- /get
upstreams:
- name: httpbin-external-domain
plugins:
- name: proxy-mirror
enable: true
config:
host: "http://nginx.aic.svc"
sample_ratio: 0.5
```

</TabItem>

</Tabs>

Apply the configuration to your cluster:

```shell
kubectl apply -f proxy-mirror-ic.yaml
```

</TabItem>

</Tabs>

❶ `host`: configure the scheme and host address to forward the mirrored traffic to.

❷ `sample_ratio`: configure the sampling ratio to 0.5 to mirror 50% of the traffic.

Send a few requests to the Route:

```shell
curl -i "http://127.0.0.1:9080/get"
Expand Down
161 changes: 160 additions & 1 deletion docs/zh/latest/plugins/proxy-mirror.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,9 @@ description: proxy-mirror 插件将入口流量复制到 APISIX 并将其转发
<link rel="canonical" href="https://docs.api7.ai/hub/proxy-mirror" />
</head>

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## 描述

`proxy-mirror` 插件将传入流量复制到 APISIX 并将其转发到指定的上游，而不会中断常规服务。您可以将插件配置为镜像所有流量或仅镜像一部分流量。该机制有利于一些用例，包括故障排除、安全检查、分析等。
Expand Down Expand Up @@ -88,7 +91,18 @@ docker run -p 8081:80 --name nginx nginx

您应该在终端会话中看到 NGINX 访问日志和错误日志。

打开一个新的终端会话并使用 `proxy-mirror` 创建一个路由来镜像 50% 的流量：
打开一个新的终端会话并使用 `proxy-mirror` 创建路由：

<Tabs
groupId="api"
defaultValue="admin-api"
values={[
{label: 'Admin API', value: 'admin-api'},
{label: 'ADC', value: 'adc'},
{label: 'Ingress Controller', value: 'aic'}
]}>

<TabItem value="admin-api">

```shell
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
Expand All @@ -111,6 +125,151 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
}'
```

</TabItem>

<TabItem value="adc">

```yaml title="adc.yaml"
services:
- name: proxy-mirror-service
routes:
- name: traffic-mirror-route
uris:
- /get
plugins:
proxy-mirror:
host: "http://127.0.0.1:8081"
sample_ratio: 0.5
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
```

将配置同步到网关：

```shell
adc sync -f adc.yaml
```

</TabItem>

<TabItem value="aic">

<Tabs
groupId="k8s-api"
defaultValue="gateway-api"
values={[
{label: 'Gateway API', value: 'gateway-api'},
{label: 'APISIX CRD', value: 'apisix-crd'}
]}>

<TabItem value="gateway-api">

```yaml title="proxy-mirror-ic.yaml"
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: proxy-mirror-plugin-config
spec:
plugins:
- name: proxy-mirror
config:
host: "http://nginx.aic.svc"
sample_ratio: 0.5
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: traffic-mirror-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /get
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: proxy-mirror-plugin-config
backendRefs:
- name: httpbin-external-domain
port: 80
```

</TabItem>

<TabItem value="apisix-crd">

```yaml title="proxy-mirror-ic.yaml"
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: httpbin-external-domain
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: traffic-mirror-route
spec:
ingressClassName: apisix
http:
- name: traffic-mirror-route
match:
paths:
- /get
upstreams:
- name: httpbin-external-domain
plugins:
- name: proxy-mirror
enable: true
config:
host: "http://nginx.aic.svc"
sample_ratio: 0.5
```

</TabItem>

</Tabs>

将配置应用到集群：

```shell
kubectl apply -f proxy-mirror-ic.yaml
```

</TabItem>

</Tabs>

❶ `host`：配置将镜像流量转发到的方案和主机地址。

❷ `sample_ratio`：将采样比率配置为 0.5，以镜像 50% 的流量。

发送生成几个请求到路由：

```shell
Expand Down
Loading