kayx23 commented on code in PR #12179:
URL: https://github.com/apache/apisix/pull/12179#discussion_r2063111868
##########
docs/en/latest/deployment-modes.md:
##########
@@ -111,23 +111,77 @@ This method is more suitable for two types of users:
1. Kubernetes(k8s)：Declarative API that dynamically updates the routing rules
with a full yaml configuration.
2. Different configuration centers: There are many implementations of the
configuration center, such as Consul, etc., using the full yaml file for
intermediate conversion.
-The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
+### Modes
-*Note*: Reloading and updating routing rules are all hot memory updates. There
is no replacement of working processes, since it's a hot update.
+Now, we have two standalone running modes, file-driven and API-driven.
-Since the current Admin API is based on the etcd configuration center
solution, enable Admin API is not allowed when the Standalone mode is enabled.
+1. The file-driven mode is the kind APISIX has always supported.
-Standalone mode can only be enabled when we set the role of APISIX as data
plane. We set `deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+ The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
-Refer to the example below:
+ *Note*: Reloading and updating routing rules are all hot memory updates.
There is no replacement of working processes, since it's a hot update.
-```yaml
-deployment:
- role: data_plane
- role_data_plane:
- config_provider: yaml
-#END
-```
+ This requires we set the APISIX role to data plane. That is, set
`deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+
+ Refer to the example below:
+
+ ```yaml
+ deployment:
+ role: data_plane
+ role_data_plane:
+ config_provider: yaml
+ #END
+ ```
+
+ This makes it possible to disable the Admin API and discover configuration
changes and reloads based on the local file system.
+
+2. The API-driven is an emerging paradigm for standalone.
+
+ The routing rules will be entirely in memory and not in a file, and it
will need to be updated using the dedicated Standalone Admin API.
+
+ I.e. we need to send an HTTP PUT request to this API containing the
configuration in JSON or YAML format, which will flush the configuration used
by each worker in the current APISIX instance.
+
+ Changes will overwrite the entire configuration and take effect
immediately, no reboot is required as it is hot updated.
Review Comment:
```suggestion
Changes will overwrite the entire configuration and take effect
immediately without requiring a reboot, as it is hot updated.
```
##########
docs/en/latest/deployment-modes.md:
##########
@@ -111,23 +111,77 @@ This method is more suitable for two types of users:
1. Kubernetes(k8s)：Declarative API that dynamically updates the routing rules
with a full yaml configuration.
2. Different configuration centers: There are many implementations of the
configuration center, such as Consul, etc., using the full yaml file for
intermediate conversion.
-The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
+### Modes
-*Note*: Reloading and updating routing rules are all hot memory updates. There
is no replacement of working processes, since it's a hot update.
+Now, we have two standalone running modes, file-driven and API-driven.
-Since the current Admin API is based on the etcd configuration center
solution, enable Admin API is not allowed when the Standalone mode is enabled.
+1. The file-driven mode is the kind APISIX has always supported.
-Standalone mode can only be enabled when we set the role of APISIX as data
plane. We set `deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+ The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
-Refer to the example below:
+ *Note*: Reloading and updating routing rules are all hot memory updates.
There is no replacement of working processes, since it's a hot update.
-```yaml
-deployment:
- role: data_plane
- role_data_plane:
- config_provider: yaml
-#END
-```
+ This requires we set the APISIX role to data plane. That is, set
`deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+
+ Refer to the example below:
+
+ ```yaml
+ deployment:
+ role: data_plane
+ role_data_plane:
+ config_provider: yaml
+ #END
+ ```
+
+ This makes it possible to disable the Admin API and discover configuration
changes and reloads based on the local file system.
+
+2. The API-driven is an emerging paradigm for standalone.
+
+ The routing rules will be entirely in memory and not in a file, and it
will need to be updated using the dedicated Standalone Admin API.
+
+ I.e. we need to send an HTTP PUT request to this API containing the
configuration in JSON or YAML format, which will flush the configuration used
by each worker in the current APISIX instance.
+
+ Changes will overwrite the entire configuration and take effect
immediately, no reboot is required as it is hot updated.
+
+ This requires we set the APISIX role to traditional (since we need to
start both the API gateway and the Admin API endpoint) and use the yaml config
provider. That is, set `deployment.role` to `traditional`, and set
`deployment.role_traditional.config_provider` to `yaml`
+
+ Refer to the example below:
+
+ ```yaml
+ deployment:
+ role: traditional
+ role_traditional:
+ config_provider: yaml
+ #END
+ ```
+
+ This disables the local file source of configuration in favor of the
API.When APISIX starts, it uses the empty configuration until you update it via
the API.
Review Comment:
```suggestion
This disables the local file source of configuration in favor of the
API. When APISIX starts, it uses the empty configuration until you update it
via the API.
```
##########
docs/en/latest/deployment-modes.md:
##########
@@ -27,11 +27,11 @@ description: Documentation about the three deployment modes
of Apache APISIX.
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. |
+| 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 / traditional | The `data_plane` means
loading the configuration from a local YAML file. And `traditional` means
configure via API. |
Review Comment:
```suggestion
| standalone | data_plane / traditional | The `data_plane` mode loads
configuration from a local YAML file, while the traditional mode expects
configuration through Admin API. |
```
##########
docs/en/latest/deployment-modes.md:
##########
@@ -111,23 +111,77 @@ This method is more suitable for two types of users:
1. Kubernetes(k8s)：Declarative API that dynamically updates the routing rules
with a full yaml configuration.
2. Different configuration centers: There are many implementations of the
configuration center, such as Consul, etc., using the full yaml file for
intermediate conversion.
-The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
+### Modes
-*Note*: Reloading and updating routing rules are all hot memory updates. There
is no replacement of working processes, since it's a hot update.
+Now, we have two standalone running modes, file-driven and API-driven.
-Since the current Admin API is based on the etcd configuration center
solution, enable Admin API is not allowed when the Standalone mode is enabled.
+1. The file-driven mode is the kind APISIX has always supported.
-Standalone mode can only be enabled when we set the role of APISIX as data
plane. We set `deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+ The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
-Refer to the example below:
+ *Note*: Reloading and updating routing rules are all hot memory updates.
There is no replacement of working processes, since it's a hot update.
-```yaml
-deployment:
- role: data_plane
- role_data_plane:
- config_provider: yaml
-#END
-```
+ This requires we set the APISIX role to data plane. That is, set
`deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+
+ Refer to the example below:
+
+ ```yaml
+ deployment:
+ role: data_plane
+ role_data_plane:
+ config_provider: yaml
+ #END
+ ```
+
+ This makes it possible to disable the Admin API and discover configuration
changes and reloads based on the local file system.
+
+2. The API-driven is an emerging paradigm for standalone.
+
+ The routing rules will be entirely in memory and not in a file, and it
will need to be updated using the dedicated Standalone Admin API.
+
+ I.e. we need to send an HTTP PUT request to this API containing the
configuration in JSON or YAML format, which will flush the configuration used
by each worker in the current APISIX instance.
+
+ Changes will overwrite the entire configuration and take effect
immediately, no reboot is required as it is hot updated.
+
+ This requires we set the APISIX role to traditional (since we need to
start both the API gateway and the Admin API endpoint) and use the yaml config
provider. That is, set `deployment.role` to `traditional`, and set
`deployment.role_traditional.config_provider` to `yaml`
+
+ Refer to the example below:
+
+ ```yaml
+ deployment:
+ role: traditional
+ role_traditional:
+ config_provider: yaml
+ #END
+ ```
+
+ This disables the local file source of configuration in favor of the
API.When APISIX starts, it uses the empty configuration until you update it via
the API.
+
+ The following are API endpoints:
+
+ ```text
+ ## Update configuration
+ ## The conf_version is not required, if it is not entered by the client,
the current 10-digit epoch time is used by default.
+ curl -X PUT http://127.0.0.1:9180/apisix/admin/configs?conf_version=1234 \
+ -H "X-API-KEY: <apikey>"
+ -H "Content-Type: application/json" ## or application/yaml
+ --data-binary @config.json
+
+ ## Get latest configuration
+ curl -X GET http://127.0.0.1:9180/apisix/admin/configs
+ -H "X-API-KEY: <apikey>"
+ -H "Accept: application/json" ## or application/yaml
+ ```
+
+ The update API checks our inputs and throws an error if they are
incorrect. Returns `202 Accpeted` if the configuration was accepted, and
returns the latest configuration version via the `X-APISIX-Conf-Version` header.
+
+ The get API also returns the version number via the
`X-APISIX-Conf-Version` header, and returns a response body containing the
configuration in a specific format as requested by the client `Accept` header.
+
+ These APIs follow the security requirements of the Admin API exactly, i.e.
APIKey, TLS/mTLS, CORS, IP allowlist, etc., nothing special.
Review Comment:
```suggestion
These APIs apply the same security requirements as the Admin API — such
as API key, TLS/mTLS, CORS, and IP allowlist — no changes or additions.
```
##########
docs/en/latest/deployment-modes.md:
##########
@@ -111,23 +111,77 @@ This method is more suitable for two types of users:
1. Kubernetes(k8s)：Declarative API that dynamically updates the routing rules
with a full yaml configuration.
2. Different configuration centers: There are many implementations of the
configuration center, such as Consul, etc., using the full yaml file for
intermediate conversion.
-The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
+### Modes
-*Note*: Reloading and updating routing rules are all hot memory updates. There
is no replacement of working processes, since it's a hot update.
+Now, we have two standalone running modes, file-driven and API-driven.
-Since the current Admin API is based on the etcd configuration center
solution, enable Admin API is not allowed when the Standalone mode is enabled.
+1. The file-driven mode is the kind APISIX has always supported.
-Standalone mode can only be enabled when we set the role of APISIX as data
plane. We set `deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+ The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
-Refer to the example below:
+ *Note*: Reloading and updating routing rules are all hot memory updates.
There is no replacement of working processes, since it's a hot update.
-```yaml
-deployment:
- role: data_plane
- role_data_plane:
- config_provider: yaml
-#END
-```
+ This requires we set the APISIX role to data plane. That is, set
`deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
Review Comment:
```suggestion
This requires us to set the APISIX role to data plane. That is, set
`deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
```
##########
docs/en/latest/deployment-modes.md:
##########
@@ -111,23 +111,77 @@ This method is more suitable for two types of users:
1. Kubernetes(k8s)：Declarative API that dynamically updates the routing rules
with a full yaml configuration.
2. Different configuration centers: There are many implementations of the
configuration center, such as Consul, etc., using the full yaml file for
intermediate conversion.
-The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
+### Modes
-*Note*: Reloading and updating routing rules are all hot memory updates. There
is no replacement of working processes, since it's a hot update.
+Now, we have two standalone running modes, file-driven and API-driven.
-Since the current Admin API is based on the etcd configuration center
solution, enable Admin API is not allowed when the Standalone mode is enabled.
+1. The file-driven mode is the kind APISIX has always supported.
-Standalone mode can only be enabled when we set the role of APISIX as data
plane. We set `deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+ The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
-Refer to the example below:
+ *Note*: Reloading and updating routing rules are all hot memory updates.
There is no replacement of working processes, since it's a hot update.
-```yaml
-deployment:
- role: data_plane
- role_data_plane:
- config_provider: yaml
-#END
-```
+ This requires we set the APISIX role to data plane. That is, set
`deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+
+ Refer to the example below:
+
+ ```yaml
+ deployment:
+ role: data_plane
+ role_data_plane:
+ config_provider: yaml
+ #END
+ ```
+
+ This makes it possible to disable the Admin API and discover configuration
changes and reloads based on the local file system.
+
+2. The API-driven is an emerging paradigm for standalone.
+
+ The routing rules will be entirely in memory and not in a file, and it
will need to be updated using the dedicated Standalone Admin API.
+
+ I.e. we need to send an HTTP PUT request to this API containing the
configuration in JSON or YAML format, which will flush the configuration used
by each worker in the current APISIX instance.
+
+ Changes will overwrite the entire configuration and take effect
immediately, no reboot is required as it is hot updated.
+
+ This requires we set the APISIX role to traditional (since we need to
start both the API gateway and the Admin API endpoint) and use the yaml config
provider. That is, set `deployment.role` to `traditional`, and set
`deployment.role_traditional.config_provider` to `yaml`
+
+ Refer to the example below:
+
+ ```yaml
+ deployment:
+ role: traditional
+ role_traditional:
+ config_provider: yaml
+ #END
+ ```
+
+ This disables the local file source of configuration in favor of the
API.When APISIX starts, it uses the empty configuration until you update it via
the API.
+
+ The following are API endpoints:
+
+ ```text
+ ## Update configuration
+ ## The conf_version is not required, if it is not entered by the client,
the current 10-digit epoch time is used by default.
+ curl -X PUT http://127.0.0.1:9180/apisix/admin/configs?conf_version=1234 \
+ -H "X-API-KEY: <apikey>"
+ -H "Content-Type: application/json" ## or application/yaml
+ --data-binary @config.json
+
+ ## Get latest configuration
+ curl -X GET http://127.0.0.1:9180/apisix/admin/configs
+ -H "X-API-KEY: <apikey>"
+ -H "Accept: application/json" ## or application/yaml
+ ```
+
+ The update API checks our inputs and throws an error if they are
incorrect. Returns `202 Accpeted` if the configuration was accepted, and
returns the latest configuration version via the `X-APISIX-Conf-Version` header.
Review Comment:
```suggestion
The update API validates the input and returns an error if it is
invalid. If the configuration is accepted, it responds with a `202 Accepted`
status and includes the latest configuration version in the`
X-APISIX-Conf-Version` header.
```
##########
docs/en/latest/deployment-modes.md:
##########
@@ -111,23 +111,77 @@ This method is more suitable for two types of users:
1. Kubernetes(k8s)：Declarative API that dynamically updates the routing rules
with a full yaml configuration.
2. Different configuration centers: There are many implementations of the
configuration center, such as Consul, etc., using the full yaml file for
intermediate conversion.
-The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
+### Modes
-*Note*: Reloading and updating routing rules are all hot memory updates. There
is no replacement of working processes, since it's a hot update.
+Now, we have two standalone running modes, file-driven and API-driven.
-Since the current Admin API is based on the etcd configuration center
solution, enable Admin API is not allowed when the Standalone mode is enabled.
+1. The file-driven mode is the kind APISIX has always supported.
-Standalone mode can only be enabled when we set the role of APISIX as data
plane. We set `deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+ The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
Review Comment:
```suggestion
The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. At each interval (default: 1
second), APISIX checks for updates to the file. If changes are detected, it
reloads the rules.
```
##########
docs/en/latest/deployment-modes.md:
##########
@@ -111,23 +111,77 @@ This method is more suitable for two types of users:
1. Kubernetes(k8s)：Declarative API that dynamically updates the routing rules
with a full yaml configuration.
2. Different configuration centers: There are many implementations of the
configuration center, such as Consul, etc., using the full yaml file for
intermediate conversion.
-The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
+### Modes
-*Note*: Reloading and updating routing rules are all hot memory updates. There
is no replacement of working processes, since it's a hot update.
+Now, we have two standalone running modes, file-driven and API-driven.
-Since the current Admin API is based on the etcd configuration center
solution, enable Admin API is not allowed when the Standalone mode is enabled.
+1. The file-driven mode is the kind APISIX has always supported.
-Standalone mode can only be enabled when we set the role of APISIX as data
plane. We set `deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+ The routing rules in the `conf/apisix.yaml` file are loaded into memory
immediately after the APISIX node service starts. And every time interval
(default 1 second), will try to detect whether the file content is updated, if
there is an update, reload the rule.
-Refer to the example below:
+ *Note*: Reloading and updating routing rules are all hot memory updates.
There is no replacement of working processes, since it's a hot update.
-```yaml
-deployment:
- role: data_plane
- role_data_plane:
- config_provider: yaml
-#END
-```
+ This requires we set the APISIX role to data plane. That is, set
`deployment.role` to `data_plane` and
`deployment.role_data_plane.config_provider` to `yaml`.
+
+ Refer to the example below:
+
+ ```yaml
+ deployment:
+ role: data_plane
+ role_data_plane:
+ config_provider: yaml
+ #END
+ ```
+
+ This makes it possible to disable the Admin API and discover configuration
changes and reloads based on the local file system.
+
+2. The API-driven is an emerging paradigm for standalone.
+
+ The routing rules will be entirely in memory and not in a file, and it
will need to be updated using the dedicated Standalone Admin API.
+
+ I.e. we need to send an HTTP PUT request to this API containing the
configuration in JSON or YAML format, which will flush the configuration used
by each worker in the current APISIX instance.
+
+ Changes will overwrite the entire configuration and take effect
immediately, no reboot is required as it is hot updated.
+
+ This requires we set the APISIX role to traditional (since we need to
start both the API gateway and the Admin API endpoint) and use the yaml config
provider. That is, set `deployment.role` to `traditional`, and set
`deployment.role_traditional.config_provider` to `yaml`
Review Comment:
```suggestion
This requires us to set the APISIX role to traditional (since we need to
start both the API gateway and the Admin API endpoint) and use the yaml config
provider. That is, set `deployment.role` to `traditional` and
`deployment.role_traditional.config_provider` to `yaml`.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscr...@apisix.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
