docs: update docs for the removal of config-default.yaml (3.10.0) (#11504)

kayx23 · web-flow · commit 5433dce25de6 · 2024-08-22T14:18:36.000+08:00
diff --git a/docs/en/latest/FAQ.md b/docs/en/latest/FAQ.md
@@ -756,15 +756,15 @@ deployment:
     password: etcd_password     # password for etcd
 ```
 
-For other ETCD configurations, such as expiration times, retries, and so on, you can refer to the `ETCD` section in the `conf/config-default.yaml` file.
+For other ETCD configurations, such as expiration times, retries, and so on, you can refer to the `etcd` section in the sample configuration `conf/config.yaml.example` file.
 
-## What is the difference between SSLs and tls.client_cert in upstream configurations, and ssl_trusted_certificate in config-default.yaml?
+## What is the difference between SSLs, `tls.client_cert` in upstream configurations, and `ssl_trusted_certificate` in `config.yaml`?
 
 The `ssls` is managed through the `/apisix/admin/ssls` API. It's used for managing TLS certificates. These certificates may be used during TLS handshake (between Apache APISIX and its clients). Apache APISIX uses Server Name Indication (SNI) to differentiate between certificates of different domains.
 
 The `tls.client_cert`, `tls.client_key`, and `tls.client_cert_id` in upstream are used for mTLS communication with the upstream.
 
-The `ssl_trusted_certificate` in config-default.yaml configures a trusted CA certificate. It is used for verifying some certificates signed by private authorities within APISIX, to avoid APISIX rejects the certificate. Note that it is not used to trust the certificates of APISIX upstream, because APISIX does not verify the legality of the upstream certificates. Therefore, even if the upstream uses an invalid TLS certificate, it can still be accessed without configuring a root certificate.
+The `ssl_trusted_certificate` in `config.yaml` configures a trusted CA certificate. It is used for verifying some certificates signed by private authorities within APISIX, to avoid APISIX rejects the certificate. Note that it is not used to trust the certificates of APISIX upstream, because APISIX does not verify the legality of the upstream certificates. Therefore, even if the upstream uses an invalid TLS certificate, it can still be accessed without configuring a root certificate.
 
 ## Where can I find more answers?
 
diff --git a/docs/en/latest/benchmark.md b/docs/en/latest/benchmark.md
@@ -140,7 +140,7 @@ For more reference on how to run the benchmark test, you can see this [PR](https
 
 :::tip
 
-If you want to run the benchmark with a large number of connections, You may have to update the **keepalive** config in the [conf/config-default.yaml](https://github.com/apache/apisix/blob/master/conf/config-default.yaml#L242). Connections exceeding this number will become short connections. You can run the following command to test the benchmark with a large number of connections:
+If you want to run the benchmark with a large number of connections, You may have to update the [**keepalive**](https://github.com/apache/apisix/blob/master/conf/config.yaml.example#L241) config by adding the configuration to [`config.yaml`](https://github.com/apache/apisix/blob/master/conf/config.yaml) and reload APISIX. Connections exceeding this number will become short connections. You can run the following command to test the benchmark with a large number of connections:
 
 ```bash
 wrk -t200 -c5000 -d30s http://127.0.0.1:9080/hello
diff --git a/docs/en/latest/customize-nginx-configuration.md b/docs/en/latest/customize-nginx-configuration.md
@@ -21,11 +21,11 @@ title: Customize Nginx configuration
 #
 -->
 
-The Nginx configuration used by APISIX is generated via the template file `apisix/cli/ngx_tpl.lua` and the options from `conf/config-default.yaml` / `conf/config.yaml`.
+The Nginx configuration used by APISIX is generated via the template file `apisix/cli/ngx_tpl.lua` and the parameters in `apisix/cli/config.lua` and `conf/config.yaml`.
 
 You can take a look at the generated Nginx configuration in `conf/nginx.conf` after running `./bin/apisix start`.
 
-If you want to customize the Nginx configuration, please read through the `nginx_config` in `conf/config-default.yaml`. You can override the default value in the `conf/config.yaml`. For instance, you can inject some snippets in the `conf/nginx.conf` via configuring the `xxx_snippet` entries:
+If you want to customize the Nginx configuration, please read through the `nginx_config` in `conf/config.default.example`. You can override the default value in the `conf/config.yaml`. For instance, you can inject some snippets in the `conf/nginx.conf` via configuring the `xxx_snippet` entries:
 
 ```yaml
 ...
diff --git a/docs/en/latest/install-dependencies.md b/docs/en/latest/install-dependencies.md
@@ -25,7 +25,7 @@ title: Install Dependencies
 
 - Since v2.0 Apache APISIX would not support the v2 protocol storage to etcd anymore, and the minimum etcd version supported is v3.4.0. What's more, etcd v3 uses gRPC as the messaging protocol, while Apache APISIX uses HTTP(S) to communicate with etcd cluster, so be sure the [etcd gRPC gateway](https://etcd.io/docs/v3.4.0/dev-guide/api_grpc_gateway/) is enabled.
 
-- Now by default Apache APISIX uses HTTP protocol to talk with etcd cluster, which is insecure. Please configure certificate and corresponding private key for your etcd cluster, and use "https" scheme explicitly in the etcd endpoints list in your Apache APISIX configuration, if you want to keep the data secure and integral. See the etcd section in `conf/config-default.yaml` for more details.
+- Now by default Apache APISIX uses HTTP protocol to talk with etcd cluster, which is insecure. Please configure certificate and corresponding private key for your etcd cluster, and use "https" scheme explicitly in the etcd endpoints list in your Apache APISIX configuration, if you want to keep the data secure and integral. See the etcd section in `conf/config.yaml.example` for more details.
 
 - If it is OpenResty 1.19, APISIX will use OpenResty's built-in LuaJIT to run `bin/apisix`; otherwise it will use Lua 5.1. If you encounter `luajit: lj_asm_x86.h:2819: asm_loop_ fixup: Assertion '((intptr_t)target & 15) == 0' failed`, this is a problem with the low version of OpenResty's built-in LuaJIT under certain compilation conditions.
 
diff --git a/docs/en/latest/installation-guide.md b/docs/en/latest/installation-guide.md
@@ -271,7 +271,7 @@ You can configure your APISIX deployment in two ways:
    apisix start -c <path to config file>
    ```
 
-APISIX will use the configurations added in this configuration file and will fall back to the default configuration if anything is not configured.
+APISIX will use the configurations added in this configuration file and will fall back to the default configuration if anything is not configured. The default configurations can be found in `apisix/cli/config.lua` and should not be modified.
 
 For example, to configure the default listening port to be `8000` without changing other configurations, your configuration file could look like this:
 
@@ -297,12 +297,6 @@ deployment:
 
 :::warning
 
-APISIX's default configuration can be found in `conf/config-default.yaml` file and it should not be modified. It is bound to the source code and the configuration should only be changed by the methods mentioned above.
-
-:::
-
-:::warning
-
 The `conf/nginx.conf` file is automatically generated and should not be modified.
 
 :::
diff --git a/docs/en/latest/plugin-develop.md b/docs/en/latest/plugin-develop.md
@@ -117,36 +117,36 @@ local _M = {
 
 Note: The priority of the new plugin cannot be same to any existing ones, you can use the `/v1/schema` method of [control API](./control-api.md#get-v1schema) to view the priority of all plugins. In addition, plugins with higher priority value will be executed first in a given phase (see the definition of `phase` in [choose-phase-to-run](#choose-phase-to-run)). For example, the priority of example-plugin is 0 and the priority of ip-restriction is 3000. Therefore, the ip-restriction plugin will be executed first, then the example-plugin plugin. It's recommended to use priority 1 ~ 99 for your plugin unless you want it to run before some builtin plugins.
 
-In the "__conf/config-default.yaml__" configuration file, the enabled plugins (all specified by plugin name) are listed.
+By default, most APISIX plugins are [enabled](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua):
 
-```yaml
-plugins:                          # plugin list
-  - limit-req
-  - limit-count
-  - limit-conn
-  - key-auth
-  - prometheus
-  - node-status
-  - jwt-auth
-  - zipkin
-  - ip-restriction
-  - grpc-transcode
-  - serverless-pre-function
-  - serverless-post-function
-  - openid-connect
-  - proxy-rewrite
-  - redirect
+```lua title="apisix/cli/config.lua"
+local _M = {
+  ...
+  plugins = {
+    "real-ip",
+    "ai",
+    "client-control",
+    "proxy-control",
+    "request-id",
+    "zipkin",
+    "ext-plugin-pre-req",
+    "fault-injection",
+    "mocking",
+    "serverless-pre-function",
+    ...
+  },
   ...
+}
 ```
 
 Note: the order of the plugins is not related to the order of execution.
 
-To enable your plugin, copy this plugin list into `conf/config.yaml`, and add your plugin name. For instance:
+To enable your custom plugin, add the list of plugins into `conf/config.yaml` and append your plugin name. For instance:
 
 ```yaml
-plugins: # copied from config-default.yaml
-  ...
-  - your-plugin
+plugins:         # see `conf/config.yaml.example` for an example
+  - ...          # add existing plugins
+  - your-plugin  # add your custom plugin
 ```
 
 If your plugin has a new code directory of its own, and you need to redistribute it with the APISIX source code, you will need to modify the `Makefile` to create directory, such as:
diff --git a/docs/en/latest/plugins/aws-lambda.md b/docs/en/latest/plugins/aws-lambda.md
@@ -104,7 +104,7 @@ Server: APISIX/2.10.2
 "Hello, APISIX!"
 ```
 
-Another example of a request where the client communicates with APISIX via HTTP/2 is shown below (make sure you have configured `enable_http2: true` for a in your default configuration file (`config-default.yaml`). You can do this by uncommenting the port `9081` from the field `apisix.node_listen`):
+Another example of a request where the client communicates with APISIX via HTTP/2 is shown below. Before proceeding, make sure you have configured `enable_http2: true` in your configuration file `config.yaml` for port `9081` and reloaded APISIX. See [`config.yaml.example`](https://github.com/apache/apisix/blob/master/conf/config.yaml.example) for the example configuration.
 
 ```shell
 curl -i -XGET --http2 --http2-prior-knowledge localhost:9081/aws\?name=APISIX
diff --git a/docs/en/latest/plugins/azure-functions.md b/docs/en/latest/plugins/azure-functions.md
@@ -119,7 +119,7 @@ Server: APISIX/2.10.2
 Hello, APISIX
 ```
 
-Another example of a request where the client communicates with APISIX via HTTP/2 is shown below (make sure you have configured `enable_http2: true` in your default configuration file (`config-default.yaml`). You can do this by uncommenting the port `9081` from the field `apisix.node_listen`):
+Another example of a request where the client communicates with APISIX via HTTP/2 is shown below. Before proceeding, make sure you have configured `enable_http2: true` in your configuration file `config.yaml` for port `9081` and reloaded APISIX. See [`config.yaml.example`](https://github.com/apache/apisix/blob/master/conf/config.yaml.example) for the example configuration.
 
 ```shell
 curl -i -XGET --http2 --http2-prior-knowledge http://localhost:9081/azure\?name=APISIX
diff --git a/docs/en/latest/plugins/inspect.md b/docs/en/latest/plugins/inspect.md
@@ -87,16 +87,23 @@ The `info` is a hash table which contains below keys:
 
 ## Enable Plugin
 
-Plugin is enabled by default (`conf/config-default.yaml`):
-
-```yaml title="conf/config-default.yaml"
-plugins:
-    - inspect
-
-plugin_attr:
-  inspect:
-    delay: 3
-    hooks_file: "/usr/local/apisix/plugin_inspect_hooks.lua"
+Plugin is enabled by default:
+
+```yaml title="apisix/cli/config.lua"
+local _M = {
+  plugins = {
+    "inspect",
+    ...
+  },
+  plugin_attr = {
+    inspect = {
+      delay = 3,
+      hooks_file = "/usr/local/apisix/plugin_inspect_hooks.lua"
+    },
+    ...
+  },
+  ...
+}
 ```
 
 ## Example usage
diff --git a/docs/en/latest/pubsub.md b/docs/en/latest/pubsub.md
@@ -106,9 +106,13 @@ Add the required fields to the plugin schema definition and write them to the co
 
 The `kafka-proxy` plugin [kafka-proxy.lua](https://github.com/apache/apisix/blob/master/apisix/plugins/kafka-proxy.lua).
 
-Add this plugin to the list of plugins in the APISIX configuration file.
+Add this plugin to [the existing list of plugins](https://github.com/apache/apisix/blob/master/apisix/cli/config.yaml.example) in the APISIX configuration file [`config.yaml`](https://github.com/apache/apisix/blob/master/conf/config.yaml). For instance:
 
-The plugins list [config-default.yaml](https://github.com/apache/apisix/blob/master/conf/config-default.yaml).
+```yaml title="conf/config.yaml"
+plugins:         # see `conf/config.yaml.example` for an example
+  - ...          # add existing plugins
+  - kafka-proxy
+```
 
 #### Results
 
diff --git a/docs/en/latest/terminology/plugin.md b/docs/en/latest/terminology/plugin.md
@@ -38,22 +38,51 @@ If existing APISIX Plugins do not meet your needs, you can also write your own p
 
 ## Plugins installation
 
-APISIX comes with a default configuration file called `config-default.yaml` and a user-defined configuration file called `config.yaml`. These files are located in the `conf` directory. If the same key (e.g. `plugins`) exists in both files, the configuration values for the key in `config.yaml` will overwrite those in `config-default.yaml`.
+By default, most APISIX plugins are [installed](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua):
+
+```lua title="apisix/cli/config.lua"
+local _M = {
+  ...
+  plugins = {
+    "real-ip",
+    "ai",
+    "client-control",
+    "proxy-control",
+    "request-id",
+    "zipkin",
+    "ext-plugin-pre-req",
+    "fault-injection",
+    "mocking",
+    "serverless-pre-function",
+    ...
+  },
+  ...
+}
+```
 
-The `plugins` block is where you can declare the Plugins loaded to your APISIX instance:
+If you would like to make adjustments to plugins installation, add the customized `plugins` configuration to `config.yaml`. For example:
 
 ```yaml
 plugins:
-  - real-ip         # loaded
+  - real-ip                   # installed
+  - ai
+  - real-ip
   - ai
   - client-control
   - proxy-control
   - request-id
   - zipkin
-  # - skywalking    # not loaded
-...
+  - ext-plugin-pre-req
+  - fault-injection
+  # - mocking                 # not install
+  - serverless-pre-function
+  ...                         # other plugins
 ```
 
+See `config.yaml.example`(https://github.com/apache/apisix/blob/master/conf/config.yaml.example) for a complete configuration reference.
+
+You should reload APISIX for configuration changes to take effect.
+
 ## Plugins execution lifecycle
 
 An installed plugin is first initialized. The configuration of the plugin is then checked against the defined [JSON Schema](https://json-schema.org) to make sure the plugins configuration schema is correct.
diff --git a/docs/zh/latest/FAQ.md b/docs/zh/latest/FAQ.md
@@ -760,15 +760,15 @@ deployment:
     password: etcd_password     # password for etcd
 ```
 
-关于 ETCD 的其他配置，比如过期时间、重试次数等等，你可以参考 `conf/config-default.yaml` 文件中的 `ETCD` 部分。
+关于 ETCD 的其他配置，比如过期时间、重试次数等等，你可以参考 `conf/config.yaml.example` 文件中的 `etcd` 部分。
 
-## SSLs 对象与 `upstream` 对象中的 `tls.client_cert` 以及 `config-default.yaml` 中的 `ssl_trusted_certificate` 区别是什么？
+## SSLs 对象与 `upstream` 对象中的 `tls.client_cert` 以及 `config.yaml` 中的 `ssl_trusted_certificate` 区别是什么？
 
 Admin API 中 `/apisix/admin/ssls` 用于管理 SSL 对象，如果 APISIX 需要接收来自外网的 HTTPS 请求，那就需要用到存放在这里的证书完成握手。SSL 对象中支持配置多个证书，不同域名的证书 APISIX 将使用 Server Name Indication (SNI) 进行区分。
 
 Upstream 对象中的 `tls.client_cert`、`tls.client_key` 与 `tls.client_cert_id` 用于存放客户端的证书，适用于需要与上游进行 [mTLS 通信](https://apisix.apache.org/zh/docs/apisix/tutorials/client-to-apisix-mtls/)的情况。
 
-`config-default.yaml` 中的 `ssl_trusted_certificate` 用于配置一个受信任的根证书。它仅用于在 APISIX 内部访问某些具有自签名证书的服务时，避免提示拒绝对方的 SSL 证书。注意：它不用于信任 APISIX 上游的证书，因为 APISIX 不会验证上游证书的合法性。因此，即使上游使用了无效的 TLS 证书，APISIX 仍然可以与其通信，而无需配置根证书。
+`config.yaml` 中的 `ssl_trusted_certificate` 用于配置一个受信任的根证书。它仅用于在 APISIX 内部访问某些具有自签名证书的服务时，避免提示拒绝对方的 SSL 证书。注意：它不用于信任 APISIX 上游的证书，因为 APISIX 不会验证上游证书的合法性。因此，即使上游使用了无效的 TLS 证书，APISIX 仍然可以与其通信，而无需配置根证书。
 
 ## 如果在使用 APISIX 过程中遇到问题，我可以在哪里寻求更多帮助？
 
diff --git a/docs/zh/latest/benchmark.md b/docs/zh/latest/benchmark.md
@@ -139,7 +139,7 @@ wrk -d 60 --latency http://127.0.0.1:9080/hello
 
 :::tip
 
-如果你想测试大量连接的基准测试，你可能需要更新 [`./conf/config-default.yaml`](https://github.com/apache/apisix/blob/master/conf/config-default.yaml#L242) 中的 **keepalive** 配置项，否则超过配置数量的连接将成为短连接。你可以使用以下命令运行大量连接的基准测试：
+如果您想使用大量连接运行基准测试，您可能需要更新 [**keepalive**](https://github.com/apache/apisix/blob/master/conf/config.yaml.example#L241) 配置，将配置添加到 [`config.yaml`](https://github.com/apache/apisix/blob/master/conf/config.yaml) 并重新加载 APISIX。否则超过配置数量的连接将成为短连接。你可以使用以下命令运行大量连接的基准测试：
 
 ```bash
 wrk -t200 -c5000 -d30s http://127.0.0.1:9080/hello
diff --git a/docs/zh/latest/customize-nginx-configuration.md b/docs/zh/latest/customize-nginx-configuration.md
@@ -21,11 +21,11 @@ title: 自定义 Nginx 配置
 #
 -->
 
-APISIX 会通过 `apisix/cli/ngx_tpl.lua` 这个模板和 `conf/config-default.yaml` 加 `conf/config.yaml` 的配置生成 Nginx 配置文件。
+APISIX 使用的 Nginx 配置是通过模板文件 `apisix/cli/ngx_tpl.lua` 以及 `apisix/cli/config.lua` 和`conf/config.yaml` 中的参数生成的。
 
 在执行完 `./bin/apisix start`，你可以在 `conf/nginx.conf` 看到生成的 Nginx 配置文件。
 
-在自定义 Nginx 配置文件之前，烦请仔细阅读 `conf/config-default.yaml`。你可以在 `conf/config.yaml` 里面覆盖掉默认值。举个例子，你可以通过 `xxx_snippet` 之类的配置，在 `conf/nginx.conf` 里面注入你的自定义配置：
+如果你需要自定义 Nginx 配置，请阅读 `conf/config.default.example` 中的 `nginx_config`。你可以在 `conf/config.yaml` 中覆盖默认值。例如，你可以在 `conf/nginx.conf` 中通过配置 `xxx_snippet` 条目注入一些代码片段：
 
 ```yaml
 ...
diff --git a/docs/zh/latest/install-dependencies.md b/docs/zh/latest/install-dependencies.md
@@ -25,7 +25,7 @@ title: 安装依赖
 
 - Apache APISIX 从 v2.0 开始不再支持 `v2` 版本的 etcd，并且 etcd 最低支持版本为 v3.4.0，因此请使用 etcd 3.4.0+。更重要的是，因为 etcd v3 使用 gRPC 作为消息传递协议，而 Apache APISIX 使用 HTTP(S) 与 etcd 集群通信，因此请确保启用 [etcd gRPC gateway](https://etcd.io/docs/v3.4.0/dev-guide/api_grpc_gateway/) 功能。
 
-- 目前 Apache APISIX 默认使用 HTTP 协议与 etcd 集群通信，这并不安全，如果希望保障数据的安全性和完整性。请为您的 etcd 集群配置证书及对应私钥，并在您的 Apache APISIX etcd endpoints 配置列表中明确使用 `https` 协议前缀。请查阅 `conf/config-default.yaml` 中 etcd 一节相关的配置来了解更多细节。
+- 目前 Apache APISIX 默认使用 HTTP 协议与 etcd 集群通信，这并不安全，如果希望保障数据的安全性和完整性。请为您的 etcd 集群配置证书及对应私钥，并在您的 Apache APISIX etcd endpoints 配置列表中明确使用 `https` 协议前缀。请查阅 `conf/config.yaml.example` 中 `etcd` 一节相关的配置来了解更多细节。
 
 - 如果是 OpenResty 1.19，APISIX 会使用 OpenResty 内置的 LuaJIT 来运行 `bin/apisix`；否则会使用 Lua 5.1。如果运行过程中遇到 `luajit: lj_asm_x86.h:2819: asm_loop_fixup: Assertion '((intptr_t)target & 15) == 0' failed`，这是低版本 OpenResty 内置的 LuaJIT 在特定编译条件下的问题。
 
diff --git a/docs/zh/latest/installation-guide.md b/docs/zh/latest/installation-guide.md
diff --git a/docs/zh/latest/plugin-develop.md b/docs/zh/latest/plugin-develop.md
diff --git a/docs/zh/latest/terminology/plugin.md b/docs/zh/latest/terminology/plugin.md
