You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sy...@apache.org on 2022/08/24 01:15:14 UTC
[apisix] branch master updated: docs: update Architecture docs (#7568)
This is an automated email from the ASF dual-hosted git repository.
sylviasu 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 cd511744d docs: update Architecture docs (#7568)
cd511744d is described below
commit cd511744df9588d4d4b3480c40316a51716057d7
Author: Navendu Pottekkat <na...@gmail.com>
AuthorDate: Wed Aug 24 06:45:07 2022 +0530
docs: update Architecture docs (#7568)
* docs: update Architecture docs
* move deployment guide and reference in installation docs
* add license header
---
docs/en/latest/architecture-design/apisix.md | 34 +++--
.../latest/architecture-design/deployment-role.md | 160 ---------------------
docs/en/latest/config.json | 28 ++--
docs/en/latest/deployment-modes.md | 157 ++++++++++++++++++++
docs/en/latest/installation-guide.md | 4 +
5 files changed, 195 insertions(+), 188 deletions(-)
diff --git a/docs/en/latest/architecture-design/apisix.md b/docs/en/latest/architecture-design/apisix.md
index 0a6139c6f..2e76aab68 100644
--- a/docs/en/latest/architecture-design/apisix.md
+++ b/docs/en/latest/architecture-design/apisix.md
@@ -1,7 +1,11 @@
---
-title: APISIX
+title: Architecture
+keywords:
+ - API gateway
+ - Apache APISIX
+ - APISIX architecture
+description: Architecture of Apache APISIX—the Cloud Native API Gateway.
---
-
<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -21,25 +25,27 @@ title: APISIX
#
-->
-## Apache APISIX : Software Architecture
+APISIX is built on top of Nginx and [ngx_lua](https://github.com/openresty/lua-nginx-module) leveraging the power offered by LuaJIT. See [Why Apache APISIX chose Nginx and Lua to build API Gateway?](https://apisix.apache.org/blog/2021/08/25/why-apache-apisix-chose-nginx-and-lua/).
+
+
-
+APISIX has two main parts:
-Apache APISIX is a dynamic, real-time, high-performance cloud-native API gateway. It is built on top of NGINX + ngx_lua technology and leverages the power offered by LuaJIT. [Why Apache APISIX chose Nginx and Lua to build API Gateway?](https://apisix.apache.org/blog/2021/08/25/why-apache-apisix-chose-nginx-and-lua/)
+1. APISIX core, Lua plugin, multi-language Plugin runtime, and the WASM plugin runtime.
+2. Built-in Plugins that adds features for observability, security, traffic control, etc.
-APISIX is divided into two main parts:
+The APISIX core handles the important functions like matching Routes, load balancing, service discovery, configuration management, and provides a management API. It also includes APISIX Plugin runtime supporting Lua and multilingual Plugins (Go, Java , Python, JavaScript, etc) including the experimental WASM Plugin runtime.
-1. APISIX core, including Lua plugin, multi-language plugin runtime, Wasm plugin runtime, etc.
-2. Feature-rich variety of built-in plugins: including observability, security, traffic control, etc.
+APISIX also has a set of [built-in Plugins](https://apisix.apache.org/docs/apisix/plugins/batch-requests) that adds features like authentication, security, observability, etc. They are written in Lua.
-In the APISIX core, important functions such as route matching, load balancing, service discovery, management API, and basic modules such as configuration management are provided. In addition, APISIX plugin runtime is also included, providing the runtime framework for native Lua plugins and multilingual plugins, as well as the experimental Wasm plugin runtime, etc. APISIX multilingual plugin runtime provides support for various development languages, such as Golang, Java, Python, JS, etc.
+## Request handling process
-APISIX currently has various plugins built in, covering various areas of API gateways, such as authentication and authentication, security, observability, traffic management, multi-protocol access, and so on. The plugins currently built into APISIX are implemented using native Lua. For the introduction and usage of each plugin, please check the [documentation](https://apisix.apache.org/docs/apisix/plugins/batch-requests) of the relevant plugin.
+The diagram below shows how APISIX handles an incoming request and applies corresponding Plugins:
-## Plugin Loading Process
+
-
+## Plugin hierarchy
-## Plugin Hierarchy Structure
+The chart below shows the order in which different types of Plugin are applied to a request:
-
+
diff --git a/docs/en/latest/architecture-design/deployment-role.md b/docs/en/latest/architecture-design/deployment-role.md
deleted file mode 100644
index 465675e83..000000000
--- a/docs/en/latest/architecture-design/deployment-role.md
+++ /dev/null
@@ -1,160 +0,0 @@
----
-title: Deployment Role
----
-
-<!--
-#
-# 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.
-#
--->
-
-## Concept
-
-Previously, the DP (Data Plane) and the CP (Control Plane) are not separate explicitly.
-
-Although we clearly distinguish the different responsibilities of DP and CP in the documentation, not everyone has correctly deployed APISIX in the production environment.
-
-Therefore, we introduce new concepts called deployment modes/roles, to help users deploy APISIX easily and safely.
-
-APISIX under different deployment modes will act differently.
-
-The table below shows the relationship among deployment modes and roles:
-
-| Deployment Modes | Role | Description |
-|------------------|----------------------------|------------------------------------------------------------------------------------------|
-| traditional | traditional | DP + CP are deployed together by default. People need to disable `enable_admin` manually |
-| decoupled | data_plane / control_plane | DP and CP are deployed independently. |
-| standalone | data_plane | Only DP, load the all configurations from local yaml file |
-
-## Deployment Modes
-
-### Traditional
-
-
-
-In the traditional deployment mode, one instance can be both DP & CP.
-
-There will be a `conf server` listens on UNIX socket and acts as a proxy between APISIX and etcd.
-
-Both the DP part and CP part of the instance will connect to the `conf server` via HTTP protocol.
-
-Here is the example of configuration:
-
-```yaml title="conf/config.yaml"
-deployment:
- role: traditional
- role_traditional:
- config_provider: etcd
- etcd:
- host:
- - http://xxxx
- prefix: /apisix
- timeout: 30
-```
-
-### Decoupled
-
-
-
-The instance deployed as data_plane will:
-
-1. Fetch configurations from the CP, the default port is 9280
-2. Before the DP service starts, it will perform a health check on all CP addresses
- - If all CP addresses are unavailable, the startup fails and an exception message is output to the screen.
- - If at least one CP address is available, print the unhealthy CP check result log, and then start the APISIX service.
- - If all CP addresses are normal, start the APISIX service normally.
-3. Handle user requests.
-
-Here is the example of configuration:
-
-```yaml title="conf/config.yaml"
-deployment:
- role: data_plane
- role_data_plane:
- config_provider: control_plane
- control_plane:
- host:
- - xxxx:9280
- timeout: 30
- certs:
- cert: /path/to/ca-cert
- cert_key: /path/to/ca-cert
- trusted_ca_cert: /path/to/ca-cert
-```
-
-The instance deployed as control_plane will:
-
-1. Listen on 9180 by default, and provide Admin API for Admin user
-2. Provide `conf server` which listens on port 9280 by default. Both the DP instances and this CP instance will connect to the `conf server` via HTTPS enforced by mTLS.
-
-Here is the example of configuration:
-
-```yaml title="conf/config.yaml"
-deployment:
- role: control_plane
- role_control_plan:
- config_provider: etcd
- conf_server:
- listen: 0.0.0.0:9280
- cert: /path/to/ca-cert
- cert_key: /path/to/ca-cert
- client_ca_cert: /path/to/ca-cert
- etcd:
- host:
- - https://xxxx
- prefix: /apisix
- timeout: 30
- certs:
- cert: /path/to/ca-cert
- cert_key: /path/to/ca-cert
- trusted_ca_cert: /path/to/ca-cert
-```
-
-As OpenResty <= 1.21.4 doesn't support sending mTLS request, if you need to accept the connections from APISIX running on these OpenResty versions,
-you need to disable client certificate verification in the CP instance.
-
-Here is the example of configuration:
-
-```yaml title="conf/config.yaml"
-deployment:
- role: control_plane
- role_control_plan:
- config_provider: etcd
- conf_server:
- listen: 0.0.0.0:9280
- cert: /path/to/ca-cert
- cert_key: /path/to/ca-cert
- etcd:
- host:
- - https://xxxx
- prefix: /apisix
- timeout: 30
- certs:
- trusted_ca_cert: /path/to/ca-cert
-```
-
-### Standalone
-
-In this mode, APISIX is deployed as DP and reads configurations from yaml file in the local file system.
-
-Here is the example of configuration:
-
-```yaml title="conf/config.yaml"
-deployment:
- role: data_plane
- role_data_plane:
- config_provider: yaml
-```
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index 939a5cac9..2e406005d 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -2,12 +2,16 @@
"version": "2.15.0",
"sidebar": [
{
- "type": "category",
- "label": "Architecture Design",
- "items": [
- "architecture-design/apisix",
- "architecture-design/deployment-role"
- ]
+ "type": "doc",
+ "id": "getting-started"
+ },
+ {
+ "type": "doc",
+ "id": "installation-guide"
+ },
+ {
+ "type": "doc",
+ "id": "architecture-design/apisix"
},
{
"type": "category",
@@ -25,14 +29,6 @@
"terminology/upstream"
]
},
- {
- "type": "doc",
- "id": "getting-started"
- },
- {
- "type": "doc",
- "id": "installation-guide"
- },
{
"type": "category",
"label": "Plugins",
@@ -244,6 +240,10 @@
"xrpc"
]
},
+ {
+ "type": "doc",
+ "id": "deployment-modes"
+ },
{
"type": "doc",
"id": "health-check"
diff --git a/docs/en/latest/deployment-modes.md b/docs/en/latest/deployment-modes.md
new file mode 100644
index 000000000..ec26a9047
--- /dev/null
+++ b/docs/en/latest/deployment-modes.md
@@ -0,0 +1,157 @@
+---
+title: Deployment modes
+keywords:
+ - API gateway
+ - Apache APISIX
+ - APISIX deployment modes
+description: Documentation about the three deployment modes of Apache APISIX.
+---
+<!--
+#
+# 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.
+#
+-->
+
+APISIX has three different deployment modes for different production use cases. The table below summarises the deployment modes:
+
+| Deployment mode | Roles | Description |
+|-----------------|----------------------------|-----------------------------------------------------------------------------------------------------------|
+| traditional | traditional | Data plane and control plane are deployed together. `enable_admin` attribute should be disabled manually. |
+| decoupled | data_plane / control_plane | Data plane and control plane are deployed independently. |
+| standalone | data_plane | Only data plane is deployed and the configurations are loaded from a local YAML file. |
+
+Each of these deployment modes are explained in detail below.
+
+## Traditional
+
+In the traditional deployment mode, one instance of APISIX will be both the data plane and the control plane.
+
+
+
+There will be a conf server that listens on the UNIX socket and acts as a proxy between APISIX and etcd. Both the data and the control planes connect to this conf server via HTTP.
+
+An example configuration of the traditional deployment mode is shown below:
+
+```yaml title="conf/config.yaml"
+deployment:
+ role: traditional
+ role_traditional:
+ config_provider: etcd
+ etcd:
+ host:
+ - http://${IP}:${Port}
+ prefix: /apisix
+ timeout: 30
+```
+
+## Decoupled
+
+In the decoupled deployment mode the data plane and control plane instances of APISIX are deployed separately. i.e one instance of APISIX is configured to be a data plane and the other to be a control plane.
+
+
+
+The instance of APISIX deployed as the data plane will:
+
+1. Fetch the configuration from the control plane. The default port is `9280`.
+2. Performs a health check on all configured control plane addresses before starting the service.
+ 1. If the control plane addresses are unavailable, the startup fails and an exception is thrown.
+ 2. If at least one control plane address is available, it prints the unhealthy control planes logs, and starts the APISIX service.
+ 3. If all control planes are normal, APISIX service is started normally.
+3. Once the service is started, it will handle the user requests.
+
+The example below shows the configuration of an APISIX instance as data plane in the decoupled mode:
+
+```yaml title="conf/config.yaml"
+deployment:
+ role: data_plane
+ role_data_plane:
+ config_provider: control_plane
+ control_plane:
+ host:
+ - ${IP}:9280
+ timeout: 30
+ certs:
+ cert: /path/to/ca-cert
+ cert_key: /path/to/ca-cert
+ trusted_ca_cert: /path/to/ca-cert
+```
+
+The instance of APISIX deployeas the control plane will:
+
+1. Listen on port `9180` and handle Admin API requests.
+2. Provide the conf server which will listen on port `9280`. Both the control plane and the data plane will connect to this via HTTPS enforced by mTLS.
+
+The example below shows the configuration of an APISIX instance as control plane in the decoupled mode:
+
+```yaml title="conf/config.yaml"
+deployment:
+ role: control_plane
+ role_control_plan:
+ config_provider: etcd
+ conf_server:
+ listen: 0.0.0.0:9280
+ cert: /path/to/ca-cert
+ cert_key: /path/to/ca-cert
+ client_ca_cert: /path/to/ca-cert
+ etcd:
+ host:
+ - https://${IP}:${Port}
+ prefix: /apisix
+ timeout: 30
+ certs:
+ cert: /path/to/ca-cert
+ cert_key: /path/to/ca-cert
+ trusted_ca_cert: /path/to/ca-cert
+```
+
+:::tip
+
+As OpenResty <= 1.21.4 does not support sending mTLS requests, to accept connections from APISIX running on these OpenResty versions, you need to disable the client certificate verification in the control plane instance as shown below:
+
+```yaml title="conf/config.yaml"
+deployment:
+ role: control_plane
+ role_control_plan:
+ config_provider: etcd
+ conf_server:
+ listen: 0.0.0.0:9280
+ cert: /path/to/ca-cert
+ cert_key: /path/to/ca-cert
+ etcd:
+ host:
+ - https://${IP}:${Port}
+ prefix: /apisix
+ timeout: 30
+ certs:
+ trusted_ca_cert: /path/to/ca-cert
+```
+
+:::
+
+## Standalone
+
+In the standalone deployment mode, APISIX is deployed as a data plane and it reads in configurations from a YAML file (`apisix.yaml`) in the local file system.
+
+This deployment mode is useful when you have to declaratively define the configuration or when you are using a different configuration center other than etcd.
+
+To configure APISIX in standalone mode:
+
+```yaml title="conf/config.yaml"
+deployment:
+ role: data_plane
+ role_data_plane:
+ config_provider: yaml
+```
diff --git a/docs/en/latest/installation-guide.md b/docs/en/latest/installation-guide.md
index 775ceb5b3..3ba06bb1d 100644
--- a/docs/en/latest/installation-guide.md
+++ b/docs/en/latest/installation-guide.md
@@ -256,6 +256,10 @@ The `conf/nginx.conf` file is automatically generated and should not be modified
:::
+### APISIX deployment modes
+
+APISIX has three different deployment modes for different use cases. To learn more and configure deployment modes, see the [documentation](./deployment-modes.md).
+
### Updating Admin API key
It is recommended to modify the Admin API key to ensure security.