Skip to content

Commit 5205abf

Browse files
YilialinnYilialinn
authored
docs(ua-restriction): re-port with Admin API, ADC, and Ingress Controller tabs (#13260)
1 parent 095e8e4 commit 5205abf

2 files changed

Lines changed: 694 additions & 17 deletions

File tree

‎docs/en/latest/plugins/ua-restriction.md‎

Lines changed: 344 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -30,18 +30,21 @@ description: The ua-restriction Plugin restricts access to upstream resources us
3030
<link rel="canonical" href="https://docs.api7.ai/hub/ua-restriction" />
3131
</head>
3232

33+
import Tabs from '@theme/Tabs';
34+
import TabItem from '@theme/TabItem';
35+
3336
## Description
3437

3538
The `ua-restriction` Plugin supports restricting access to upstream resources through either configuring an allowlist or denylist of user agents. A common use case is to prevent web crawlers from overloading the upstream resources and causing service degradation.
3639

3740
## Attributes
3841

39-
| Name | Type | Required | Default | Valid values | Description |
40-
|----------------|---------------|----------|--------------|-------------------------|---------------------------------------------------------------------------------|
41-
| bypass_missing | boolean | False | false | | If true, bypass the user agent restriction check when the `User-Agent` header is missing. |
42-
| allowlist | array[string] | False | | | List of user agents to allow. Support regular expressions. At least one of the `allowlist` and `denylist` should be configured, but they cannot be configured at the same time. |
43-
| denylist | array[string] | False | | | List of user agents to deny. Support regular expressions. At least one of the `allowlist` and `denylist` should be configured, but they cannot be configured at the same time. |
44-
| message | string | False | "Not allowed" | | Message returned when the user agent is denied access. |
42+
| Name | Type | Required | Default | Valid values | Description |
43+
|----------------|---------------|----------|---------------|----------------|--------------------------------------------------------------------------------------------------------------------------------------|
44+
| bypass_missing | boolean | False | false | | If `true`, bypasses the UA restriction check when the `User-Agent` header is missing. |
45+
| allowlist | array[string] | False | | | List of allowed user agents (supports regex). Exactly one of `allowlist` or `denylist` must be configured. |
46+
| denylist | array[string] | False | | | List of denied user agents (supports regex). Exactly one of `allowlist` or `denylist` must be configured. |
47+
| message | string | False | "Not allowed" | [1, 1024] chars | Message returned to the client when the user agent is not allowed. |
4548

4649
## Examples
4750

@@ -61,6 +64,17 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/
6164

6265
The following example demonstrates how you can configure the Plugin to fend off unwanted web crawlers and customize the rejection message.
6366

67+
<Tabs
68+
groupId="api"
69+
defaultValue="admin-api"
70+
values={[
71+
{label: 'Admin API', value: 'admin-api'},
72+
{label: 'ADC', value: 'adc'},
73+
{label: 'Ingress Controller', value: 'aic'}
74+
]}>
75+
76+
<TabItem value="admin-api">
77+
6478
Create a Route and configure the Plugin to block specific crawlers from accessing resources with a customized message:
6579

6680
```shell
@@ -88,6 +102,164 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
88102
}'
89103
```
90104

105+
</TabItem>
106+
107+
<TabItem value="adc">
108+
109+
```yaml title="adc.yaml"
110+
services:
111+
- name: ua-restriction-service
112+
routes:
113+
- name: ua-restriction-route
114+
uris:
115+
- /anything
116+
plugins:
117+
ua-restriction:
118+
bypass_missing: false
119+
denylist:
120+
- "(Baiduspider)/(\\d+)\\.(\\d+)"
121+
- "bad-bot-1"
122+
message: "Access denied"
123+
upstream:
124+
type: roundrobin
125+
nodes:
126+
- host: httpbin.org
127+
port: 80
128+
weight: 1
129+
```
130+
131+
Synchronize the configuration to the gateway:
132+
133+
```shell
134+
adc sync -f adc.yaml
135+
```
136+
137+
</TabItem>
138+
139+
<TabItem value="aic">
140+
141+
<Tabs
142+
groupId="k8s-api"
143+
defaultValue="gateway-api"
144+
values={[
145+
{label: 'Gateway API', value: 'gateway-api'},
146+
{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
147+
]}>
148+
149+
<TabItem value="gateway-api">
150+
151+
```yaml title="ua-restriction-ic.yaml"
152+
apiVersion: v1
153+
kind: Service
154+
metadata:
155+
namespace: aic
156+
name: httpbin-external-domain
157+
spec:
158+
type: ExternalName
159+
ports:
160+
- port: 80
161+
externalName: httpbin.org
162+
---
163+
apiVersion: apisix.apache.org/v1alpha1
164+
kind: PluginConfig
165+
metadata:
166+
namespace: aic
167+
name: ua-restriction-plugin-config
168+
spec:
169+
plugins:
170+
- name: ua-restriction
171+
config:
172+
bypass_missing: false
173+
denylist:
174+
- "(Baiduspider)/(\\d+)\\.(\\d+)"
175+
- "bad-bot-1"
176+
message: "Access denied"
177+
---
178+
apiVersion: gateway.networking.k8s.io/v1
179+
kind: HTTPRoute
180+
metadata:
181+
namespace: aic
182+
name: ua-restriction-route
183+
spec:
184+
parentRefs:
185+
- name: apisix
186+
rules:
187+
- matches:
188+
- path:
189+
type: Exact
190+
value: /anything
191+
filters:
192+
- type: ExtensionRef
193+
extensionRef:
194+
group: apisix.apache.org
195+
kind: PluginConfig
196+
name: ua-restriction-plugin-config
197+
backendRefs:
198+
- name: httpbin-external-domain
199+
port: 80
200+
```
201+
202+
Apply the configuration to your cluster:
203+
204+
```shell
205+
kubectl apply -f ua-restriction-ic.yaml
206+
```
207+
208+
</TabItem>
209+
210+
<TabItem value="apisix-ingress-controller">
211+
212+
```yaml title="ua-restriction-ic.yaml"
213+
apiVersion: apisix.apache.org/v2
214+
kind: ApisixUpstream
215+
metadata:
216+
namespace: aic
217+
name: httpbin-external-domain
218+
spec:
219+
ingressClassName: apisix
220+
externalNodes:
221+
- type: Domain
222+
name: httpbin.org
223+
---
224+
apiVersion: apisix.apache.org/v2
225+
kind: ApisixRoute
226+
metadata:
227+
namespace: aic
228+
name: ua-restriction-route
229+
spec:
230+
ingressClassName: apisix
231+
http:
232+
- name: ua-restriction-route
233+
match:
234+
paths:
235+
- /anything
236+
upstreams:
237+
- name: httpbin-external-domain
238+
plugins:
239+
- name: ua-restriction
240+
enable: true
241+
config:
242+
bypass_missing: false
243+
denylist:
244+
- "(Baiduspider)/(\\d+)\\.(\\d+)"
245+
- "bad-bot-1"
246+
message: "Access denied"
247+
```
248+
249+
Apply the configuration to your cluster:
250+
251+
```shell
252+
kubectl apply -f ua-restriction-ic.yaml
253+
```
254+
255+
</TabItem>
256+
257+
</Tabs>
258+
259+
</TabItem>
260+
261+
</Tabs>
262+
91263
Send a request to the Route:
92264

93265
```shell
@@ -112,6 +284,17 @@ You should receive an `HTTP/1.1 403 Forbidden` response with the following messa
112284

113285
The following example demonstrates how to configure the Plugin to allow requests of a specific user agent to bypass the UA restriction.
114286

287+
<Tabs
288+
groupId="api"
289+
defaultValue="admin-api"
290+
values={[
291+
{label: 'Admin API', value: 'admin-api'},
292+
{label: 'ADC', value: 'adc'},
293+
{label: 'Ingress Controller', value: 'aic'}
294+
]}>
295+
296+
<TabItem value="admin-api">
297+
115298
Create a Route as such:
116299

117300
```shell
@@ -138,6 +321,161 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
138321
}'
139322
```
140323

324+
</TabItem>
325+
326+
<TabItem value="adc">
327+
328+
```yaml title="adc.yaml"
329+
services:
330+
- name: ua-restriction-service
331+
routes:
332+
- name: ua-restriction-route
333+
uris:
334+
- /anything
335+
plugins:
336+
ua-restriction:
337+
bypass_missing: true
338+
allowlist:
339+
- "good-bot-1"
340+
message: "Access denied"
341+
upstream:
342+
type: roundrobin
343+
nodes:
344+
- host: httpbin.org
345+
port: 80
346+
weight: 1
347+
```
348+
349+
Synchronize the configuration to the gateway:
350+
351+
```shell
352+
adc sync -f adc.yaml
353+
```
354+
355+
</TabItem>
356+
357+
<TabItem value="aic">
358+
359+
<Tabs
360+
groupId="k8s-api"
361+
defaultValue="gateway-api"
362+
values={[
363+
{label: 'Gateway API', value: 'gateway-api'},
364+
{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
365+
]}>
366+
367+
<TabItem value="gateway-api">
368+
369+
```yaml title="ua-restriction-ic.yaml"
370+
apiVersion: v1
371+
kind: Service
372+
metadata:
373+
namespace: aic
374+
name: httpbin-external-domain
375+
spec:
376+
type: ExternalName
377+
ports:
378+
- port: 80
379+
externalName: httpbin.org
380+
---
381+
apiVersion: apisix.apache.org/v1alpha1
382+
kind: PluginConfig
383+
metadata:
384+
namespace: aic
385+
name: ua-restriction-allowlist-plugin-config
386+
spec:
387+
plugins:
388+
- name: ua-restriction
389+
config:
390+
bypass_missing: true
391+
allowlist:
392+
- "good-bot-1"
393+
message: "Access denied"
394+
---
395+
apiVersion: gateway.networking.k8s.io/v1
396+
kind: HTTPRoute
397+
metadata:
398+
namespace: aic
399+
name: ua-restriction-route
400+
spec:
401+
parentRefs:
402+
- name: apisix
403+
rules:
404+
- matches:
405+
- path:
406+
type: Exact
407+
value: /anything
408+
filters:
409+
- type: ExtensionRef
410+
extensionRef:
411+
group: apisix.apache.org
412+
kind: PluginConfig
413+
name: ua-restriction-allowlist-plugin-config
414+
backendRefs:
415+
- name: httpbin-external-domain
416+
port: 80
417+
```
418+
419+
Apply the configuration to your cluster:
420+
421+
```shell
422+
kubectl apply -f ua-restriction-ic.yaml
423+
```
424+
425+
</TabItem>
426+
427+
<TabItem value="apisix-ingress-controller">
428+
429+
```yaml title="ua-restriction-ic.yaml"
430+
apiVersion: apisix.apache.org/v2
431+
kind: ApisixUpstream
432+
metadata:
433+
namespace: aic
434+
name: httpbin-external-domain
435+
spec:
436+
ingressClassName: apisix
437+
externalNodes:
438+
- type: Domain
439+
name: httpbin.org
440+
---
441+
apiVersion: apisix.apache.org/v2
442+
kind: ApisixRoute
443+
metadata:
444+
namespace: aic
445+
name: ua-restriction-route
446+
spec:
447+
ingressClassName: apisix
448+
http:
449+
- name: ua-restriction-route
450+
match:
451+
paths:
452+
- /anything
453+
upstreams:
454+
- name: httpbin-external-domain
455+
plugins:
456+
- name: ua-restriction
457+
enable: true
458+
config:
459+
bypass_missing: true
460+
allowlist:
461+
- "good-bot-1"
462+
message: "Access denied"
463+
```
464+
465+
Apply the configuration to your cluster:
466+
467+
```shell
468+
kubectl apply -f ua-restriction-ic.yaml
469+
```
470+
471+
</TabItem>
472+
473+
</Tabs>
474+
475+
</TabItem>
476+
477+
</Tabs>
478+
141479
Send a request to the Route without modifying the user agent:
142480

143481
```shell

0 commit comments

Comments
 (0)