cherry pick pingcap#5331 to release-5.0

TomShawn · ti-srebot · commit 235b4332934e · 2021-04-16T19:29:06.000+08:00
Signed-off-by: ti-srebot &lt;ti-srebot@pingcap.com&gt;
diff --git a/TOC.md b/TOC.md
@@ -506,12 +506,15 @@
       + [Overview](/tiflash/tiflash-overview.md)
       + [Use TiFlash](/tiflash/use-tiflash.md)
   + TiUP
-    + [Documentation Guide](/tiup/tiup-documentation-guide.md)
+    + [Documentation Map](/tiup/tiup-documentation-guide.md)
     + [Overview](/tiup/tiup-overview.md)
     + [Terminology and Concepts](/tiup/tiup-terminology-and-concepts.md)
     + [Manage TiUP Components](/tiup/tiup-component-management.md)
     + [FAQ](/tiup/tiup-faq.md)
     + [Troubleshooting Guide](/tiup/tiup-troubleshooting-guide.md)
+    + [Reference Guide](/tiup/tiup-reference.md)
+    + [Cluster Topology Reference](/tiup/tiup-cluster-topology-reference.md)
+    + [Mirror Reference Guide](/tiup/tiup-mirror-reference.md)
     + TiUP Components
       + [tiup-playground](/tiup/tiup-playground.md)
       + [tiup-cluster](/tiup/tiup-cluster.md)
