From 6c352fd525ff6b45b65d433e13cd8bf1bc7d4c8f Mon Sep 17 00:00:00 2001
From: "Zaiming (Stone) Shi" <zmstone@gmail.com>
Date: Tue, 18 Apr 2023 18:23:21 +0200
Subject: [PATCH] docs: update config docs

---
 rel/emqx_conf.template.en.md | 22 ++++++++++++++--------
 rel/emqx_conf.template.zh.md | 16 ++++++++++------
 2 files changed, 24 insertions(+), 14 deletions(-)

diff --git a/rel/emqx_conf.template.en.md b/rel/emqx_conf.template.en.md
index 8740e4319..bf5120046 100644
--- a/rel/emqx_conf.template.en.md
+++ b/rel/emqx_conf.template.en.md
@@ -7,21 +7,27 @@ and a superset of JSON.
 EMQX configuration consists of two layers.
 From bottom up:
 
-1. Immutable base: `emqx.conf` + `EMQX_` prefixed environment variables.<br/>
-   Changes in this layer require a full node restart to take effect.
-1. Cluster overrides: `$EMQX_NODE__DATA_DIR/configs/cluster-override.conf`
+1. Cluster-synced configs: `$EMQX_NODE__DATA_DIR/configs/cluster.hocon`.
+2. Local node configs: `emqx.conf` + `EMQX_` prefixed environment variables.
+
+:::tip Tip
+Prior to v5.0.23 and e5.0.3, the cluster-synced configs are stored in
+`cluster-override.conf` which is applied on top of the local configs.
+
+If upgraded from an earlier version, as long as `cluster-override.conf` exists,
+`cluster.hocon` will not be created, and `cluster-override.conf` will stay on
+top of the overriding layers.
+:::
 
 When environment variable `$EMQX_NODE__DATA_DIR` is not set, config `node.data_dir`
 is used.
 
-The `cluster-override.conf` file is overwritten at runtime when changes
-are made from dashboard UI, management HTTP API, or CLI. When clustered,
+The `cluster.hocon` file is overwritten at runtime when changes
+are made from Dashboard, management HTTP API, or CLI. When clustered,
 after EMQX restarts, it copies the file from the node which has the greatest `uptime`.
 
 :::tip Tip
-Some of the configs (such as `node.name`) are boot-only configs and not overridable.
-Config values from `*-override.conf` are **not** mapped to boot configs for
-the config fields attributed with `mapping: path.to.boot.config.key`
+To avoid confusion, don't add the same keys in both `cluster.hocon` and `emqx.conf`.
 :::
 
 For detailed override rules, see [Config Overlay Rules](#config-overlay-rules).
diff --git a/rel/emqx_conf.template.zh.md b/rel/emqx_conf.template.zh.md
index 9402760a2..a96c9ee48 100644
--- a/rel/emqx_conf.template.zh.md
+++ b/rel/emqx_conf.template.zh.md
@@ -5,9 +5,15 @@ HOCON（Human-Optimized Config Object Notation）是一个JSON的超集，非常
 
 EMQX的配置文件可分为二层，自底向上依次是：
 
-1. 不可变的基础层 `emqx.conf` 加上 `EMQX_` 前缀的环境变量。<br/>
-   修改这一层的配置之后，需要重启节点来使之生效。
-1. 集群范围重载层：`$EMQX_NODE__DATA_DIR/configs/cluster-override.conf`
+1. 集群同步配置：`$EMQX_NODE__DATA_DIR/configs/cluster.hocon`。
+2. 本地节点配置：`emqx.conf` 加上 `EMQX_` 前缀的环境变量。
+
+:::tip Tip
+在 v5.0.23 或 e5.0.3 之前，集群同步配置保存在文件 `cluster-override.conf` 中，并且它覆盖在配置的最上层。
+
+如果从之前的版本升级上来，只要 `cluster-override.conf` 文件存在，
+EMQX 就不会创建 `cluster.hocon`，并且 `cluster-override.conf` 会继续覆盖在配置的最上层。
+:::
 
 如果环境变量 `$EMQX_NODE__DATA_DIR` 没有设置，那么该目录会从 `emqx.conf` 的 `node.data_dir` 配置中读取。
 
@@ -16,9 +22,7 @@ EMQX的配置文件可分为二层，自底向上依次是：
 当EMQX运行在集群中时，一个EMQX节点重启之后，会从集群中其他节点复制该文件内容到本地。
 
 :::tip Tip
-有些配置项是不能被重载的（例如 `node.name`）。
-配置项如果有 `mapping: path.to.boot.config.key` 这个属性，
-则不能被添加到重载文件 `*-override.conf` 中。
+为避免歧义，应尽量避免让 `cluster.hocon` 和 `emqx.conf` 出现配置交集。
 :::
 
 更多的重载规则，请参考下文 [配置重载规则](#配置重载规则)。