This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 477d32820 docs: update "Traffic" Plugin docs 2 (#7050)
477d32820 is described below
commit 477d32820f27c33a376ab2ba9a1a48637e651096
Author: Navendu Pottekkat <[email protected]>
AuthorDate: Mon May 16 10:15:31 2022 +0530
docs: update "Traffic" Plugin docs 2 (#7050)
Signed-off-by: Navendu Pottekkat <[email protected]>
---
docs/en/latest/plugins/api-breaker.md | 63 ++++----
docs/en/latest/plugins/proxy-cache.md | 230 +++++++--------------------
docs/en/latest/plugins/proxy-mirror.md | 91 ++++++-----
docs/en/latest/plugins/request-validation.md | 126 ++++++++-------
4 files changed, 207 insertions(+), 303 deletions(-)
diff --git a/docs/en/latest/plugins/api-breaker.md
b/docs/en/latest/plugins/api-breaker.md
index 9f561c914..87c1f1d58 100644
--- a/docs/en/latest/plugins/api-breaker.md
+++ b/docs/en/latest/plugins/api-breaker.md
@@ -1,5 +1,11 @@
---
title: api-breaker
+keywords:
+ - APISIX
+ - Plugin
+ - API Breaker
+ - api-breaker
+description: This document contains information about the Apache APISIX
api-breaker Plugin.
---
<!--
@@ -23,40 +29,30 @@ title: api-breaker
## Description
-The plugin implements API fuse functionality to help us protect our upstream
business services.
+The `api-breaker` Plugin implements circuit breaker functionality to protect
Upstream services.
-> About the breaker timeout logic
+Whenever the Upstream service responds with a status code from the configured
`unhealthy.http_statuses` list for the configured `unhealthy.failures` number
of times, the Upstream service will be considered unhealthy.
-the code logic automatically **triggers the unhealthy state** incrementation
of the number of operations.
+The request is then retried in 2, 4, 8, 16 ... seconds until the
`max_breaker_sec`.
-Whenever the upstream service returns a status code from the
`unhealthy.http_statuses` configuration (e.g., 500), up to `unhealthy.failures`
(e.g., three times) and considers the upstream service to be in an unhealthy
state.
-
-The first time unhealthy status is triggered, **broken for 2 seconds**.
-
-Then, the request is forwarded to the upstream service again after 2 seconds,
and if the `unhealthy.http_statuses` status code is returned, and the count
reaches `unhealthy.failures` again, **broken for 4 seconds**.
-
-and so on, 2, 4, 8, 16, 32, 64, ..., 256, 300. `300` is the maximum value of
`max_breaker_sec`, allow users to specify.
-
-In an unhealthy state, when a request is forwarded to an upstream service and
the status code in the `healthy.http_statuses` configuration is returned (e.g.,
200) that `healthy.successes` is reached (e.g., three times), and the upstream
service is considered healthy again.
+In an unhealthy state, if the Upstream service responds with a status code
from the configured list `healthy.http_statuses` for `healthy.successes` times,
the service is considered healthy again.
## Attributes
-| Name | Type | Requirement | Default | Valid
| Description
|
-| ----------------------- | ------------- | ----------- | -------- |
--------------- |
--------------------------------------------------------------------------- |
-| break_response_code | integer | required | | [200,
..., 599] | Return error code when unhealthy |
-| break_response_body | string | optional | |
| Return response body when unhealthy |
-| break_response_headers | array[object] | optional | |
| New headers for the response. The values in the header can contain
Nginx variables like `$remote_addr` and `$balancer_ip`. This field is in
effective only if `break_response_body` is configured. |
-| max_breaker_sec | integer | optional | 300 | >=3
| Maximum breaker time(seconds) |
-| unhealthy.http_statuses | array[integer] | optional | {500} | [500,
..., 599] | Status codes when unhealthy |
-| unhealthy.failures | integer | optional | 3 | >=1
| Number of consecutive error requests that triggered an unhealthy state |
-| healthy.http_statuses | array[integer] | optional | {200} | [200,
..., 499] | Status codes when healthy |
-| healthy.successes | integer | optional | 3 | >=1
| Number of consecutive normal requests that trigger health status |
-
-## How To Enable
+| Name | Type | Required | Default | Valid values
| Description
|
+|-------------------------|----------------|----------|---------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| break_response_code | integer | True | | [200, ...,
599] | HTTP error code to return when Upstream is unhealthy.
|
+| break_response_body | string | False | |
| Body of the response message to return when Upstream is unhealthy.
|
+| break_response_headers | array[object] | False | |
| Headers of the response message to return when Upstream is unhealthy. Can
only be configured when the `break_response_body` attribute is configured. The
values can contain Nginx variables. For example, `$remote_addr` and
`$balancer_ip`. |
+| max_breaker_sec | integer | False | 300 | >=3
| Maximum time in seconds for circuit breaking.
|
+| unhealthy.http_statuses | array[integer] | False | [500] | [500, ...,
599] | Status codes of Upstream to be considered unhealthy.
|
+| unhealthy.failures | integer | False | 3 | >=1
| Number of consecutive failures for the Upstream service to be considered
unhealthy.
|
+| healthy.http_statuses | array[integer] | False | [200] | [200, ...,
499] | Status codes of Upstream to be considered healthy.
|
+| healthy.successes | integer | False | 3 | >=1
| Number of consecutive healthy requests for the Upstream service to be
considered healthy.
|
-Here's an example, enable the `api-breaker` plugin on the specified route.
+## Enabling the Plugin
-Response 500 or 503 three times in a row to trigger a unhealthy. Response 200
once in a row to restore healthy.
+The example below shows how you can configure the Plugin on a specific Route:
```shell
curl "http://127.0.0.1:9080/apisix/admin/routes/1"; -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -84,12 +80,17 @@ curl "http://127.0.0.1:9080/apisix/admin/routes/1"; -H
'X-API-KEY: edd1c9f034335f
}'
```
-## Test Plugin
+In this configuration, a response code of 500 or 503 three times in a row
triggers the unhealthy status of the Upstream service. A response code of 200
restores its healthy status.
-Then. Like the configuration above, if your upstream service returns 500. 3
times in a row. The client will receive a 502 (break_response_code) response.
+## Example usage
+
+Once you have configured the Plugin as shown above, you can test it out by
sending a request. If the Upstream service responds with an unhealthy response
code, you will receive the configured response code (`break_response_code`).
+
+```shell
+curl -i -X POST "http://127.0.0.1:9080/hello";
+```
```shell
-$ curl -i -X POST "http://127.0.0.1:9080/hello";
HTTP/1.1 502 Bad Gateway
Content-Type: application/octet-stream
Connection: keep-alive
@@ -100,7 +101,7 @@ Server: APISIX/1.5
## Disable Plugin
-When you want to disable the `api-breaker` plugin, it is very simple, you can
delete the corresponding json configuration in the plugin configuration, no
need to restart the service, it will take effect immediately:
+To disable the `api-breaker` Plugin, you can delete the corresponding JSON
configuration from the Plugin configuration. APISIX will automatically reload
and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -114,5 +115,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}
}'
```
-
-The `api-breaker` plugin has been disabled now. It works for other plugins.
diff --git a/docs/en/latest/plugins/proxy-cache.md
b/docs/en/latest/plugins/proxy-cache.md
index f1f449de1..a21d87089 100644
--- a/docs/en/latest/plugins/proxy-cache.md
+++ b/docs/en/latest/plugins/proxy-cache.md
@@ -1,7 +1,12 @@
---
title: proxy-cache
+keywords:
+ - APISIX
+ - Plugin
+ - Proxy Cache
+ - proxy-cache
+description: This document contains information about the Apache APISIX
proxy-cache Plugin.
---
-
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -23,135 +28,55 @@ title: proxy-cache
## Description
-The proxy-cache plugin, which provides the ability to cache upstream response
data and can be used with other plugins. The plugin supports disk-based caching
and will support the memory-based caching in the future. The data that needs to
be cached can be determined by the response code or request method and more
complex caching policies can be configured by no_cache and cache_bypass
attributes.
-
-*Note*:
+The `proxy-cache` Plugin can be used to cache the response from the Upstream.
It can be used with other Plugins and currently supports disk-based caching.
-1. The cache expiration time cannot be configured dynamically. The expiration
time can only be set by the upstream response header `Expires` or
`Cache-Control`, and the default cache expiration time is 10s if there is no
`Expires` or `Cache-Control` in the upstream response header
-2. If the upstream service is not available and APISIX will return 502 or 504,
then 502 or 504 will be cached for 10s.
+The data to be cached can be filtered with response codes, request modes, or
more complex methods using the `no_cache` and `cache_bypass` attributes.
## Attributes
-| Name | Type | Requirement | Default
| Valid
| Description
|
-| ------------------ | -------------- | ----------- |
------------------------- |
-------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
-| cache_strategy | string | optional | disk
| ["disk","memory"]
| Cache strategy. Specify where the cache data is stored (memory or disk) |
-| cache_zone | string | optional | disk_cache_one
|
| Specify which cache area to use, each cache area can be configured with
different paths. In addition, cache areas can be predefined in conf/config.yaml
file. When the default value is not used, the specified cache area is
inconsistent with the pre-defined cache area in the conf/config.yaml file, and
the cache is invalid. |
-| cache_key | array[string] | optional | ["$host",
"$request_uri"] |
| key of a cache, can use variables. For example: ["$host",
"$uri", "-cache-id"]
|
-| cache_bypass | array[string] | optional |
|
| Whether to skip cache retrieval. That is, do not look for data in the
cache. It can use variables, and note that cache data retrieval will be skipped
when the value of this attribute is not empty or not '0'. For example:
["$arg_bypass"] |
-| cache_method | array[string] | optional | ["GET", "HEAD"]
| ["GET", "POST", "HEAD"] | Decide whether to be cached according to the
request method
|
-| cache_http_status | array[integer] | optional | [200, 301, 404]
| [200, 599]
| Decide whether to be cached according to the upstream response status
|
-| hide_cache_headers | boolean | optional | false
|
| Whether to return the Expires and Cache-Control response headers to the
client,
|
-| cache_control | boolean | optional | false
|
| Whether to comply with the cache-control behavior in the HTTP
specification. Only for memory strategy. |
-| no_cache | array[string] | optional |
|
| Whether to cache data, it can use variables, and note that the data will
not be cached when the value of this attribute is not empty or not '0'.
|
-| cache_ttl | integer | optional | 300 seconds
|
| The default cache time. when the cache_control option is not enabled or
the proxied server does not return cache header (cache-contorl or expires), it
will be take effect. Only for memory strategy. |
-
-Note:
-
-1. The variable starts with $.
-2. The attribute can use a combination of the variable and the string, but it
needs to be written separately as an array, and the final values are stitched
together after the variable is parsed.
-
-Example configuration in the `conf/config.yaml` file:
-
-```yaml
-proxy_cache: # Proxy Caching configuration
- cache_ttl: 10s # The default caching time if the upstream
does not specify the cache time
- zones: # The parameters of a cache
- - name: disk_cache_one # The name of the cache, administrator can
be specify
- # which cache to use by name in the admin
api
- memory_size: 50m # The size of shared memory, it's used to
store the cache index
- disk_size: 1G # The size of disk, it's used to store the
cache data
- disk_path: "/tmp/disk_cache_one" # The path to store the cache data
- cache_levels: "1:2" # The hierarchy levels of a cache
-```
-
-### Examples
+| Name | Type | Required | Default |
Valid values | Description
|
+|--------------------|----------------|----------|---------------------------|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| cache_strategy | string | False | disk |
["disk","memory"] | Specifies where the cached data should be stored.
|
+| cache_zone | string | False | disk_cache_one |
| Specifies which cache area to use. Each cache area
can be configured with different paths. Cache areas can be predefined in your
configuration file (conf/config.yaml). If the specified cache area is
inconsistent with the pre-defined cache area in your configuration file, the
cache is invalid. |
+| cache_key | array[string] | False | ["$host", "$request_uri"] |
| Key to use for caching. For example, `["$host",
"$uri", "-cache-id"]`.
|
+| cache_bypass | array[string] | False | |
| Conditions in which response from cache is bypassed.
Whether to skip cache retrieval. If at least one value of the string parameters
is not empty and is not equal to “0” then the response will not be taken from
the cache. For example, `["$arg_bypass"]`.
|
+| cache_method | array[string] | False | ["GET", "HEAD"] |
["GET", "POST", "HEAD"] | Request methods for which the response will be
cached.
|
+| cache_http_status | array[integer] | False | [200, 301, 404] |
[200, 599] | HTTP status codes of the Upstream response for which
the response will be cached.
|
+| hide_cache_headers | boolean | False | false |
| When set to true adds the `Expires` and
`Cache-Control` headers to the client response.
|
+| cache_control | boolean | False | false |
| When set to true, complies with Cache-Control
behavior in the HTTP specification. Used only for memory strategy.
|
+| no_cache | array[string] | False | |
| Conditions in which the response will not be cached.
If at least one value of the string parameters is not empty and is not equal to
“0” then the response will not be saved.
|
+| cache_ttl | integer | False | 300 seconds |
| Time that a response is cached until it is deleted or
refreshed. Comes in to effect when the `cache_control` attribute is not enabled
or the proxied server does not return cache header. Used only for memory
strategy.
|
-#### Enable the plugin
+:::note
-Example 1: The cache_zone parameter defaults to `disk_cache_one`
+The cache expiration time cannot be configured dynamically. It can only be set
by the Upstream response header `Expires` or `Cache-Control`. The default
expiration time is 10s if there is no `Expires` or `Cache-Control` in the
Upstream response header.
-1: enable the proxy-cache plugin for a specific route :
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "plugins": {
- "proxy-cache": {
- "cache_key": ["$uri", "-cache-id"],
- "cache_bypass": ["$arg_bypass"],
- "cache_method": ["GET"],
- "cache_http_status": [200],
- "hide_cache_headers": true,
- "no_cache": ["$arg_test"]
- }
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1999": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
-```
-
-Test Plugin:
-
-```shell
-$ curl http://127.0.0.1:9080/hello -i
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Content-Length: 6
-Connection: keep-alive
-Server: APISIX web server
-Date: Tue, 03 Mar 2020 10:45:36 GMT
-Last-Modified: Tue, 03 Mar 2020 10:36:38 GMT
-Apisix-Cache-Status: MISS
-
-hello
-```
-
-> http status is '200' and the response header contains 'Apisix-Cache-Status'
to indicate that the plugin is enabled.
-
-2: Verify that the data is cached, request the address above again:
-
-```shell
-$ curl http://127.0.0.1:9080/hello -i
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Content-Length: 6
-Connection: keep-alive
-Server: APISIX web server
-Date: Tue, 03 Mar 2020 11:14:46 GMT
-Last-Modified: Thu, 20 Feb 2020 14:21:41 GMT
-Apisix-Cache-Status: HIT
+If the Upstream service is not available and APISIX returns a 502 or 504
status code, it will be cached for 10s.
-hello
-```
+:::
-Example 2: Customize the cache_zone parameter to `disk_cache_two`
+## Enabling the Plugin
-1. Specify the cache area and other information in the `conf/config.yaml` file:
+You can add your cache configuration in you APISIX configuration file
(`conf/config.yaml`) as shown below:
-```yaml
+```yaml title="conf/config.yaml"
proxy_cache:
- cache_ttl: 10s
+ cache_ttl: 10s # default caching time if the upstream
doesn't specify the caching time
zones:
- - name: disk_cache_two
- memory_size: 50m
- disk_size: 1G
- disk_path: "/tmp/disk_cache_one"
- cache_levels: "1:2"
+ - name: disk_cache_one # name of the cache. Admin can specify
which cache to use in the Admin API by name
+ memory_size: 50m # size of shared memory, used to store the
cache index
+ disk_size: 1G # size of disk, used to store the cache data
+ disk_path: "/tmp/disk_cache_one" # path to store the cache data
+ cache_levels: "1:2" # hierarchy levels of the cache
```
-2. Enable the `proxy-cache` plugin for a specific route:
+You can enable the Plugin on a specific Route as shown below:
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"proxy-cache": {
- "cache_zone": "disk_cache_two",
"cache_key": ["$uri", "-cache-id"],
"cache_bypass": ["$arg_bypass"],
"cache_method": ["GET"],
@@ -170,10 +95,17 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335
}'
```
-Test Plugin:
+In the above configuration, the `cache_zone` attribute defaults to
`disk_cache_one`.
+
+## Example usage
+
+Once you have configured the Plugin as shown above, you can make an initial
request:
+
+```shell
+curl http://127.0.0.1:9080/hello -i
+```
```shell
-$ curl http://127.0.0.1:9080/hello -i
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 6
@@ -186,12 +118,13 @@ Apisix-Cache-Status: MISS
hello
```
-> http status is '200' and the response header contains 'Apisix-Cache-Status'
to indicate that the plug-in is enabled.
+The `Apisix-Cache-Status` in the response shows `MISS` meaning that the
response is not cached, as expected. Now, if you make another request, you will
see that you get a cached response:
-3. Verify that the data is cached and request the above address again:
+```shell
+curl http://127.0.0.1:9080/hello -i
+```
```shell
-$ curl http://127.0.0.1:9080/hello -i
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 6
@@ -204,48 +137,17 @@ Apisix-Cache-Status: HIT
hello
```
-> The response header `Apisix-Cache-Status` value has changed to HIT,
indicating that the data has been cached
+If you set `"cache_zone": "invalid_disk_cache"` attribute to an invalid value
(cache not configured in the your configuration file), then it will return a
404 response.
-Example 3: Specifying cache_zone as `invalid_disk_cache` is inconsistent with
the cache area `disk_cache_one` specified in the `conf/config.yaml` file.
+:::tip
-```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "plugins": {
- "proxy-cache": {
- "cache_zone": "invalid_disk_cache",
- "cache_key": ["$uri", "-cache-id"],
- "cache_bypass": ["$arg_bypass"],
- "cache_method": ["GET"],
- "cache_http_status": [200],
- "hide_cache_headers": true,
- "no_cache": ["$arg_test"]
- }
- },
- "upstream": {
- "nodes": {
- "127.0.0.1:1999": 1
- },
- "type": "roundrobin"
- },
- "uri": "/hello"
-}'
-```
+To clear the cached data, you can send a request with PURGE method:
-```json
-{"error_msg":"failed to check the configuration of plugin proxy-cache err:
cache_zone invalid_disk_cache not found"}
+```shell
+curl -i http://127.0.0.1:9080/hello -X PURGE
```
-In response to an error message, the plug-in configuration is invalid.
-
-#### Clear cached data
-
-How to clean the cached data only needs to specify the requested method as
PURGE.
-
-Test Plugin:
-
```shell
-$ curl -i http://127.0.0.1:9080/hello -X PURGE
HTTP/1.1 200 OK
Date: Tue, 03 Mar 2020 11:17:35 GMT
Content-Type: text/plain
@@ -254,31 +156,13 @@ Connection: keep-alive
Server: APISIX web server
```
-> If the response code is 200, it means the deletion is successful. If the
cached data is not found, 404 will be returned.
-
-Request again, the cached data is not found and return 404:
-
-```shell
-$ curl -i http://127.0.0.1:9080/hello -X PURGE
-HTTP/1.1 404 Not Found
-Date: Wed, 18 Nov 2020 05:46:34 GMT
-Content-Type: text/plain
-Transfer-Encoding: chunked
-Connection: keep-alive
-Server: APISIX web server
+If the response code is 200, the deletion is successful. If the cached data is
not found, a 404 response code will be returned.
-<html>
-<head><title>404 Not Found</title></head>
-<body>
-<center><h1>404 Not Found</h1></center>
-<hr><center>openresty</center>
-</body>
-</html>
-```
+:::
## Disable Plugin
-Remove the corresponding JSON in the plugin configuration to disable the
plugin immediately without restarting the service:
+To disable the `proxy-cache` Plugin, you can delete the corresponding JSON
configuration from the Plugin configuration. APISIX will automatically reload
and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -293,5 +177,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f1
}
}'
```
-
-The plugin has been disabled now.
diff --git a/docs/en/latest/plugins/proxy-mirror.md
b/docs/en/latest/plugins/proxy-mirror.md
index 5b8d8b4ef..2b127ffef 100644
--- a/docs/en/latest/plugins/proxy-mirror.md
+++ b/docs/en/latest/plugins/proxy-mirror.md
@@ -1,7 +1,12 @@
---
title: proxy-mirror
+keywords:
+ - APISIX
+ - Plugin
+ - Proxy Mirror
+ - proxy-mirror
+description: This document contains information about the Apache APISIX
proxy-mirror Plugin.
---
-
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -23,23 +28,42 @@ title: proxy-mirror
## Description
-The proxy-mirror plugin, which provides the ability to mirror client requests.
+The `proxy-mirror` Plugin can be used to mirror client requests.
+
+:::note
+
+The response returned by the mirror request is ignored.
-*Note*: The response returned by the mirror request is ignored.
+:::
## Attributes
-| Name | Type | Requirement | Default | Valid | Description
|
-| ---- | ------ | ----------- | ------- | ----- |
---------------------------------------------------------------------------------------------------------------------------
|
-| host | string | required | | | Specify a mirror service
address, e.g. http://127.0.0.1:9797 (address needs to contain scheme: http or
https, and without the path part) |
-| path | string | optional | | | Specify the mirror request's
path part. Without it the current path will be used. |
-| sample_ratio | number | optional | 1 | [0.00001, 1] | the
sample ratio that requests will be mirrored. |
+| Name | Type | Required | Default | Valid values | Description
|
+|--------------|--------|----------|---------|--------------|---------------------------------------------------------------------------------------------------------------------------|
+| host | string | True | | | Address of the
mirror service. It needs to contain the scheme but without the path. For
example, `http://127.0.0.1:9797`. |
+| path | string | False | | | Path of the
mirror request. If unspecified, current path will be used.
|
+| sample_ratio | number | False | 1 | [0.00001, 1] | Ratio of the
requests that will be mirrored.
|
-### Examples
+You can customize the proxy timeouts for the mirrored sub-requests by
configuring the `plugin_attr` key in your configuration file
(`conf/config.yaml`). This can be used for mirroring traffic to a slow backend.
-#### Enable the plugin
+```yaml title="conf/config.yaml"
+plugin_attr:
+ proxy-mirror:
+ timeout:
+ connect: 2000ms
+ read: 2000ms
+ send: 2000ms
+```
+
+| Name | Type | Default | Description |
+|---------|--------|---------|-------------------------------------------|
+| connect | string | 60s | Connect timeout to the mirrored Upstream. |
+| read | string | 60s | Read timeout to the mirrored Upstream. |
+| send | string | 60s | Send timeout to the mirrored Upstream. |
-example 1: enable the proxy-mirror plugin for a specific route :
+## Enabling the Plugin
+
+You can enable the Plugin on a specific Route as shown below:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -59,10 +83,15 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f1
}'
```
-Test plugin：
+## Example usage
+
+Once you have configured the Plugin as shown above, the requests made will be
mirrored to the configured host.
+
+```shell
+curl http://127.0.0.1:9080/hello -i
+```
```shell
-$ curl http://127.0.0.1:9080/hello -i
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 12
@@ -74,12 +103,19 @@ Last-Modified: Thu, 20 Feb 2020 14:21:41 GMT
hello world
```
-> Since the specified mirror address is 127.0.0.1:9797, so to verify whether
this plugin is in effect, we need to confirm on the service with port 9797.
-> For example, we can start a simple server: python -m SimpleHTTPServer 9797
+:::tip
-#### Disable Plugin
+For testing you can create a test server by running:
-Remove the corresponding JSON in the plugin configuration to disable the
plugin immediately without restarting the service:
+```shell
+python -m http.server 9797
+```
+
+:::
+
+## Disable Plugin
+
+To disable the `proxy-mirror` Plugin, you can delete the corresponding JSON
configuration from the Plugin configuration. APISIX will automatically reload
and you do not have to restart for this to take effect.
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -94,24 +130,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f1
}
}'
```
-
-The plugin has been disabled now.
-
-## Customize proxy timeouts for mirrored sub-request
-
-We can customize proxy timeouts for the mirrored sub-request in the
`plugin_attr` of `conf/config.yaml`. This is useful while mirroring traffic to
a slow backend in a long connection scenario.
-
-| Name | Type | Default | Description |
-| --- | --- | --- | --- |
-| connect | string | 60s | connect timeout to the mirrored upstream |
-| read | string | 60s | read timeout to the mirrored upstream |
-| send | string | 60s | send timeout to the mirrored upstream |
-
-```yaml
-plugin_attr:
- proxy-mirror:
- timeout:
- connect: 2000ms
- read: 2000ms
- send: 2000ms
-```
diff --git a/docs/en/latest/plugins/request-validation.md
b/docs/en/latest/plugins/request-validation.md
index 3c3770c53..5ad7b8421 100644
--- a/docs/en/latest/plugins/request-validation.md
+++ b/docs/en/latest/plugins/request-validation.md
@@ -1,5 +1,11 @@
---
title: request-validation
+keywords:
+ - APISIX
+ - Plugin
+ - Request Validation
+ - proxy-cache
+description: This document contains information about the Apache APISIX
request-validation Plugin.
---
<!--
@@ -23,25 +29,26 @@ title: request-validation
## Description
-`request-validation` plugin validates the requests before forwarding to an
upstream service. The validation plugin uses
-json-schema to validate the schema. The plugin can be used to validate the
headers and body data.
-
-For more information on schema, refer to [JSON
schema](https://github.com/api7/jsonschema) for more information.
+The `request-validation` Plugin can be used to validate the requests before
forwarding them to an Upstream service. This Plugin uses [JSON
Schema](https://github.com/api7/jsonschema) for validation and can be used to
validate the headers and body of the request.
## Attributes
-> Note that at least one of `header_schema` and `body_schema` must be filled
in.
+| Name | Type | Required | Default | Valid values | Description
|
+|---------------|---------|----------|---------|---------------|---------------------------------------------------|
+| header_schema | object | False | | | Schema for
the request header data. |
+| body_schema | object | False | | | Schema for
the request body data. |
+| rejected_code | integer | False | 400 | [200,...,599] | Status code
to show when the request is rejected. |
+| rejected_msg | string | False | | | Message to
show when the request is rejected. |
+
+:::note
-| Name | Type | Requirement | Default | Valid | Description
|
-| ---------------- | ------ | ----------- | ------- | ----- |
-------------------------- |
-| header_schema | object | optional | | | schema for the
header data |
-| body_schema | object | optional | | | schema for the
body data |
-| rejected_code | integer | optional | 400 | [200,...,599] |
the custom rejected code |
-| rejected_msg | string | optional | | | the custom rejected
message |
+At least one of `header_schema` or `body_schema` should be filled in.
-## How To Enable
+:::
-Create a route and enable the request-validation plugin on the route:
+## Enabling the Plugin
+
+You can configure the Plugin on a specific Route as shown below:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -55,41 +62,10 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
"properties": {
"required_payload": {"type": "string"},
"boolean_payload": {"type": "boolean"}
- }
- },
- "rejected_msg": "customize reject message"
- }
- },
- "upstream": {
- "type": "roundrobin",
- "nodes": {
- "127.0.0.1:8080": 1
+ },
+ "rejected_msg": "customize reject message"
+ }
}
- }
-}'
-```
-
-## Test Plugin
-
-```shell
-curl --header "Content-Type: application/json" \
- --request POST \
- --data '{"boolean-payload":true,"required_payload":"hello"}' \
- http://127.0.0.1:9080/get
-```
-
-If the schema is violated the plugin will yield a `400` bad request with the
reject response.
-
-## Disable Plugin
-
-Remove the corresponding json configuration in the plugin configuration to
disable the `request-validation`.
-APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "uri": "/get",
- "plugins": {
},
"upstream": {
"type": "roundrobin",
@@ -100,9 +76,9 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-## Examples:
+The examples below shows how you can configure this Plugin for different
validation scenarios:
-**`Enum` validate:**
+Enum validation:
```json
{
@@ -120,7 +96,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}
```
-**`Boolean` validate:**
+Boolean validation:
```json
{
@@ -137,7 +113,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}
```
-**`Number` or `Integer` validate:**
+Number or Integer validation:
```json
{
@@ -155,7 +131,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}
```
-**`String` validate:**
+String validation:
```json
{
@@ -173,7 +149,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}
```
-**`Regex` validate:**
+Regular expression validation:
```json
{
@@ -192,7 +168,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}
```
-**`Array` validate:**
+Array validation:
```json
{
@@ -216,7 +192,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}
```
-**Multi-field combination verification:**
+Combined validation:
```json
{
@@ -249,7 +225,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}
```
-**Custom rejected message:**
+Custom rejection message:
```json
{
@@ -262,9 +238,9 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
"properties": {
"required_payload": {"type": "string"},
"boolean_payload": {"type": "boolean"}
- }
- },
- "rejected_msg": "customize reject message"
+ },
+ "rejected_msg": "customize reject message"
+ }
}
},
"upstream": {
@@ -275,3 +251,35 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H
'X-API-KEY: edd1c9f034335f13
}
}
```
+
+## Example usage
+
+Once you have configured the Plugin, it will only allow requests that are
valid based on the configuration to reach the Upstream service. If not, the
requests are rejected with a 400 or a custom status code you configured.
+
+A valid request for the above configuration could look like this:
+
+```shell
+curl --header "Content-Type: application/json" \
+ --request POST \
+ --data '{"boolean-payload":true,"required_payload":"hello"}' \
+ http://127.0.0.1:9080/get
+```
+
+## Disable Plugin
+
+To disable the `request-validation` Plugin, you can delete the corresponding
JSON configuration from the Plugin configuration. APISIX will automatically
reload and you do not have to restart for this to take effect.
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/get",
+ "plugins": {
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:8080": 1
+ }
+ }
+}'
+```
