feat: allow user to specify APISIX id in config.yaml (#2893)

fix #2810

FAQ.md

@@ -257,7 +257,7 @@ Steps:
 
 Now you can trace the info level log in logs/error.log.
 
-## How to reload your own plugin
+## How to reload your own plugin?
 
 The Apache APISIX plugin supports hot reloading.
 See the `Hot reload` section in [plugins](./doc/plugins.md) for how to do that.
@@ -274,7 +274,7 @@ By default, APISIX only listens on port 9080 when handling HTTP requests. If you
         - 9080
         - 9081
         - 9082
-    ```
+   ```
 
    Handling HTTPS requests is similar, modify the parameter of HTTPS port listen `ssl.listen_port` in `conf/config.yaml`, for example:
 
@@ -288,3 +288,14 @@ By default, APISIX only listens on port 9080 when handling HTTP requests. If you
     ```
 
 2. Reload or restart APISIX
+
+## How to customize the APISIX instance id?
+
+By default, APISIX will read the instance id from `conf/apisix.uid`. If it is not found, and no id is configured, APISIX will generate a `uuid` as the instance id.
+
+If you want to specify a meaningful id to bind APISIX instance to your internal system, you can configure it in `conf/config.yaml`, for example:
+
+    ```
+    apisix:
+      id: "your-meaningful-id"
+    ```

FAQ_CN.md

@@ -250,3 +250,14 @@ APISIX 主要使用 [etcd.watchdir](https://github.com/api7/lua-resty-etcd/blob/
 * 如果监听目录有数据更新：etcd 将立刻返回订阅(毫秒级)到的新数据，APISIX 将它更新到内存缓存。
 
 借助 etcd 增量通知毫秒级特性，APISIX 也就完成了毫秒级的配置同步。
+
+## 如何自定义 APISIX 实例 id
+
+默认情况下，APISIX 会从 `conf/apisix.uid` 中读取实例 id。如果找不到，且没有配置 id，APISIX 会生成一个 `uuid` 作为实例 id。
+
+如果你想指定一个有意义的 id 来绑定 APISIX 实例到你的内部系统，你可以在 `conf/config.yaml` 中进行配置，示例：
+
+    ```
+    apisix:
+      id: "your-meaningful-id"
+    ```

apisix/core/id.lua

@@ -14,10 +14,12 @@
 -- See the License for the specific language governing permissions and
 -- limitations under the License.
 --
-local log = require("apisix.core.log")
-local uuid = require('resty.jit-uuid')
-local smatch = string.match
-local open = io.open
+local fetch_local_conf = require("apisix.core.config_local").local_conf
+local try_read_attr    = require("apisix.core.table").try_read_attr
+local log              = require("apisix.core.log")
+local uuid             = require('resty.jit-uuid')
+local smatch           = string.match
+local open             = io.open
 
 
 local prefix = ngx.config.prefix()
@@ -65,9 +67,16 @@ function _M.init()
         return
     end
 
-    uuid.seed()
-    apisix_uid = uuid.generate_v4()
-    log.notice("not found apisix uid, generate a new one: ", apisix_uid)
+    --allow user to specify a meaningful id as apisix instance id
+    local local_conf = fetch_local_conf()
+    local id = try_read_attr(local_conf, "apisix", "id")
+    if id then
+        apisix_uid = local_conf.apisix.id
+    else
+        uuid.seed()
+        apisix_uid = uuid.generate_v4()
+        log.notice("not found apisix uid, generate a new one: ", apisix_uid)
+    end
 
     local ok, err = write_file(uid_file_path, apisix_uid)
     if not ok then

t/plugin/node-status.t

@@ -53,3 +53,55 @@ qr/"accepted":/
 --- request
 PATCH /apisix/status
 --- error_code: 404
+
+
+
+=== TEST 3: test for use default uuid as apisix_uid
+--- config
+location /t {
+    content_by_lua_block {
+        ngx.sleep(0.5)
+        local t = require("lib.test_admin").test
+        local code, body, body_org = t('/apisix/status', ngx.HTTP_GET)
+
+        if code >= 300 then
+            ngx.status = code
+        end
+        local json_decode = require("cjson").decode
+        local body_json = json_decode(body_org)
+        ngx.say(body_json.id)
+    }
+}
+--- request
+GET /t
+--- response_body_like eval
+qr/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/
+--- no_error_log
+[error]
+
+
+
+=== TEST 4: test for allow user to specify a meaningful id as apisix_uid
+--- yaml_config
+apisix:
+    id: "user-set-apisix-instance-id-A"
+#END
+--- config
+location /t {
+    content_by_lua_block {
+        ngx.sleep(0.5)
+        local t = require("lib.test_admin").test
+        local code, body, body_org = t('/apisix/status', ngx.HTTP_GET)
+
+        if code >= 300 then
+            ngx.status = code
+        end
+        ngx.say(body_org)
+    }
+}
+--- request
+GET /t
+--- response_body eval
+qr/"id":"user-set-apisix-instance-id-A"/
+--- no_error_log
+[error]