You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2022/03/17 11:24:17 UTC
[apisix] branch master updated: docs: move keyword definition to `Terminology` section and improve (#6610)
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 6cea6a9 docs: move keyword definition to `Terminology` section and improve (#6610)
6cea6a9 is described below
commit 6cea6a90d165b0f01df4405a310cdb22e34aeb6b
Author: Avinal Kumar <av...@gmail.com>
AuthorDate: Thu Mar 17 16:54:06 2022 +0530
docs: move keyword definition to `Terminology` section and improve (#6610)
---
docs/en/latest/architecture-design/debug-mode.md | 8 ++---
docs/en/latest/config.json | 23 ++++++++-----
docs/en/latest/terminology/api-gateway.md | 39 ++++++++++++++++++++++
.../consumer.md | 24 ++++++++-----
.../global-rule.md | 6 ++--
.../{architecture-design => terminology}/plugin.md | 30 ++++++++---------
.../{architecture-design => terminology}/route.md | 10 ++++--
.../{architecture-design => terminology}/router.md | 10 +++---
.../{architecture-design => terminology}/script.md | 4 ++-
.../service.md | 9 +++--
.../upstream.md | 8 +++--
11 files changed, 122 insertions(+), 49 deletions(-)
diff --git a/docs/en/latest/architecture-design/debug-mode.md b/docs/en/latest/architecture-design/debug-mode.md
index 792c2bb..479bdec 100644
--- a/docs/en/latest/architecture-design/debug-mode.md
+++ b/docs/en/latest/architecture-design/debug-mode.md
@@ -63,10 +63,10 @@ The checker would only check this if the file was updated by checking its last m
| 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 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 |
+| 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:
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 1cc5ad9..0bf31b8 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -6,19 +6,26 @@
"label": "Architecture Design",
"items": [
"architecture-design/apisix",
- "architecture-design/route",
- "architecture-design/plugin",
- "architecture-design/script",
- "architecture-design/service",
- "architecture-design/consumer",
- "architecture-design/upstream",
- "architecture-design/global-rule",
"architecture-design/plugin-config",
- "architecture-design/router",
"architecture-design/debug-mode"
]
},
{
+ "type": "category",
+ "label": "Terminology",
+ "items": [
+ "terminology/api-gateway",
+ "terminology/consumer",
+ "terminology/global-rule",
+ "terminology/plugin",
+ "terminology/route",
+ "terminology/router",
+ "terminology/script",
+ "terminology/service",
+ "terminology/upstream"
+ ]
+ },
+ {
"type": "doc",
"id": "getting-started"
},
diff --git a/docs/en/latest/terminology/api-gateway.md b/docs/en/latest/terminology/api-gateway.md
new file mode 100644
index 0000000..435c226
--- /dev/null
+++ b/docs/en/latest/terminology/api-gateway.md
@@ -0,0 +1,39 @@
+---
+title: API Gateway
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Description
+
+An API gateway is a software pattern that sits in front of an application programming interface (API) or group of microservices, to facilitate requests and delivery of data and services. Its primary role is to act as a single entry point and standardized process for interactions between an organization's apps, data, and services and internal and external customers. The API gateway can also perform various other functions to support and manage API usage, from authentication to rate limiti [...]
+
+An API gateway also acts as a gateway between the API and the underlying infrastructure. It can be used to route requests to different backends, such as a load balancer, or route requests to different services based on the request headers.
+
+## Why use an API gateway?
+
+An API gateway comes with a lot of benefits over a traditional API microservice. The following are some of the benefits:
+
+- It is a single entry point for all API requests.
+- It can be used to route requests to different backends, such as a load balancer, or route requests to different services based on the request headers.
+- It can be used to perform authentication, authorization, and rate-limiting.
+- It can be used to support analytics, such as monitoring, logging, and tracing.
+- It can protect the API from malicious attack vectors such as SQL injections, DDOS attacks, and XSS.
+- It decreases the complexity of the API and microservices.
diff --git a/docs/en/latest/architecture-design/consumer.md b/docs/en/latest/terminology/consumer.md
similarity index 83%
rename from docs/en/latest/architecture-design/consumer.md
rename to docs/en/latest/terminology/consumer.md
index e41eb65..331cc6c 100644
--- a/docs/en/latest/architecture-design/consumer.md
+++ b/docs/en/latest/terminology/consumer.md
@@ -21,20 +21,26 @@ title: Consumer
#
-->
+## Description
+
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.
+But this level of depth can be insufficient on some occasions.
-An API gateway should know who the consumer of the API is to configure different rules for different 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.
+
+### Configuration options
-This is where the Consumer construct comes in APISIX. The fields are defined below.
+The fields for defining a Consumer are defined as below.
-| Field | Required | Description |
-| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 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. |
+| Field | Required | Description |
+| ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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. |
+
+## Identifying a Consumer
The process of identifying a Consumer in APISIX is described below:
@@ -46,7 +52,9 @@ The process of identifying a Consumer in APISIX is described below:
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.
-Refer the documentation for the [key-auth](../plugins/key-auth.md) authentication Plugin to further understand the concept of a Consumer.
+Refer to the documentation for the [key-auth](../plugins/key-auth.md) authentication Plugin to further understand the concept of a Consumer.
+
+## Example
The example below shows how you can enable a Plugin for a specific Consumer.
diff --git a/docs/en/latest/architecture-design/global-rule.md b/docs/en/latest/terminology/global-rule.md
similarity index 94%
rename from docs/en/latest/architecture-design/global-rule.md
rename to docs/en/latest/terminology/global-rule.md
index a38084c..67b3b2d 100644
--- a/docs/en/latest/architecture-design/global-rule.md
+++ b/docs/en/latest/terminology/global-rule.md
@@ -21,9 +21,11 @@ title: Global Rule
#
-->
-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?
+## Description
-This is where we register a global Plugin with Global Rule.
+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.
+
+## Example
The example below shows how you can use the `limit-count` Plugin on all requests:
diff --git a/docs/en/latest/architecture-design/plugin.md b/docs/en/latest/terminology/plugin.md
similarity index 63%
rename from docs/en/latest/architecture-design/plugin.md
rename to docs/en/latest/terminology/plugin.md
index a325719..efc21e1 100644
--- a/docs/en/latest/architecture-design/plugin.md
+++ b/docs/en/latest/terminology/plugin.md
@@ -21,21 +21,21 @@ title: Plugin
#
-->
-This represents the configuration of the plugins that are executed during the HTTP request/response lifecycle.
+## Description
-A `Plugin` configuration can be bound directly to a [`Route`](./route.md), a [`Service`](./service.md) or a [`Consumer`](./consumer.md).
+This represents the configuration of the plugins that are executed during the HTTP request/response lifecycle. A **Plugin** configuration can be bound directly to a [`Route`](./route.md), a [`Service`](./service.md) or a [`Consumer`](./consumer.md).
-**Note**: While configuring the same plugin, only one copy of the configuration is valid. The order of precedence is always `Consumer` > `Route` > `Service`.
+:::note
-While [configuring APISIX](./apisix.md#configuring-apisix), you can declare the Plugins that are supported by the local APISIX node.
+While configuring the same plugin, only one copy of the configuration is valid. The order of precedence is always `Consumer` > `Route` > `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.
+While [configuring APISIX](./apisix.md#configuring-apisix), you can declare the Plugins that are supported by the local APISIX node. 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.
-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`).
+## Adding a Plugin
-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.
+For adding new plugins based on existing plugins, copy the data in the `plugins` node from the default configuration file `conf/config-default.yaml` to your configuration file (`conf/config.yaml`).
-The order in which Plugins are run is determined by its configured priorities:
+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 = {
@@ -47,7 +47,7 @@ local _M = {
}
```
-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.
+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 holding the configuration items for the different Plugins.
```json
{
@@ -66,7 +66,7 @@ A Plugin configuration is submitted as part of the Route or Service and is place
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.
+A warning level log as shown below indicates that the request was rejected by the Plugin.
```shell
ip-restriction exits with http status code 403
@@ -74,17 +74,15 @@ ip-restriction exits with http status code 403
## Hot Reload
-APISIX Plugins are hot-loaded.
-
-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.
-
-To hot-reload, you can send an HTTP request through the [Admin API](../admin-api.md):
+APISIX Plugins are hot-loaded. 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. 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 a configured Plugin is disabled, 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
diff --git a/docs/en/latest/architecture-design/route.md b/docs/en/latest/terminology/route.md
similarity index 89%
rename from docs/en/latest/architecture-design/route.md
rename to docs/en/latest/terminology/route.md
index e287e99..685c8ce 100644
--- a/docs/en/latest/architecture-design/route.md
+++ b/docs/en/latest/terminology/route.md
@@ -21,11 +21,13 @@ title: Route
#
-->
-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).
+## Description
+
+Routes match the client's request based on defined rules, load and execute the corresponding [plugins](./plugin.md), and forwards the request to the specified [Upstream](./upstream.md).
A Route mainly consists of three parts:
-1. Matching rules (uri, host, remote address)
+1. Matching rules (`uri`, `host`, `remote address`)
2. Plugin configuration (current-limit, rate-limit)
3. Upstream information
@@ -39,6 +41,8 @@ When Routes have repetitive configurations (say, enabling the same plugin config
These shortcomings are independently abstracted in APISIX by two concepts: [Service](service.md) and [Upstream](upstream.md).
+## Example
+
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
@@ -67,4 +71,6 @@ Server: APISIX web server
A successful response indicates that the route was created.
+## Configuration
+
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/terminology/router.md
similarity index 86%
rename from docs/en/latest/architecture-design/router.md
rename to docs/en/latest/terminology/router.md
index 58db1a6..2427396 100644
--- a/docs/en/latest/architecture-design/router.md
+++ b/docs/en/latest/terminology/router.md
@@ -21,13 +21,15 @@ title: Router
#
-->
+## Description
+
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).
+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`.
+## Configuration
-It can have the following configurations:
+A Router can have the following configurations:
- `apisix.router.http`: The HTTP request route. It can take the following values:
@@ -35,7 +37,7 @@ It can have the following configurations:
- `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.
+ - `Any filter attribute`: This 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).
diff --git a/docs/en/latest/architecture-design/script.md b/docs/en/latest/terminology/script.md
similarity index 89%
rename from docs/en/latest/architecture-design/script.md
rename to docs/en/latest/terminology/script.md
index 3e77b28..793a5ac 100644
--- a/docs/en/latest/architecture-design/script.md
+++ b/docs/en/latest/terminology/script.md
@@ -21,13 +21,15 @@ title: Script
#
-->
+## Description
+
Scripts lets you write arbitrary Lua code or directly call existing plugins and execute them during the HTTP request/response lifecycle.
A Script configuration can be directly bound to a [Route](./route.md).
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.
-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.
+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/terminology/service.md
similarity index 93%
rename from docs/en/latest/architecture-design/service.md
rename to docs/en/latest/terminology/service.md
index 019bcd5..16587f5 100644
--- a/docs/en/latest/architecture-design/service.md
+++ b/docs/en/latest/terminology/service.md
@@ -21,6 +21,8 @@ title: Service
#
-->
+## Description
+
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.
@@ -29,7 +31,9 @@ The relationship between Routes and a Service is usually N:1 as shown in the ima
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 it to the Routes with the ids `100` and `101`.
+## Examples
+
+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
@@ -86,4 +90,5 @@ curl http://127.0.0.1:9080/apisix/admin/routes/102 -H 'X-API-KEY: edd1c9f034335f
}'
```
-**Note**: When a Route and a Service enable the same Plugin, the one defined in the Route is given the higher priority.
+:::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/terminology/upstream.md
similarity index 98%
rename from docs/en/latest/architecture-design/upstream.md
rename to docs/en/latest/terminology/upstream.md
index e00bd88..09783b5 100644
--- a/docs/en/latest/architecture-design/upstream.md
+++ b/docs/en/latest/terminology/upstream.md
@@ -21,6 +21,8 @@ title: Upstream
#
-->
+## Description
+
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.
@@ -31,7 +33,7 @@ By creating an Upstream object and referencing it by `upstream_id` in the Route,
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
+## Configuration
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).
@@ -82,6 +84,8 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
+## Example
+
The example below shows how you can configure a health check:
```shell
@@ -122,7 +126,7 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
You can learn more about health checks [here](../health-check.md).
-The examples below shows configurations which uses different `hash_on` types.
+The examples below show configurations that use different `hash_on` types.
#### Consumer