Skip to content
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

Jump to bottom

docs: update "Traffic" Plugin docs 3 #7064

Merged
merged 7 commits into from
May 20, 2022
Merged

docs: update "Traffic" Plugin docs 3 #7064

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b281535
docs: update "Traffic" Plugin docs 3
pottekkat May 17, 2022
63540f0
Merge branch 'master' into docs/plugin-traffic-3/6734
pottekkat May 17, 2022
f960ab0
fix lint errors
pottekkat May 17, 2022
07d88d5
Merge branch 'docs/plugin-traffic-3/6734' of https://github.com/naven…
pottekkat May 17, 2022
94f35d9
fix lint error
pottekkat May 18, 2022
2d14a5f
apply suggestions from review
pottekkat May 18, 2022
6321221
apply suggestion from the review
pottekkat May 20, 2022
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
37 changes: 22 additions & 15 deletions docs/en/latest/plugins/client-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
---
title: client-control
keywords:
- APISIX
- Plugin
- Client Control
- client-control
description: This document contains information about the Apache APISIX client-control Plugin.
---

<!--
Expand All @@ -23,20 +29,23 @@ title: client-control

## Description

The `client-control` plugin dynamically controls the behavior of Nginx to
handle the client request.
The `client-control` Plugin can be used to dynamically control the behavior of Nginx to handle a client request.

**This plugin requires APISIX to run on [APISIX-Base](../FAQ.md#how-do-i-build-the-apisix-base-environment?).**
:::info IMPORTANT

This Plugin requires APISIX to run on APISIX-Base. See [apisix-build-tools](https://github.com/api7/apisix-build-tools) for more info.

:::

## Attributes

| Name | Type | Requirement | Default | Valid | Description |
| --------- | ------------- | ----------- | ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| max_body_size | integer | optional | | >= 0 | dynamically set the `client_max_body_size` directive |
| Name | Type | Required | Valid values | Description |
| ------------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| max_body_size | integer | False | >= 0 | Dynamically set the [client_max_body_size](https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) directive. |
yzeng25 marked this conversation as resolved.
Show resolved Hide resolved

## How To Enable
## Enabling the Plugin

Here's an example, enable this plugin on the specified route:
The example below enables the Plugin on a specific Route:

```shell
curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
Expand All @@ -56,13 +65,15 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f03433
}'
```

## Test Plugin
## Example usage

Use curl to access:
Now since you have configured the `max_body_size` to `1` above, you will get the following message when you make a request:

```shell
curl -i http://127.0.0.1:9080/index.html -d '123'
```

```shell
HTTP/1.1 413 Request Entity Too Large
...
<html>
Expand All @@ -76,9 +87,7 @@ HTTP/1.1 413 Request Entity Too Large

## Disable Plugin

When you want to disable this 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 `client-control` 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.
yzeng25 marked this conversation as resolved.
Show resolved Hide resolved

```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
Expand All @@ -92,5 +101,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}
}'
```

This plugin has been disabled now. It works for other plugins.
36 changes: 21 additions & 15 deletions docs/en/latest/plugins/proxy-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
---
title: proxy-control
keywords:
- APISIX
- Plugin
- Proxy Control
- proxy-control
description: This document contains information about the Apache APISIX proxy-control Plugin.
---

<!--
Expand All @@ -23,19 +29,23 @@ title: proxy-control

## Description

The `proxy-control` plugin dynamically controls the behavior of Nginx to proxy.
The proxy-control Plugin dynamically controls the behavior of the Nginx proxy.
Copy link
Contributor

@guitu168 guitu168 May 17, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The proxy-control Plugin dynamically controls the behavior of the Nginx proxy.
The proxy-control Plugin dynamically controls the behavior of the NGINX proxy.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I found on the NGINX official website, it should be NGINX.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess we started using Nginx and kept using it. We might need to change this everywhere if this is desired.


**This plugin requires APISIX to run on [APISIX-Base](../FAQ.md#how-do-i-build-the-apisix-base-environment?).**
:::info IMPORTANT

This Plugin requires APISIX to run on APISIX-Base. See [apisix-build-tools](https://github.com/api7/apisix-build-tools) for more info.

:::

## Attributes

| Name | Type | Requirement | Default | Valid | Description |
| --------- | ------------- | ----------- | ---------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| request_buffering | boolean | optional | true | | dynamically set the `proxy_request_buffering` directive |
| Name | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| request_buffering | boolean | False | true | When set to true, dynamically sets the [proxy_request_buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_request_buffering) directive. |
yzeng25 marked this conversation as resolved.
Show resolved Hide resolved

## How To Enable
## Enabling the Plugin

Here's an example, enable this plugin on the specified route:
The example below enables the Plugin on a specific Route:

```shell
curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
Expand All @@ -55,21 +65,19 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f03433
}'
```

## Test Plugin
## Example usage

Use curl to access:
The example below shows the use case of uploading a big file:

```shell
curl -i http://127.0.0.1:9080/upload -d @very_big_file
```

It's expected not to find "a client request body is buffered to a temporary file" in the error log.
It's expected to not find a message "a client request body is buffered to a temporary file" in the error log.

## Disable Plugin

When you want to disable this 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 `proxy-control` 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 '
Expand All @@ -83,5 +91,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f1
}
}'
```

