This is an automated email from the ASF dual-hosted git repository.
juzhiyuan 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 fdad0ae docs: restructure the "Architecture Design" Section (#6464)
fdad0ae is described below
commit fdad0aea0b1fbcba050bf5ed00b8801c40a6da16
Author: Navendu Pottekkat <[email protected]>
AuthorDate: Thu Mar 3 03:49:09 2022 +0530
docs: restructure the "Architecture Design" Section (#6464)
Signed-off-by: Navendu Pottekkat <[email protected]>
---
docs/en/latest/architecture-design/apisix.md | 20 +++++++----
docs/en/latest/architecture-design/consumer.md | 30 +++++++++--------
docs/en/latest/architecture-design/debug-mode.md | 33 +++++++++---------
docs/en/latest/architecture-design/global-rule.md | 13 ++++----
.../en/latest/architecture-design/plugin-config.md | 16 ++++-----
docs/en/latest/architecture-design/plugin.md | 39 +++++++++++++---------
docs/en/latest/architecture-design/route.md | 24 ++++++++-----
docs/en/latest/architecture-design/router.md | 22 +++++++-----
docs/en/latest/architecture-design/script.md | 10 +++---
docs/en/latest/architecture-design/service.md | 12 ++++---
docs/en/latest/architecture-design/upstream.md | 36 ++++++++++----------
11 files changed, 144 insertions(+), 111 deletions(-)
diff --git a/docs/en/latest/architecture-design/apisix.md
b/docs/en/latest/architecture-design/apisix.md
index f5d262e..8bef622 100644
--- a/docs/en/latest/architecture-design/apisix.md
+++ b/docs/en/latest/architecture-design/apisix.md
@@ -33,19 +33,23 @@ title: APISIX
-## Configure APISIX
+## Configuring APISIX
-There are two methods to configure APISIX: directly change `conf/config.yaml`,
or add file path argument using `-c` or `--config` flag when start APISIX like
`apisix start -c <path string>`
+Apache APISIX can be configured in two ways:
-For example, set the default listening port of APISIX to 8000, and keep other
configurations as default. The configuration in `config.yaml` should be like
this:
+1. By directly changing `conf/config.yaml`.
+2. Using the `--config` or the `-c` flag to pass in the file path of your
config file while starting APISIX (`apisix start -c <path to config file>`).
+
+Configurations can be added to this YAML file and Apache APISIX will fall back
to the default configurations for anything that is not configured in this file.
+
+For example, to set the default listening port to 8000 while keeping other
configurations as default, your configuration file (`config.yaml`) would look
like:
```yaml
apisix:
node_listen: 8000 # APISIX listening port
```
-Set the default listening port of APISIX to 8000, set the `etcd` address to
`http://foo:2379`,
-and keep other configurations as default. The configuration in `config.yaml`
should be like this:
+Similarly, to set the listening port to 8000 and set the etcd address to
`http://foo:2379` while keeping other configurations as default, your
configuration file would look like:
```yaml
apisix:
@@ -55,6 +59,8 @@ etcd:
host: "http://foo:2379"; # etcd address
```
-Other default configurations can be found in the `conf/config-default.yaml`
file, which is bound to the APISIX source code. **Never** manually modify the
`conf/config-default.yaml` file. If you need to customize any configuration,
you should update the `config.yaml` file.
+Default configurations of APISIX can be found in the
`conf/config-default.yaml` file.
+
+**Note**: This file is bound to the APISIX source code and should **NOT** be
modified. The configuration should only be changed by the methods mentioned
above.
-**Note** `APISIX` will generate `conf/nginx.conf` file automatically, so
please _DO NOT EDIT_ `conf/nginx.conf` file too.
+**Note**: The `conf/nginx.conf` file is automatically generated by APISIX and
should **NOT** be edited.
diff --git a/docs/en/latest/architecture-design/consumer.md
b/docs/en/latest/architecture-design/consumer.md
index 3710338..e41eb65 100644
--- a/docs/en/latest/architecture-design/consumer.md
+++ b/docs/en/latest/architecture-design/consumer.md
@@ -21,32 +21,34 @@ title: Consumer
#
-->
-For the API gateway, it is usually possible to identify a certain type of
requester by using a domain name such as a request domain name, a client IP
address, etc., and then perform plugin filtering and forward the request to the
specified upstream, but sometimes the depth is insufficient.
+For an API gateway, it is usually possible to identify the type of the
requester by using things like their request domain name and client IP address.
A gateway like APISIX can then filter these requests using
[Plugins](./plugin.md) and forward it to the specified
[Upstream](./upstream.md).
+
+But this level of depth can be insufficient in some occasions.
-As shown in the image above, as an API gateway, you should know who the API
Consumer is, so you can configure different rules for different API Consumers.
+An API gateway should know who the consumer of the API is to configure
different rules for different consumers.
+
+This is where the Consumer construct comes in APISIX. The fields are defined
below.
| Field | Required | Description
|
| -------- | -------- |
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
-| username | Yes | Consumer Name.
|
-| plugins | No | The corresponding plugin configuration of the
Consumer, which has the highest priority: Consumer > Route > Service. For
specific plugin configurations, refer to the [Plugins](plugin.md) section. |
+| username | Yes | Name of the consumer.
|
+| plugins | No | Plugin configuration of the Consumer. It has the
highest priority: Consumer > Route > Service. For specific Plugin
configurations, refer the [Plugins](./plugin.md) section. |
-In APISIX, the process of identifying a Consumer is as follows:
+The process of identifying a Consumer in APISIX is described below:
-1. Authorization certification: e.g [key-auth](../plugins/key-auth.md),
[JWT](../plugins/jwt-auth.md), etc.
-2. Get consumer_name: By authorization, you can naturally get the
corresponding Consumer `id`, which is the unique identifier of the Consumer
object.
-3. Get the Plugin or Upstream information bound to the Consumer: Complete the
different configurations for different Consumers.
-
-To sum up, Consumer is a consumer of certain types of services and needs to be
used in conjunction with the user authentication system.
+1. The first step is Authentication. This is achieved by Authentication
Plugins like [key-auth](../plugins/key-auth.md) and
[JWT](../plugins/jwt-auth.md).
+2. After authenticating, you can obtain the `id` of the Consumer. This `id`
will be the unique identifier of a Consumer.
+3. The configurations like Plugins and Upstream bound to the Consumer are then
executed.
-For example, different consumers request the same API, and the gateway service
corresponds to different Plugin or Upstream configurations according to the
current request user information.
+Consumers are useful when you have different consumers requesting the same API
and you need to execute different Plugin and Upstream configurations based on
the consumer. These need to be used in conjunction with the user authentication
system.
-In addition, you can refer to the [key-auth](../plugins/key-auth.md)
authentication authorization plugin call logic to help you further understand
the Consumer concept and usage.
+Refer the documentation for the [key-auth](../plugins/key-auth.md)
authentication Plugin to further understand the concept of a Consumer.
-How to enable a specific plugin for a Consumer, you can see the following
example:
+The example below shows how you can enable a Plugin for a specific Consumer.
```shell
# Create a Consumer, specify the authentication plugin key-auth, and enable
the specific plugin limit-count
@@ -95,7 +97,7 @@ HTTP/1.1 503 Service Temporarily Unavailable
```
-Use the [consumer-restriction](../plugins/consumer-restriction.md) plug-in to
restrict the access of Jack to this API.
+We can use the [consumer-restriction](../plugins/consumer-restriction.md)
Plugin to restrict our user "Jack" from accessing the API.
```shell
# Add Jack to the blacklist
diff --git a/docs/en/latest/architecture-design/debug-mode.md
b/docs/en/latest/architecture-design/debug-mode.md
index 5c66343..792c2bb 100644
--- a/docs/en/latest/architecture-design/debug-mode.md
+++ b/docs/en/latest/architecture-design/debug-mode.md
@@ -23,16 +23,16 @@ title: Debug Mode
### Basic Debug Mode
-Enable basic debug mode via `conf/debug.yaml` file:
+You can enable the basic debug mode by adding this line to your
`conf/debug.yaml` file.
```
basic:
enable: true
```
-Note: before APISIX 2.10, we enabled basic debug mode by setting
`apisix.enable_debug = true` in `conf/config.yaml` file.
+**Note**: Before Apache APISIX 2.10, basic debug mode was enabled by setting
`apisix.enable_debug = true` in the `conf/config.yaml` file.
-e.g Using both `limit-conn` and `limit-count` plugins for a `/hello` request,
there will have a response header called `Apisix-Plugins: limit-conn,
limit-count`.
+For example, if we are using two plugins `limit-conn` and `limit-count` for a
Route `/hello`, we will receive a response with the header `Apisix-Plugins:
limit-conn, limit-count` when we enable the basic debug mode.
```shell
$ curl http://127.0.0.1:1984/hello -i
@@ -48,22 +48,25 @@ Server: openresty
hello world
```
-If the information can not be delivered via HTTP response header, for example,
the plugin is in stream
-subsystem, the information will be logged in the error log with `warn` level.
+If the debug information cannot be included in a response header (say when the
plugin is in a stream subsystem), the information will be logged in the error
log at a `warn` level.
### Advanced Debug Mode
-Enable advanced debug mode by modifying the configuration in `conf/debug.yaml`
file. Because there will be a check every second, only the checker reads the
`#END` flag, and the file would be considered as closed.
+Advanced debug mode can also be enabled by modifying the configuration in the
`conf/debug.yaml` file.
-The checker would judge whether the file data changed according to the last
modification time of the file. If there has any change, reload it. If there was
no change, skip this check. So it's hot reload for enabling or disabling
advanced debug mode.
+Enable advanced debug mode by modifying the configuration in `conf/debug.yaml`
file.
+
+The checker checks every second for changes to the configuration files. An
`#END` flag is added to let the checker know that it should only look for
changes till that point.
+
+The checker would only check this if the file was updated by checking its last
modification time.
| Key | Optional | Description
| Default |
| ------------------------------- | -------- |
-----------------------------------------------------------------------------------------------------------------------------------------
| ------- |
| hook_conf.enable | required | Enable/Disable hook debug
trace. Target module function's input arguments or returned value would be
printed once this option is enabled. | false |
-| hook_conf.name | required | The module list name of hook
which has enabled debug trace.
| |
-| hook_conf.log_level | required | Logging levels for input
arguments & returned value.
| warn |
-| hook_conf.is_print_input_args | required | Enable/Disable input arguments
print.
| true |
-| hook_conf.is_print_return_value | required | Enable/Disable returned value
print.
| true |
+| hook_conf.name | required | The module list name of the
hook which has enabled debug trace.
| |
+| hook_conf.log_level | required | Logging levels for input
arguments & returned values.
| warn |
+| hook_conf.is_print_input_args | required | Enable/Disable printing input
arguments.
| true |
+| hook_conf.is_print_return_value | required | Enable/Disable printing
returned values.
| true |
Example:
@@ -86,9 +89,9 @@ hook_phase: # Module Function List, Name: hook_phase
### Enable Advanced Debug Mode Dynamically
-The advanced debug mode can take effect in particular requests by dynamic rule.
+You can also enable the advanced debug mode to take effect on particular
requests.
-Example:
+For example, to dynamically enable advanced debugging mode on requests with a
particular header name `X-APISIX-Dynamic-Debug` you can configure:
```yaml
http_filter:
@@ -98,10 +101,10 @@ http_filter:
#END
```
-Dynamically enable advanced debugging mode in a particular request like this:
+This will enable the advanced debug mode for requests like:
```shell
curl 127.0.0.1:9090/hello --header 'X-APISIX-Dynamic-Debug: foo'
```
-Notice: We can not hook the `apisix.http_access_phase` module for particular
requests, since whether the advanced debug mode is enabled is determined after
these requests enter such phase.
+**Note**: The `apisix.http_access_phase` module cannot be hooked for dynamic
rules as the advanced debug mode is enabled based on the request.
diff --git a/docs/en/latest/architecture-design/global-rule.md
b/docs/en/latest/architecture-design/global-rule.md
index cb9615e..a38084c 100644
--- a/docs/en/latest/architecture-design/global-rule.md
+++ b/docs/en/latest/architecture-design/global-rule.md
@@ -1,5 +1,5 @@
---
-title: Global rule
+title: Global Rule
---
<!--
@@ -21,8 +21,11 @@ title: Global rule
#
-->
-The [Plugin](plugin.md) configuration can be bound directly to a
[Route](route.md), or to a [Service](service.md) or [Consumer](consumer.md).
What if we want a [Plugin](plugin.md) to work on all requests, how to do it?
-We can register a global [Plugin](plugin.md) with `GlobalRule`:
+A [Plugin](./plugin.md) configuration can be bound directly to a
[Route](./route.md), a [Service](./service.md) or a [Consumer](./consumer.md).
But what if we want a Plugin to work on all requests?
+
+This is where we register a global Plugin with Global Rule.
+
+The example below shows how you can use the `limit-count` Plugin on all
requests:
```shell
curl -X PUT \
@@ -42,9 +45,7 @@ curl -X PUT \
}'
```
-Now, the `limit-count` plugin will work on all requests
-
-we can list all `GlobalRule` via admin api as below:
+You can also list all the Global rules by making this request with the Admin
API:
```shell
curl https://{apisix_listen_address}/apisix/admin/global_rules
diff --git a/docs/en/latest/architecture-design/plugin-config.md
b/docs/en/latest/architecture-design/plugin-config.md
index 84de448..075562f 100644
--- a/docs/en/latest/architecture-design/plugin-config.md
+++ b/docs/en/latest/architecture-design/plugin-config.md
@@ -21,10 +21,9 @@ title: Plugin Config
#
-->
-To reuse common plugin configurations, you can extract them into a plugin
config and
-bind it with a route directly.
+Plugin Configs are used to extract commonly used [Plugin](./plugin.md)
configurations and can be bound directly to a [Route](./route.md).
-For instance, you can do something like:
+The example below illustrates how this can be used:
```shell
# create a plugin config
@@ -54,12 +53,11 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f
}'
```
-When we can't find the corresponding plugin config with the id, the requests
hit the route will be terminated with HTTP status code 503.
+When APISIX can't find the Plugin Config with the `id`, the requests reaching
this Route are terminated with a status code of 503.
-When a route already have `plugins` field configured, the `plugins` in the
plugin config
-will be merged into it. The same plugin in the plugin config will override one
in the `plugins`.
+If a Route already has the `plugins` field configured, the plugins in the
Plugin Config will effectively be merged to it. The same plugin in the Plugin
Config will override the ones configured directly in the Route.
-For example, when we configure a plugin config
+For example, if we configure a Plugin Config as shown below
```
{
@@ -80,7 +78,7 @@ For example, when we configure a plugin config
}
```
-to
+to a Route as shown below,
```
{
@@ -108,7 +106,7 @@ to
}
```
-is equal to
+the effective configuration will be as the one shown below:
```
{
diff --git a/docs/en/latest/architecture-design/plugin.md
b/docs/en/latest/architecture-design/plugin.md
index cda1e8e..a325719 100644
--- a/docs/en/latest/architecture-design/plugin.md
+++ b/docs/en/latest/architecture-design/plugin.md
@@ -21,17 +21,21 @@ title: Plugin
#
-->
-`Plugin` represents the plugin configuration that will be executed during the
`HTTP` request/response lifecycle.
+This represents the configuration of the plugins that are executed during the
HTTP request/response lifecycle.
-The `Plugin` configuration can be bound directly to `Route` or it can be bound
to `Service` or `Consumer`. For the configuration of the same plugin, only one
copy is valid, and the configuration selection priority is always `Consumer` >
`Route` > `Service`.
+A `Plugin` configuration can be bound directly to a [`Route`](./route.md), a
[`Service`](./service.md) or a [`Consumer`](./consumer.md).
-In `conf/config.yaml`, you can declare which plugins are supported by the
local APISIX node. This is a whitelisting mechanism. Plugins that are not in
this whitelist will be automatically ignored. This feature can be used to
temporarily turn off or turn on specific plugins, which is very effective in
dealing with unexpected situations. If you want to add new plugins based on
existing plugins, you need to copy the data of `plugins` node which in
`conf/config-default.yaml` to the `plugins` [...]
+**Note**: While configuring the same plugin, only one copy of the
configuration is valid. The order of precedence is always `Consumer` > `Route`
> `Service`.
-The configuration of the plugin can be directly bound to the specified Route,
or it can be bound to the Service, but the plugin configuration in Route has a
higher priority.
+While [configuring APISIX](./apisix.md#configuring-apisix), you can declare
the Plugins that are supported by the local APISIX node.
-A plugin will only be executed once in a single request, even if it is bound
to multiple different objects (such as Route or Service).
+This acts as a whitelisting mechanism as Plugins that are not in this
whitelist will be automatically ignored. So, this feature can be used to
temporarily turn off/turn on specific plugins.
-The order in which plugins are run is determined by the priority of the plugin
itself, for example:
+For adding new plugins based on existing plugins, copy the data in the the
`plugins` node from the default configuration file `conf/config-default.yaml`
to your configuration file (`conf/config.yaml`).
+
+In a request, a Plugin is only executed once. This is true even if it is bound
to multiple different objects like Routes and Services.
+
+The order in which Plugins are run is determined by its configured priorities:
```lua
local _M = {
@@ -43,7 +47,7 @@ local _M = {
}
```
-The plugin configuration is submitted as part of Route or Service and placed
under `plugins`. It internally uses the plugin name as the hash's key to hold
configuration items for different plugins.
+A Plugin configuration is submitted as part of the Route or Service and is
placed under `plugins`. It internally uses the Plugin name as the hash key to
hold the configuration items for the different Plugins.
```json
{
@@ -60,23 +64,28 @@ The plugin configuration is submitted as part of Route or
Service and placed und
}
```
-Not all plugins have specific configuration items. For example, there is no
specific configuration item under `prometheus`. In this case, an empty object
identifier can be used.
+Not all Plugins have specific configuration items (for example,
[prometheus](/docs/apisix/plugins/prometheus/)). In such cases, an empty object
identifier can be used.
+
+A warn level log as shown below indicates that the request was rejected by the
Plugin.
+
+```shell
+ip-restriction exits with http status code 403
+```
-If a request is rejected by a plugin, there will be warn level log like
`ip-restriction exits with http status code 403`.
+## Hot Reload
-## Hot reload
+APISIX Plugins are hot-loaded.
-APISIX plugins are hot-loaded. No matter you add, delete or modify plugins,
and **update codes of plugins in disk**, you don't need to restart the service.
+This means that there is no need to restart the service if you add, delete,
modify plugins or even if you update the plugin code.
-If your APISIX node has the Admin API turned on, just send an HTTP request
through admin API:
+To hot-reload, you can send an HTTP request through the [Admin
API](../admin-api.md):
```shell
curl http://127.0.0.1:9080/apisix/admin/plugins/reload -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT
```
-Note: if you disable a plugin that has been configured as part of your rule
(in the `plugins` field of `route`, etc.),
-then its execution will be skipped.
+**Note**: If a configured Plugin is disabled, then its execution will be
skipped.
### Hot reload in stand-alone mode
-For stand-alone mode, see plugin related section in [stand alone
mode](../stand-alone.md).
+For hot-reloading in stand-alone mode, see the plugin related section in
[stand alone mode](../stand-alone.md).
diff --git a/docs/en/latest/architecture-design/route.md
b/docs/en/latest/architecture-design/route.md
index 57a2449..e287e99 100644
--- a/docs/en/latest/architecture-design/route.md
+++ b/docs/en/latest/architecture-design/route.md
@@ -21,19 +21,25 @@ title: Route
#
-->
-The route matches the client's request by defining rules, then loads and
executes the corresponding plugin based on the matching result, and forwards
the request to the specified Upstream.
+Routes match the client's request based on defined rules, loads and executes
the corresponding [plugins](./plugin.md), and forwards the request to the
specified [Upstream](./upstream.md).
-The route mainly consists of three parts: matching rules (e.g uri, host,
remote_addr, etc.), plugin configuration (current-limit & rate-limit, etc.) and
upstream information.
+A Route mainly consists of three parts:
-The following image shows an example of some Route rules. When some attribute
values are the same, the figure is identified by the same color.
+1. Matching rules (uri, host, remote address)
+2. Plugin configuration (current-limit, rate-limit)
+3. Upstream information
+
+The image below shows some example Route rules. Note that the values are of
the same color if they are identical.
-We configure all the parameters directly in the Route, it's easy to set up,
and each Route has a relatively high degree of freedom. But when our Route has
more repetitive configurations (such as enabling the same plugin configuration
or upstream information), once we need update these same properties, we have to
traverse all the Routes and modify them, so it's adding a lot of complexity of
management and maintenance.
+All the parameters are configured directly in the Route. It is easy to set up,
and each Route has a high degree of freedom.
+
+When Routes have repetitive configurations (say, enabling the same plugin
configuration or Upstream information), to update it, we need to traverse all
the Routes and modify them. This adds a lot of complexity, making it difficult
to maintain.
-The shortcomings mentioned above are independently abstracted in APISIX by the
two concepts [Service](service.md) and [Upstream](upstream.md).
+These shortcomings are independently abstracted in APISIX by two concepts:
[Service](service.md) and [Upstream](upstream.md).
-The route example created below is to proxy the request with URL `/index.html`
to the Upstream service with the address `127.0.0.1:1980`:
+The Route example shown below proxies the request with the URL `/index.html`
to the Upstream service with the address `127.0.0.1:1980`.
```shell
$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -i -d '
@@ -46,7 +52,9 @@ $ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f
}
}
}'
+```
+```shell
HTTP/1.1 201 Created
Date: Sat, 31 Aug 2019 01:17:15 GMT
Content-Type: text/plain
@@ -57,6 +65,6 @@ Server: APISIX web server
{"node":{"value":{"uri":"\/index.html","upstream":{"nodes":{"127.0.0.1:1980":1},"type":"roundrobin"}},"createdIndex":61925,"key":"\/apisix\/routes\/1","modifiedIndex":61925},"action":"create"}
```
-When we receive a successful response, it indicates that the route was
successfully created.
+A successful response indicates that the route was created.
-For specific options of Route, please refer to [Admin
API](../admin-api.md#route).
+For specific options of Route, please refer to the [Admin
API](../admin-api.md#route).
diff --git a/docs/en/latest/architecture-design/router.md
b/docs/en/latest/architecture-design/router.md
index 4dbd970..58db1a6 100644
--- a/docs/en/latest/architecture-design/router.md
+++ b/docs/en/latest/architecture-design/router.md
@@ -21,19 +21,23 @@ title: Router
#
-->
-A distinguishing feature of APISIX from other API gateways is that it allows
users to choose different routers to better match free services, making the
best choice between performance and freedom.
+A distinguishing feature of Apache APISIX from other API gateways is that it
allows you to choose different Routers to better match free services, giving
you the best choices for performance and freedom.
+
+You can set the Router that best suits your needs in your configuration file
(conf/config.yaml).
Set the route that best suits your business needs in the local configuration
`conf/config.yaml`.
-- `apisix.router.http`: HTTP Request Route。
+It can have the following configurations:
+
+- `apisix.router.http`: The HTTP request route. It can take the following
values:
- - `radixtree_uri`: (Default) only use `uri` as the primary index. Support
for full and deep prefix matching based on the `radixtree` engine, see [How to
use router-radixtree](../router-radixtree.md).
- - `Absolute match`: Complete match for the given `uri`, such as
`/foo/bar`,`/foo/glo`.
- - `Prefix match`: Use `*` at the end to represent the given `uri` as a
prefix match. For example, `/foo*` allows matching `/foo/`, `/foo/a` and
`/foo/b`.
- - `match priority`: first try absolute match, if you can't hit absolute
match, try prefix match.
- - `Any filter attribute`: Allows you to specify any Nginx built-in
variable as a filter, such as URL request parameters, request headers, cookies,
and so on.
- - `radixtree_uri_with_parameter`: Like `radixtree_uri` but also support
parameter match.
- - `radixtree_host_uri`: Use `host + uri` as the primary index (based on the
`radixtree` engine), matching both host and URL for the current request.
+ - `radixtree_uri`: (Default) Only use the `uri` as the primary index. To
learn more about the support for full and deep prefix matching, check [How to
use router-radixtree](../router-radixtree.md).
+ - `Absolute match`: Match completely with the given `uri` (`/foo/bar`,
`/foo/glo`).
+ - `Prefix match`: Match with the given prefix. Use `*` to represent the
given `uri` for prefix matching. For example, `/foo*` can match with `/foo/`,
`/foo/a` and `/foo/b`.
+ - `match priority`: First try an absolute match, if it didn't match, try
prefix matching.
+ - `Any filter attribute`: Allows you to specify any Nginx built-in
variable as a filter, such as URL request parameters, request headers, and
cookies.
+ - `radixtree_uri_with_parameter`: Like `radixtree_uri` but also supports
parameter match.
+ - `radixtree_host_uri`: Matches both host and URI of the request. Use `host
+ uri` as the primary index (based on the `radixtree` engine).
- `apisix.router.ssl`: SSL loads the matching route.
- `radixtree_sni`: (Default) Use `SNI` (Server Name Indication) as the
primary index (based on the radixtree engine).
diff --git a/docs/en/latest/architecture-design/script.md
b/docs/en/latest/architecture-design/script.md
index 0987d49..3e77b28 100644
--- a/docs/en/latest/architecture-design/script.md
+++ b/docs/en/latest/architecture-design/script.md
@@ -21,15 +21,13 @@ title: Script
#
-->
-`Script` represents a script that will be executed during the `HTTP`
request/response life cycle.
+Scripts lets you write arbitrary Lua code or directly call existing plugins
and execute them during the HTTP request/response lifecycle.
-The `Script` configuration can be directly bound to the `Route`.
+A Script configuration can be directly bound to a [Route](./route.md).
-`Script` and `Plugin` are mutually exclusive, and `Script` is executed first.
This means that after configuring `Script`, the `Plugin` configured on `Route`
will not be executed.
+Scripts and [Plugins](./plugin.md) are mutually exclusive, and a Script is
executed before a Plugin. This means that after configuring a Script, the
Plugin configured on the Route will **not** be executed.
-In theory, you can write arbitrary Lua code in `Script`, or you can directly
call existing plugins to reuse existing code.
-
-`Script` also has the concept of execution phase, supporting `access`,
`header_filter`, `body_filter` and `log` phase. The system will automatically
execute the code of the corresponding phase in the `Script` script in the
corresponding phase.
+Scripts also have a concept of execution phase which supports the `access`,
`header_filter`, `body_filter` and the `log` phase. The corresponding phase
will be executed automatically by the system in the Script.
```json
{
diff --git a/docs/en/latest/architecture-design/service.md
b/docs/en/latest/architecture-design/service.md
index f2238c9..019bcd5 100644
--- a/docs/en/latest/architecture-design/service.md
+++ b/docs/en/latest/architecture-design/service.md
@@ -21,13 +21,15 @@ title: Service
#
-->
-A `Service` is an abstraction of an API (which can also be understood as a set
of Route abstractions). It usually corresponds to the upstream service
abstraction. Between `Route` and `Service`, usually the relationship of N:1,
please see the following image.
+A Service is an abstraction of an API (which can also be understood as a set
of [Route](./route.md) abstractions). It usually corresponds to an upstream
service abstraction.
+
+The relationship between Routes and a Service is usually N:1 as shown in the
image below.
-Different Route rules are bound to a Service at the same time. These Routes
will have the same upstream and plugin configuration, reducing redundant
configuration.
+As shown, different Routes could be bound to the same Service. This reduces
redundancy as these bounded Routes will have the same [Upstream](./upstream.md)
and [Plugin](./plugin.md) configurations.
-The following example creates a Service that enables the current-limit plugin,
and then binds the Route with the id of `100` and `101` to the Service.
+The following example creates a Service that enables the current-limit Plugin,
and then binds it to the Routes with the ids `100` and `101`.
```shell
# create new Service
@@ -65,7 +67,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/101 -H
'X-API-KEY: edd1c9f034335f
}'
```
-Of course, we can also specify different plugin parameters or upstream for
Route. Some of the following Routes have different current-limit parameters.
Other parts (such as upstream) continue to use the configuration parameters in
Service.
+We can also specify different Plugins or Upstream for the Routes than the ones
defined in the Service. The example below creates a Route with a limit-count
Plugin. This Route will continue to use the other configurations defined in the
Service (here, the Upstream configuration).
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/102 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -84,4 +86,4 @@ curl http://127.0.0.1:9080/apisix/admin/routes/102 -H
'X-API-KEY: edd1c9f034335f
}'
```
-Note: When both Route and Service enable the same plugin, the Route parameter
has a higher priority than Service.
+**Note**: When a Route and a Service enable the same Plugin, the one defined
in the Route is given the higher priority.
diff --git a/docs/en/latest/architecture-design/upstream.md
b/docs/en/latest/architecture-design/upstream.md
index e8d8e11..e00bd88 100644
--- a/docs/en/latest/architecture-design/upstream.md
+++ b/docs/en/latest/architecture-design/upstream.md
@@ -21,19 +21,21 @@ title: Upstream
#
-->
-Upstream is a virtual host abstraction that performs load balancing on a given
set of service nodes according to configuration rules. Upstream address
information can be directly configured to `Route` (or `Service`). When Upstream
has duplicates, you need to use "reference" to avoid duplication.
+Upstream is a virtual host abstraction that performs load balancing on a given
set of service nodes according to the configured rules.
+
+Although Upstream can be directly configured to the [Route](./route.md) or
[Service](./route.md), using an Upstream object is recommended when there is
duplication as shown below.
-As shown in the image above, by creating an Upstream object and referencing it
by ID in `Route`, you can ensure that only the value of an object is maintained.
+By creating an Upstream object and referencing it by `upstream_id` in the
Route, you can ensure that there is only a single value of the object that
needs to be maintained.
-Upstream configuration can be directly bound to the specified `Route` or it
can be bound to `Service`, but the configuration in `Route` has a higher
priority. The priority behavior here is very similar to `Plugin`.
+An Upstream configuration can be directly bound to a Route or a Service, but
the configuration in Route has a higher priority. This behavior is consistent
with priority followed by the [Plugin](./plugin.md) object.
### Configuration
-In addition to the basic complex equalization algorithm selection, APISIX's
Upstream also supports logic for upstream passive health check and retry, see
[this link](../admin-api.md#upstream).
+In addition to the equalization algorithm selections, Upstream also supports
passive health check and retry for the upstream. You can learn more about this
[here](../admin-api.md#upstream).
-Create an upstream object use case:
+To create an Upstream object, you can use the Admin API as shown below:
```shell
curl http://127.0.0.1:9080/apisix/admin/upstreams/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -47,7 +49,7 @@ curl http://127.0.0.1:9080/apisix/admin/upstreams/1 -H
'X-API-KEY: edd1c9f034335
}'
```
-After the upstream object is created, it can be referenced by specific `Route`
or `Service`, for example:
+After creating an Upstream object, it can be referenced by a specific Route or
Service as shown below:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -57,7 +59,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-For convenience, you can also directly bind the upstream address to a `Route`
or `Service`, for example:
+For convenience, you can directly bind the upstream address to a Route or
Service:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -80,7 +82,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-Here's an example of configuring a health check:
+The example below shows how you can configure a health check:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -118,13 +120,13 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-More details can be found in [Health Checking Documents](../health-check.md).
+You can learn more about health checks [here](../health-check.md).
-Here are some examples of configurations using different `hash_on` types:
+The examples below shows configurations which uses different `hash_on` types.
#### Consumer
-Create a consumer object:
+Creating a Consumer object:
```shell
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -138,7 +140,7 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H
'X-API-KEY: edd1c9f034335f1
}'
```
-Create route object and enable `key-auth` plugin authentication:
+Creating a Route object and enabling the `key-auth` authentication Plugin:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -158,7 +160,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-Test request, the `consumer_name` after authentication is passed will be used
as the hash value of the load balancing hash algorithm:
+To test the request, the `consumer_name` passed for authentication will be
used as the hash value of the load balancing hash algorithm.
```shell
curl http://127.0.0.1:9080/server_port -H "apikey: auth-jack"
@@ -166,7 +168,7 @@ curl http://127.0.0.1:9080/server_port -H "apikey:
auth-jack"
#### Cookie
-Create route and upstream object, `hash_on` is `cookie`:
+Creating a Route and an upstream object:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -184,7 +186,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-The client requests with `Cookie`:
+The client can then send a request with a cookie:
```shell
curl http://127.0.0.1:9080/hash_on_cookie -H "Cookie:
sid=3c183a30cffcda1408daf1c61d47b274"
@@ -192,7 +194,7 @@ The client requests with `Cookie`:
#### Header
-Create route and upstream object, `hash_on` is `header`, `key` is
`Content-Type`:
+Creating a Route and an upstream object:
```shell
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
@@ -210,7 +212,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H
'X-API-KEY: edd1c9f034335f13
}'
```
-The client requests with header `Content-Type`:
+The client can now send requests with a header. The example below shows using
the header `Content-Type`:
```shell
curl http://127.0.0.1:9080/hash_on_header -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -H "Content-Type: application/json"
