AlinsRan commented on code in PR #12214: URL: https://github.com/apache/apisix/pull/12214#discussion_r2096799974
########## docs/en/latest/deployment-modes.md: ########## @@ -115,73 +115,162 @@ This method is more suitable for two types of users: Now, we have two standalone running modes, file-driven and API-driven. -1. The file-driven mode is the kind APISIX has always supported. +#### File-driven - 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. +The file-driven mode is the kind APISIX has always supported. - *Note*: Reloading and updating routing rules are all hot memory updates. There is no replacement of working processes, since it's a hot update. +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. - 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`. +*Note*: Reloading and updating routing rules are all hot memory updates. There is no replacement of working processes, since it's a hot update. - Refer to the example below: +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`. - ```yaml - deployment: - role: data_plane - role_data_plane: - config_provider: yaml - #END - ``` +Refer to the example below: - This makes it possible to disable the Admin API and discover configuration changes and reloads based on the local file system. +```yaml +deployment: + role: data_plane + role_data_plane: + config_provider: yaml +``` -2. The API-driven is an emerging paradigm for standalone. +This makes it possible to disable the Admin API and discover configuration changes and reloads based on the local file system. - 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. +#### API-driven (Experimental) - 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. +##### Overview - Changes will overwrite the entire configuration and take effect immediately without requiring a reboot, as it is hot updated. +The API-driven mode is an emerging paradigm for standalone deployment. The routing rules are entirely in memory and not in a file, requiring updates through the dedicated Standalone Admin API. Changes overwrite the entire configuration and take effect immediately without requiring a reboot, as it is hot updated. - 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`. +##### Configuration - Refer to the example below: +To enable this mode, set the APISIX role to `traditional` (to start both the API gateway and the Admin API endpoint) and use the YAML config provider. Example configuration: - ```yaml - deployment: - role: traditional - role_traditional: - config_provider: yaml - #END - ``` +```yaml +deployment: + role: traditional + role_traditional: + config_provider: yamls Review Comment: fixed. ########## docs/en/latest/deployment-modes.md: ########## @@ -115,73 +115,162 @@ This method is more suitable for two types of users: Now, we have two standalone running modes, file-driven and API-driven. -1. The file-driven mode is the kind APISIX has always supported. +#### File-driven - 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. +The file-driven mode is the kind APISIX has always supported. - *Note*: Reloading and updating routing rules are all hot memory updates. There is no replacement of working processes, since it's a hot update. +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. - 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`. +*Note*: Reloading and updating routing rules are all hot memory updates. There is no replacement of working processes, since it's a hot update. - Refer to the example below: +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`. - ```yaml - deployment: - role: data_plane - role_data_plane: - config_provider: yaml - #END - ``` +Refer to the example below: - This makes it possible to disable the Admin API and discover configuration changes and reloads based on the local file system. +```yaml +deployment: + role: data_plane + role_data_plane: + config_provider: yaml +``` -2. The API-driven is an emerging paradigm for standalone. +This makes it possible to disable the Admin API and discover configuration changes and reloads based on the local file system. - 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. +#### API-driven (Experimental) - 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. +##### Overview - Changes will overwrite the entire configuration and take effect immediately without requiring a reboot, as it is hot updated. +The API-driven mode is an emerging paradigm for standalone deployment. The routing rules are entirely in memory and not in a file, requiring updates through the dedicated Standalone Admin API. Changes overwrite the entire configuration and take effect immediately without requiring a reboot, as it is hot updated. - 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`. +##### Configuration - Refer to the example below: +To enable this mode, set the APISIX role to `traditional` (to start both the API gateway and the Admin API endpoint) and use the YAML config provider. Example configuration: - ```yaml - deployment: - role: traditional - role_traditional: - config_provider: yaml - #END - ``` +```yaml +deployment: + role: traditional + role_traditional: + config_provider: yamls +``` + +This disables the local file source of configuration in favor of the API. When APISIX starts, it uses an empty configuration until updated via the API. - 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. +##### API Endpoints - The following are API endpoints: +* Per-resource-type conf_version - ```shell - ## 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 + Use `<resource>_conf_version` to indicate the client’s current version for each resource type (e.g. routes, upstreams, services, etc.). - ## 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 + ```json + { + "routes_conf_version": 12, + "upstreams_conf_version": 102, + "routes": [], + "upstreams": [] + } ``` - 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. + APISIX compares each provided `<resource>_conf_version` against its in-memory `<resource>_conf_version` for that resource type: + + - **Greater than** the current `conf_version` + If your `<resource>_conf_version` is **higher**, APISIX will **rebuild/reset** that resource type’s data to match your payload. Review Comment: done. -- 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