This plugin has been disabled now. It works for other plugins.
130 changes: 63 additions & 67 deletions docs/en/latest/plugins/request-id.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
---
title: request-id
keywords:
- APISIX
- Plugin
- Request ID
- request-id
description: This document contains information about the Apache APISIX request-id Plugin.
---

<!--
Expand All @@ -23,20 +29,60 @@ title: request-id

## Description

`request-id` plugin adds a unique ID (UUID) to each request proxied through APISIX. This plugin can be used to track an
API request. The plugin will not add a request id if the `header_name` is already present in the request.
The `request-id` Plugin adds a unique ID to each request proxied through APISIX.

This Plugin can be used to track API requests.

:::note

The Plugin will not add a unique ID if the request already has a header with the configured `header_name`.

:::

## Attributes

| Name | Type | Requirement | Default | Valid | Description |
| ------------------- | ------- | ----------- | -------------- | ----- | -------------------------------------------------------------- |
| header_name | string | optional | "X-Request-Id" | | Request ID header name |
| include_in_response | boolean | optional | true | | Option to include the unique request ID in the response header |
| algorithm | string | optional | "uuid" | ["uuid", "snowflake", "nanoid"] | ID generation algorithm |
| Name | Type | Required | Default | Valid values | Description |
| ------------------- | ------- | -------- | -------------- | ------------------------------- | ---------------------------------------------------------------------- |
| header_name | string | False | "X-Request-Id" | | Header name for the unique request ID. |
| include_in_response | boolean | False | true | | When set to `true`, adds the unique request ID in the response header. |
| algorithm | string | False | "uuid" | ["uuid", "snowflake", "nanoid"] | Algorithm to use for generating the unique request ID. |

## How To Enable
### Using snowflake algorithm to generate unique ID

Create a route and enable the request-id plugin on the route:
To use the snowflake algorithm, you have to enable it first on your configuration file (`conf/config.yaml`):

```yaml title="conf/config.yaml"
plugin_attr:
request-id:
snowflake:
enable: true
snowflake_epoc: 1609459200000
data_machine_bits: 12
sequence_bits: 10
data_machine_ttl: 30
data_machine_interval: 10
```

:::warning
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see "warning" listed on https://docusaurus.io/docs/markdown-features/admonitions, please specify which one you'd like to use. Personally I think :::caution should do the work.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you decide to stick with "waring", you can also do a trick like :::caution Warning.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it was supposed to be :::caution WARNING. I missed it. Thank you for pointing it out.


Please read this documentation before deciding to use the snowflake algorithm. Once it is configured, you cannot arbitrarily change the configuration. Failure to do so may result in duplicate ID being generated.
yzeng25 marked this conversation as resolved.
Show resolved Hide resolved

:::

#### Attributes