diff --git a/geo-distributed-deployment-topology.md b/geo-distributed-deployment-topology.md
@@ -20,6 +20,8 @@ This document takes the typical architecture of three data centers (DC) in two c
 
 - [The geo-distributed topology template](https://github.com/pingcap/docs/blob/master/config-templates/geo-redundancy-deployment.yaml)
 
+For detailed descriptions of the configuration items in the above TiDB cluster topology file, see [Topology Configuration File for Deploying TiDB Using TiUP](/tiup/tiup-cluster-topology-reference.md).
+
 ### Key parameters
 
 This section describes the key parameter configuration of the TiDB geo-distributed deployment.
diff --git a/hybrid-deployment-topology.md b/hybrid-deployment-topology.md
@@ -25,6 +25,8 @@ The deployment machine has multiple CPU processors with sufficient memory. To im
 - [The simple template for the hybrid deployment](https://github.com/pingcap/docs-cn/blob/master/config-templates/simple-multi-instance.yaml)
 - [The complex template for the hybrid deployment](https://github.com/pingcap/docs/blob/master/config-templates/complex-multi-instance.yaml)
 
+For detailed descriptions of the configuration items in the above TiDB cluster topology file, see [Topology Configuration File for Deploying TiDB Using TiUP](/tiup/tiup-cluster-topology-reference.md).
+
 ### Key parameters
 
 This section introduces the key parameters when you deploy multiple instances on a single machine, which is mainly used in scenarios when multiple instances of TiDB and TiKV are deployed on a single machine. You need to fill in the results into the configuration template according to the calculation methods provided below.
diff --git a/minimal-deployment-topology.md b/minimal-deployment-topology.md
@@ -21,6 +21,8 @@ This document describes the minimal deployment topology of TiDB clusters.
 - [The simple template for the minimal topology](https://github.com/pingcap/docs/blob/master/config-templates/simple-mini.yaml)
 - [The complex template for the minimal topology](https://github.com/pingcap/docs/blob/master/config-templates/complex-mini.yaml)
 
+For detailed descriptions of the configuration items in the above TiDB cluster topology file, see [Topology Configuration File for Deploying TiDB Using TiUP](/tiup/tiup-cluster-topology-reference.md).
+
 > **Note:**
 >
 > - You do not need to manually create the `tidb` user in the configuration file. The TiUP cluster component automatically creates the `tidb` user on the target machines. You can customize the user, or keep the user consistent with the control machine.
diff --git a/ticdc-deployment-topology.md b/ticdc-deployment-topology.md
@@ -28,6 +28,8 @@ TiCDC is a tool for replicating the incremental data of TiDB, introduced in TiDB
 - [The simple template for the TiCDC topology](https://github.com/pingcap/docs/blob/master/config-templates/simple-cdc.yaml)
 - [The complex template for the TiCDC topology](https://github.com/pingcap/docs/blob/master/config-templates/complex-cdc.yaml)
 
+For detailed descriptions of the configuration items in the above TiDB cluster topology file, see [Topology Configuration File for Deploying TiDB Using TiUP](/tiup/tiup-cluster-topology-reference.md).
+
 > **Note:**
 >
 > - You do not need to manually create the `tidb` user in the configuration file. The TiUP cluster component automatically creates the `tidb` user on the target machines. You can customize the user, or keep the user consistent with the control machine.
diff --git a/tidb-binlog-deployment-topology.md b/tidb-binlog-deployment-topology.md
@@ -25,6 +25,8 @@ TiDB Binlog is the widely used component for replicating incremental data. It pr
 - [The simple template for the TiDB Binlog topology (with `file` as the downstream type)](https://github.com/pingcap/docs/blob/master/config-templates/simple-file-binlog.yaml)
 - [The complex template for the TiDB Binlog topology](https://github.com/pingcap/docs/blob/master/config-templates/complex-tidb-binlog.yaml)
 
+For detailed descriptions of the configuration items in the above TiDB cluster topology file, see [Topology Configuration File for Deploying TiDB Using TiUP](/tiup/tiup-cluster-topology-reference.md).
+
 ### Key parameters
 
 The key parameters in the topology configuration templates are as follows:
diff --git a/tiflash-deployment-topology.md b/tiflash-deployment-topology.md
@@ -24,6 +24,8 @@ TiFlash is a columnar storage engine, and gradually becomes the standard cluster
 - [The simple template for the TiFlash topology](https://github.com/pingcap/docs/blob/master/config-templates/simple-tiflash.yaml)
 - [The complex template for the TiFlash topology](https://github.com/pingcap/docs/blob/master/config-templates/complex-tiflash.yaml)
 
+For detailed descriptions of the configuration items in the above TiDB cluster topology file, see [Topology Configuration File for Deploying TiDB Using TiUP](/tiup/tiup-cluster-topology-reference.md).
+
 ### Key parameters
 
 - To enable the [Placement Rules](/configure-placement-rules.md) feature of PD, set the value of `replication.enable-placement-rules` in the configuration template to `true`.
diff --git a/tispark-deployment-topology.md b/tispark-deployment-topology.md
@@ -30,6 +30,8 @@ For more information about the TiSpark architecture and how to use it, see [TiSp
 - [Simple TiSpark topology template](https://github.com/pingcap/docs/blob/master/config-templates/simple-tispark.yaml)
 - [Complex TiSpark topology template](https://github.com/pingcap/docs/blob/master/config-templates/complex-tispark.yaml)
 
+For detailed descriptions of the configuration items in the above TiDB cluster topology file, see [Topology Configuration File for Deploying TiDB Using TiUP](/tiup/tiup-cluster-topology-reference.md).
+
 > **Note:**
 >
 > - You do not need to manually create the `tidb` user in the configuration file. The TiUP cluster component automatically creates the `tidb` user on the target machines. You can customize the user, or keep the user consistent with the control machine.
diff --git a/tiup/tiup-cluster.md b/tiup/tiup-cluster.md
@@ -219,7 +219,7 @@ For the PD component, `|L` or `|UI` might be appended to `Up` or `Down`. `|L` in
 >
 > This section describes only the syntax of the scale-in command. For detailed steps of online scaling, refer to [Scale the TiDB Cluster Using TiUP](/scale-tidb-using-tiup.md).
 
-Scaling in a cluster means making some node(s) offline. This operation removes the specific node(s) from the cluster and deletes the remaining data files.
+Scaling in a cluster means making some node(s) offline. This operation removes the specific node(s) from the cluster and deletes the remaining files.
 
 Because the offline process of the TiKV and TiDB Binlog components is asynchronous (which requires removing the node through API), and the process takes a long time (which requires continuous observation on whether the node is successfully taken offline), special treatment is given to the TiKV and TiDB Binlog components.
 
diff --git a/tiup/tiup-documentation-guide.md b/tiup/tiup-documentation-guide.md
@@ -1,25 +1,19 @@
 ---
-title: TiUP Documentation Guide
+title: TiUP Documentation Map
 summary: Guide you through TiUP documentation with links and introductions.
 ---
 
-# TiUP Documentation Guide
+# TiUP Documentation Map
 
-## TiUP user guide
+## User guide
 
-- [TiUP Overview](/tiup/tiup-overview.md): Gives an overall introduction to TiUP, for example, how to install and use TiUP
+- [TiUP Overview](/tiup/tiup-overview.md): Gives an overall introduction to TiUP, for example, how to install and use TiUP, and the related terminologies.
 - [TiUP Terminology and Concepts](/tiup/tiup-terminology-and-concepts.md): Explains the terms that you might bump into when using TiUP, and help you understand the key concepts of TiUP
 - [TiUP Component Management](/tiup/tiup-component-management.md): Introduces all TiUP commands in detail, and how to use TiUP to download, update and delete components
 - [TiUP FAQ](/tiup/tiup-faq.md): Introduces common issues when you use TiUP, including FAQs of the third-party components of TiUP
 - [TiUP Troubleshooting Guide](/tiup/tiup-troubleshooting-guide.md): Introduces the troubleshooting methods and solutions if you encounter issues when using TiUP
-
-## TiUP component user guide
-
-- [tiup-playground](/tiup/tiup-playground.md): Introduces how to use the TiUP playground component to quickly build a local TiDB cluster for testing
-- [tiup-cluster](/tiup/tiup-cluster.md): Introduces the usage and command-line flags of the TiUP cluster component, which is used to deploy and maintain a TiDB cluster for production
-- [tiup-mirror](/tiup/tiup-mirror.md): Introduces how to use the TiUP mirror component to customize a local offline mirror
-- [tiup-bench](/tiup/tiup-bench.md): Introduces how to use the TiUP bench component for common stress testings, such as TPCC/TPCH
+- [TiUP Reference Guide](/tiup/tiup-reference.md): Introduces detailed references, including commands, components, and mirrors.
 
 ## TiUP resources
 
-- [TiUP Issues](https://github.com/pingcap/tiup/issues): Lists TiUP Github issues
+- [TiUP Issues](https://github.com/pingcap/tiup/issues): Lists TiUP GitHub issues

Original file line number	Diff line number	Diff line change
`@@ -21,6 +21,8 @@ This document describes the minimal deployment topology of TiDB clusters.`
`21`	`21`	`- [The simple template for the minimal topology](https://github.com/pingcap/docs/blob/master/config-templates/simple-mini.yaml)`
`22`	`22`	`- [The complex template for the minimal topology](https://github.com/pingcap/docs/blob/master/config-templates/complex-mini.yaml)`
`23`	`23`
	`24`	`+For detailed descriptions of the configuration items in the above TiDB cluster topology file, see [Topology Configuration File for Deploying TiDB Using TiUP](/tiup/tiup-cluster-topology-reference.md).`
	`25`	`+`
`24`	`26`	`> Note:`
`25`	`27`	`>`
`26`	`28`	> - You do not need to manually create the `tidb` user in the configuration file. The TiUP cluster component automatically creates the `tidb` user on the target machines. You can customize the user, or keep the user consistent with the control machine.
Original file line number	Diff line number	Diff line change
`@@ -28,6 +28,8 @@ TiCDC is a tool for replicating the incremental data of TiDB, introduced in TiDB`
`28`	`28`	`- [The simple template for the TiCDC topology](https://github.com/pingcap/docs/blob/master/config-templates/simple-cdc.yaml)`
`29`	`29`	`- [The complex template for the TiCDC topology](https://github.com/pingcap/docs/blob/master/config-templates/complex-cdc.yaml)`
`30`	`30`
	`31`	`+For detailed descriptions of the configuration items in the above TiDB cluster topology file, see [Topology Configuration File for Deploying TiDB Using TiUP](/tiup/tiup-cluster-topology-reference.md).`
	`32`	`+`
`31`	`33`	`> Note:`
`32`	`34`	`>`
`33`	`35`	> - You do not need to manually create the `tidb` user in the configuration file. The TiUP cluster component automatically creates the `tidb` user on the target machines. You can customize the user, or keep the user consistent with the control machine.
Original file line number	Diff line number	Diff line change
`@@ -30,6 +30,8 @@ For more information about the TiSpark architecture and how to use it, see [TiSp`
`30`	`30`	`- [Simple TiSpark topology template](https://github.com/pingcap/docs/blob/master/config-templates/simple-tispark.yaml)`
`31`	`31`	`- [Complex TiSpark topology template](https://github.com/pingcap/docs/blob/master/config-templates/complex-tispark.yaml)`
`32`	`32`
	`33`	`+For detailed descriptions of the configuration items in the above TiDB cluster topology file, see [Topology Configuration File for Deploying TiDB Using TiUP](/tiup/tiup-cluster-topology-reference.md).`
	`34`	`+`
`33`	`35`	`> Note:`
`34`	`36`	`>`
`35`	`37`	> - You do not need to manually create the `tidb` user in the configuration file. The TiUP cluster component automatically creates the `tidb` user on the target machines. You can customize the user, or keep the user consistent with the control machine.
Original file line number	Diff line number	Diff line change
@@ -219,7 +219,7 @@ For the PD component, `\|L` or `\|UI` might be appended to `Up` or `Down`. `\|L` in
`219`	`219`	`>`
`220`	`220`	`> This section describes only the syntax of the scale-in command. For detailed steps of online scaling, refer to [Scale the TiDB Cluster Using TiUP](/scale-tidb-using-tiup.md).`
`221`	`221`
`222`		`-Scaling in a cluster means making some node(s) offline. This operation removes the specific node(s) from the cluster and deletes the remaining data files.`
	`222`	`+Scaling in a cluster means making some node(s) offline. This operation removes the specific node(s) from the cluster and deletes the remaining files.`
`223`	`223`
`224`	`224`	`Because the offline process of the TiKV and TiDB Binlog components is asynchronous (which requires removing the node through API), and the process takes a long time (which requires continuous observation on whether the node is successfully taken offline), special treatment is given to the TiKV and TiDB Binlog components.`
`225`	`225`