Skip to content

Commit 348e7c9

Browse files
sjbermansjberman
authored
Add NGF request mirror doc (#429)
NGF is adding the capability for users to configure request mirroring. This adds a guide explaining how a user can set this up.
1 parent 5f5bd4c commit 348e7c9

File tree

2 files changed

+218
-2
lines changed

2 files changed

+218
-2
lines changed

‎content/ngf/how-to/traffic-management/mirror.md

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
---
2+
title: Configure Request Mirroring
3+
weight: 700
4+
toc: true
5+
type: how-to
6+
product: NGF
7+
docs: DOCS-000
8+
---
9+
10+
Learn how to mirror your HTTP or gRPC traffic using NGINX Gateway Fabric.
11+
12+
---
13+
14+
## Overview
15+
16+
[HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) and [GRPCRoute](https://gateway-api.sigs.k8s.io/api-types/grpcroute/) filters can be used to configure request mirroring. Mirroring copies a request to another backend.
17+
18+
In this guide, we will set up two applications, **coffee** and **tea**, and mirror requests between them. All requests
19+
sent to the **coffee** application will also be sent to the **tea** application automatically.
20+
21+
---
22+
23+
## Before you begin
24+
25+
- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric.
26+
- Save the public IP address and port of NGINX Gateway Fabric into shell variables:
27+
28+
```text
29+
GW_IP=XXX.YYY.ZZZ.III
30+
GW_PORT=<port number>
31+
```
32+
33+
{{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}}
34+
35+
---
36+
37+
## Set up
38+
39+
Create the **coffee** and **tea** applications in Kubernetes by copying and pasting the following block into your terminal:
40+
41+
```yaml
42+
kubectl apply -f - <<EOF
43+
apiVersion: apps/v1
44+
kind: Deployment
45+
metadata:
46+
name: coffee
47+
spec:
48+
replicas: 1
49+
selector:
50+
matchLabels:
51+
app: coffee
52+
template:
53+
metadata:
54+
labels:
55+
app: coffee
56+
spec:
57+
containers:
58+
- name: coffee
59+
image: nginxdemos/nginx-hello:plain-text
60+
ports:
61+
- containerPort: 8080
62+
---
63+
apiVersion: v1
64+
kind: Service
65+
metadata:
66+
name: coffee
67+
spec:
68+
ports:
69+
- port: 80
70+
targetPort: 8080
71+
protocol: TCP
72+
name: http
73+
selector:
74+
app: coffee
75+
---
76+
apiVersion: apps/v1
77+
kind: Deployment
78+
metadata:
79+
name: tea
80+
spec:
81+
replicas: 1
82+
selector:
83+
matchLabels:
84+
app: tea
85+
template:
86+
metadata:
87+
labels:
88+
app: tea
89+
spec:
90+
containers:
91+
- name: tea
92+
image: nginxdemos/nginx-hello:plain-text
93+
ports:
94+
- containerPort: 8080
95+
---
96+
apiVersion: v1
97+
kind: Service
98+
metadata:
99+
name: tea
100+
spec:
101+
ports:
102+
- port: 80
103+
targetPort: 8080
104+
protocol: TCP
105+
name: http
106+
selector:
107+
app: tea
108+
EOF
109+
```
110+
111+
Run the following command to verify the resources were created:
112+
113+
```shell
114+
kubectl get pods,svc
115+
```
116+
117+
Your output should include the pods and services for **coffee** and **tea**:
118+
119+
```text
120+
NAME READY STATUS RESTARTS AGE
121+
pod/coffee-676c9f8944-dxvkt 0/1 ContainerCreating 0 3s
122+
pod/tea-6fbfdcb95d-xl22n 0/1 ContainerCreating 0 3s
123+
124+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
125+
service/coffee ClusterIP 10.96.151.184 <none> 80/TCP 3s
126+
service/tea ClusterIP 10.96.185.235 <none> 80/TCP 3s
127+
```
128+
129+
---
130+
131+
## Configure request mirroring
132+
133+
First, create the **cafe** Gateway resource:
134+
135+
```yaml
136+
kubectl apply -f - <<EOF
137+
apiVersion: gateway.networking.k8s.io/v1
138+
kind: Gateway
139+
metadata:
140+
name: cafe
141+
spec:
142+
gatewayClassName: nginx
143+
listeners:
144+
- name: http
145+
port: 80
146+
protocol: HTTP
147+
EOF
148+
```
149+
150+
Now create an HTTPRoute that defines a RequestMirror filter that copies all requests sent to `/coffee` to be sent to the **coffee** backend and mirrored to the **tea** backend. Use the following command:
151+
152+
```yaml
153+
kubectl apply -f - <<EOF
154+
apiVersion: gateway.networking.k8s.io/v1
155+
kind: HTTPRoute
156+
metadata:
157+
name: mirror
158+
spec:
159+
parentRefs:
160+
- name: cafe
161+
sectionName: http
162+
hostnames:
163+
- "cafe.example.com"
164+
rules:
165+
- matches:
166+
- path:
167+
type: PathPrefix
168+
value: /coffee
169+
filters:
170+
- type: RequestMirror
171+
requestMirror:
172+
backendRef:
173+
name: tea
174+
port: 80
175+
backendRefs:
176+
- name: coffee
177+
port: 80
178+
EOF
179+
```
180+
181+
Test the configuration:
182+
183+
You can send traffic using the external IP address and port saved earlier:
184+
185+
```shell
186+
curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee
187+
```
188+
189+
This request should receive a response from the `coffee` Pod:
190+
191+
```text
192+
Server address: 10.244.0.13:8080
193+
Server name: coffee-676c9f8944-dxvkt
194+
```
195+
196+
Now, check the logs of the **tea** application:
197+
198+
```shell
199+
kubectl logs deployments/tea
200+
```
201+
202+
You should see a log that looks similar to the following:
203+
204+
```text
205+
10.244.0.12 - - [17/Apr/2025:18:44:21 +0000] "GET /coffee HTTP/1.1" 200 158 "-" "curl/8.7.1" "127.0.0.1"
206+
```
207+
208+
This shows that the request to `/coffee` was mirrored to the **tea** application.
209+
210+
## See also
211+
212+
To learn more about request mirroring using the Gateway API, see the following resource:
213+
214+
- [Gateway API request mirroring](https://gateway-api.sigs.k8s.io/guides/http-request-mirroring/)

‎content/ngf/overview/gateway-api-compatibility.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,8 @@ See the [static-mode]({{< ref "/ngf/reference/cli-help.md#static-mode">}}) comma
178178
- `requestHeaderModifier`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest.
179179
- `urlRewrite`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest. Incompatible with `requestRedirect`.
180180
- `responseHeaderModifier`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest.
181-
- `requestMirror`, `extensionRef`: Not supported.
181+
- `requestMirror`: Supported. Multiple mirrors can be specified.
182+
- `extensionRef`: Supported for SnippetsFilters.
182183
- `backendRefs`: Partially supported. Backend ref `filters` are not supported.
183184
- `status`
184185
- `parents`
@@ -226,7 +227,8 @@ See the [static-mode]({{< ref "/ngf/reference/cli-help.md#static-mode">}}) comma
226227
- `type`: Supported.
227228
- `requestHeaderModifier`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest.
228229
- `responseHeaderModifier`: Supported. If multiple filters are configured, NGINX Gateway Fabric will choose the first and ignore the rest.
229-
- `requestMirror`, `extensionRef`: Not supported.
230+
- `requestMirror`: Supported. Multiple mirrors can be specified.
231+
- `extensionRef`: Supported for SnippetsFilters.
230232
- `backendRefs`: Partially supported. Backend ref `filters` are not supported.
231233
- `status`
232234
- `parents`

0 commit comments

Comments
 (0)