| Name | Type | Required | Default | Description |
| --------------------- | ------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| enable | boolean | False | false | When set to `true`, enables the snowflake algorithm. |
| snowflake_epoc | integer | False | 1609459200000 | Starting timestamp in milliseconds. Default is `2021-01-01T00:00:00Z` and supports to a 69 year time until `2090-09-0715:47:35Z`. |
| data_machine_bits | integer | False | 12 | Maximum number of supported machines (processes) `1 << data_machine_bits`. Corresponds the set of `workIDs` and `dataCenterIDs` in the snowflake definition. Each process is associated to a unique ID. The maximum number of supported processes is `pow(2, data_machine_bits)`. So, for the default value of 12 bits, it is 4096. |
| sequence_bits | integer | False | 10 | Maximum number of generated ID per millisecond per node `1 << sequence_bits`. Each process generates up to 1024 IDs per millisecond. |
| data_machine_ttl | integer | False | 30 | Valid time in seconds of registration of `data_machine` in etcd. |
| data_machine_interval | integer | False | 10 | Time in seconds between `data_machine` renewals in etcd. |

## Enabling the Plugin

The example below enables the Plugin on a specific Route:

```shell
curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
Expand All @@ -56,73 +102,23 @@ curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f13
}'
```

## Test Plugin
## Example usage

Once you have configured the Plugin as shown above, APISIX will create a unique ID for each request you make:

```shell
curl -i http://127.0.0.1:9080/hello
```

```shell
$ curl -i http://127.0.0.1:9080/hello
HTTP/1.1 200 OK
X-Request-Id: fe32076a-d0a5-49a6-a361-6c244c1df956
......
```

### Use the snowflake algorithm to generate an ID

> supports using the Snowflake algorithm to generate ID.
> read the documentation first before deciding to use snowflake. Because once the configuration information is enabled, you can not arbitrarily adjust the configuration information. Failure to do so may result in duplicate ID being generated.

The Snowflake algorithm is not enabled by default and needs to be configured in 'conf/config.yaml'.

```yaml
plugin_attr:
request-id:
snowflake:
enable: true
snowflake_epoc: 1609459200000
data_machine_bits: 12
sequence_bits: 10
data_machine_ttl: 30
data_machine_interval: 10
```

#### Configuration parameters

| Name | Type | Requirement | Default | Valid | Description |
| ------------------- | ------- | ------------- | -------------- | ------- | ------------------------------ |
| enable | boolean | optional | false | | When set it to true, enable the snowflake algorithm. |
| snowflake_epoc | integer | optional | 1609459200000 | | Start timestamp (in milliseconds) |
| data_machine_bits | integer | optional | 12 | | Maximum number of supported machines (processes) `1 << data_machine_bits` |
| sequence_bits | integer | optional | 10 | | Maximum number of generated ID per millisecond per node `1 << sequence_bits` |
| data_machine_ttl | integer | optional | 30 | | Valid time of registration of 'data_machine' in 'etcd' (unit: seconds) |
| data_machine_interval | integer | optional | 10 | | Time between 'data_machine' renewal in 'etcd' (unit: seconds) |

- `snowflake_epoc` default start time is `2021-01-01T00:00:00Z`, and it can support `69 year` approximately to `2090-09-0715:47:35Z` according to the default configuration
- `data_machine_bits` corresponds to the set of workIDs and datacEnteridd in the snowflake definition. The plug-in aslocates a unique ID to each process. Maximum number of supported processes is `pow(2, data_machine_bits)`. The default number of `12 bits` is up to `4096`.
- `sequence_bits` defaults to `10 bits` and each process generates up to `1024` ID per millisecond.

#### example

> Snowflake supports flexible configuration to meet a wide variety of needs

- Snowflake original configuration

> - Start time 2014-10-20 T15:00:00.000z, accurate to milliseconds. It can last about 69 years
> - supports up to `1024` processes
> - Up to `4096` ID per millisecond per process

```yaml
plugin_attr:
request-id:
snowflake:
enable: true
snowflake_epoc: 1413817200000
data_machine_bits: 10
sequence_bits: 12
```

## Disable Plugin

Remove the corresponding json configuration in the plugin configuration to disable the `request-id`.
APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
To disable the `request-id` 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 '
Expand Down
Loading