From 71afcfcefb3527d9b35b12ed35ece51351d43905 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 9 Apr 2021 09:31:41 +0800 Subject: [PATCH 01/20] TiUP: add two documents for cluster import and scale-in --- tiup/tiup-component-cluster-import.md | 67 ++++++++++++++++++++++++ tiup/tiup-component-cluster-scale-in.md | 69 +++++++++++++++++++++++++ 2 files changed, 136 insertions(+) create mode 100644 tiup/tiup-component-cluster-import.md create mode 100644 tiup/tiup-component-cluster-scale-in.md diff --git a/tiup/tiup-component-cluster-import.md b/tiup/tiup-component-cluster-import.md new file mode 100644 index 0000000000000..c9c2596269e90 --- /dev/null +++ b/tiup/tiup-component-cluster-import.md @@ -0,0 +1,67 @@ +--- +title: tiup cluster import +--- + +# tiup cluster import + +Before TiDB 4.0, clusters were usually deployed using TiDB Ansible. From TiDB 4.0 onwards, TiUP Cluster provides the `import` command to transfer these clusters to the tiup-cluster component for the management. + +> **Note:** +> +> + After importing the TiDB Ansible configuration to TiUP for the management, do not use TiDB Ansible for cluster operations anymore. Otherwise, conflicts might be caused due to inconsistent meta information. +> + The `import` command does not support the import of the following clusters. If the clusters deployed using TiDB Ansible are in any of the following scenarios, do not use the `import` command. +> + Clusters with TLS encryption enabled +> + Pure KV clusters (clusters without TiDB instances) +> + Clusters with `Kafka` enabled +> + Clusters with `Spark` enabled +> + Clusters with TiDB Lightning/Importer enabled +> + Clusters still using the old `push` mode to collect monitoring metrics (if you keep the default mode `pull` unchanged, using the `import` command is supported) +> + Clusters in which the non-default ports (the ports configured in the `group_vars` directory are compatible) are separately configured in the `inventory.ini` configuration file using `node_exporter_port` / `blackbox_exporter_port` + +## Syntax + +```sh +tiup cluster import [flags] +``` + +## Options + +### -d, --dir ${string} + +- Data type: `STRING` +- Specifies the directory where TiDB Ansible is located. +- If you do not specify this option in the command, the current directory is regarded as the directory where TiDB Ansible is located. + +### --ansible-config ${string} + +- Data type: `STRING` +- Specifies the path of the Ansible configuration file. +- If you do not specify this option in the command, the default path `. /ansible.cfg` is used in the import. + +### --inventory ${string} + +- Data type: `STRING` +- Specifies the name of the Ansible inventory file. +- If you do not specify this option in the command, the default name `inventory.ini` is used in the import. + +### --no-backup + +- Data type: `BOOLEAN` +- Controls whether to disable the backup of files in the directory where TiDB Ansible is located. +- If you do not specify this option in the command, after a successful import, everything in the directory specified by the `-dir` option is backed up to the `${TIUP_HOME}/.tiup/storage/cluster/clusters/{cluster-name}/ansible-backup` directory. If there are multiple inventory files (which indicates multiple clusters are deployed) in this directory, it is recommended to include this option in the `import` command to disable the default backup step. + +### --rename ${string} + +- Data type: `STRING` +- Renames the imported cluster. +- If you do not specify this option in the command, the cluster_name specified in inventory is used as the cluster name. + +### -h, --help + +- Data type: `BOOLEAN` +- Shows the help information. +- If you do not specify this option in the command, the default value is `false` so the help information is not shown. + +## Output + +Shows the logs of the import process. diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md new file mode 100644 index 0000000000000..d4d8b272c2e6b --- /dev/null +++ b/tiup/tiup-component-cluster-scale-in.md @@ -0,0 +1,69 @@ +--- +title: tiup cluster scale-in +--- + +# tiup cluster scale-in + +The `tiup cluster scale-in` command is used to scale down the cluster, which takes the services of the specified nodes offline, removes the specified nodes from the cluster, and deletes the remaining files from those nodes. + +Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynchronously (the removal needs to be executed by the API first) and the stopping process takes a long time (the command needs to keep checking whether the specified nodes have been successfully stopped), the `tiup cluster scale-in` command handles the TiKV, TiFlash and TiDB Binlog components particularly as follows: + +- For TiKV, TiFlash and TiDB Binlog components, the `tiup cluster scale-in` command makes the following operations: + + - Exit tiup-cluster directly after it is stopped by the API without waiting for the entire stopping process to be completed. + - Execute the `tiup cluster display` command to check the status of the nodes being scaled down and wait for the status to change to `Tombstone`. + - Execute the `tiup cluster prune` command to clean up the nodes in the `Tombstone` status, which performs the following operations: + + - Stop the services of the nodes that have been taken offline. + - Clean up the data files of the nodes that have been taken offline. + - Update the cluster topology and remove the nodes that have been taken offline. + +- For other components, the `tiup cluster scale-in` command makes the following operations: + + - To take the PD nodes offline, the command uses the API to remove the specified PD nodes from the cluster (this process is fast), stops the services of the specified PD nodes, and then cleans up the data files of the specified PD nodes. + - To take other components offline, the command stops the nodes and cleans up the related data files directly. + +## Syntax + +```sh +tiup cluster scale-in [flags] +``` + +`` is the name of the cluster to be scaled down. If you forget the cluster name, check the name in [cluster-list](/tiup/tiup-component-cluster-list.md). + +## Options + +### -N, --node ${strings} + +- Data type: `STRING` +- Specifies the nodes to be scaled down, split by commas if scaling multiple nodes. +- There is no default value. This option is mandatory. + +### --force + +- Data type: `BOOLEAN` +- Controls whether to forcibly remove the specified nodes from the cluster. In some cases, it is possible that the host of the node to be scaled down is down, making it impossible to connect to the node via SSH for operations, so you can forcibly remove it from the cluster using the `-force` option. +- The default value is `false`. If you do not add this option in the command, the specified nodes are not forcibly removed. + +> **Note:** +> +> Because the forced removal of a TiKV node does not wait for data to be scheduled, removing more than one serving TiKV node is in the risk of data loss. + +### --transfer-timeout ${unit} + +- When a PD or TiKV node is to be scaled down, the leader role of the node will be migrated to other nodes first. Because the migration process takes some time, you can set the maximum waiting time (in seconds) by configuring `-transfer-timeout`. After the timeout, the `tiup cluster scale-in` command skips waiting and starts the scaling down directly. +- If you do not add this option in the command, the default waiting time of leader migration is `300` seconds. + +> **Note:** +> +> If a PD or TiKV node is scaled down directly without waiting for the leader role migration to be completed, the service performance may jitter. + +### -h, --help + +- Data type: `BOOLEAN` +- Shows the help information. +- If you do not specify this option in the command, the default value is `false` so the help information is not shown. + +## Output + +Shows the logs of the scaling down process. \ No newline at end of file From 7a0e5b804e787286ca6b1f1a1fca86ce3816d783 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 9 Apr 2021 10:05:43 +0800 Subject: [PATCH 02/20] Create tiup-component-dm-list.md --- tiup/tiup-component-dm-list.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 tiup/tiup-component-dm-list.md diff --git a/tiup/tiup-component-dm-list.md b/tiup/tiup-component-dm-list.md new file mode 100644 index 0000000000000..e161023905a85 --- /dev/null +++ b/tiup/tiup-component-dm-list.md @@ -0,0 +1,34 @@ +--- +title: tiup dm list +--- + +# tiup dm list + +`tiup-dm` supports deploying multiple clusters with the same central console. You can use the command `tiup dm list` to check which clusters are deployed using the central console by the currently logged-in user. + +> **Note:** +> +> By default, the data of the deployed clusters is stored in the `~/.tiup/storage/dm/clusters/` directory. The currently logged-in user cannot view the clusters deployed by other users on the same central console. + +## Syntax + +```sh +tiup dm list [flags] +``` + +## Options + +### -h, --help (boolean, default false) + +Show help information in the output. + +## Output + +The output is a table containing the following fields. + +- Name: the cluster name +- User: the user who deployed the cluster +- Version: the cluster version +- Path: the path of the cluster deployment data on the central control machine +- PrivateKey: the path of the private key to the cluster + From 0d1c7316b276ad7c5bbb9c54da5827211a642c2f Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 9 Apr 2021 11:17:38 +0800 Subject: [PATCH 03/20] Updated the style --- tiup/tiup-component-cluster-import.md | 34 ++++++++++++------------- tiup/tiup-component-cluster-scale-in.md | 21 +++++++-------- tiup/tiup-component-dm-list.md | 13 +++++----- 3 files changed, 35 insertions(+), 33 deletions(-) diff --git a/tiup/tiup-component-cluster-import.md b/tiup/tiup-component-cluster-import.md index c9c2596269e90..24a7258d84225 100644 --- a/tiup/tiup-component-cluster-import.md +++ b/tiup/tiup-component-cluster-import.md @@ -4,7 +4,7 @@ title: tiup cluster import # tiup cluster import -Before TiDB 4.0, clusters were usually deployed using TiDB Ansible. From TiDB 4.0 onwards, TiUP Cluster provides the `import` command to transfer these clusters to the tiup-cluster component for the management. +Before TiDB 4.0, clusters were usually deployed using TiDB Ansible. For TiDB 4.0 and later releases, TiUP Cluster provides the `import` command to transfer these clusters to the tiup-cluster component for the management. > **Note:** > @@ -26,41 +26,41 @@ tiup cluster import [flags] ## Options -### -d, --dir ${string} +### -d, --dir -- Data type: `STRING` - Specifies the directory where TiDB Ansible is located. -- If you do not specify this option in the command, the current directory is regarded as the directory where TiDB Ansible is located. +- Data type: `STRING` +- If this option is not specified in the command, the current directory is regarded as the directory where TiDB Ansible is located. -### --ansible-config ${string} +### --ansible-config -- Data type: `STRING` - Specifies the path of the Ansible configuration file. -- If you do not specify this option in the command, the default path `. /ansible.cfg` is used in the import. +- Data type: `STRING` +- If this option is not specified in the command, the default path `. /ansible.cfg` is used in the import. -### --inventory ${string} +### --inventory -- Data type: `STRING` - Specifies the name of the Ansible inventory file. -- If you do not specify this option in the command, the default name `inventory.ini` is used in the import. +- Data type: `STRING` +- If this option is not specified in the command, the default name `inventory.ini` is used in the import. ### --no-backup -- Data type: `BOOLEAN` - Controls whether to disable the backup of files in the directory where TiDB Ansible is located. -- If you do not specify this option in the command, after a successful import, everything in the directory specified by the `-dir` option is backed up to the `${TIUP_HOME}/.tiup/storage/cluster/clusters/{cluster-name}/ansible-backup` directory. If there are multiple inventory files (which indicates multiple clusters are deployed) in this directory, it is recommended to include this option in the `import` command to disable the default backup step. +- Data type: `BOOLEAN` +- Default: false. If this option is not specified in the command, after a successful import, everything in the directory specified by the `-dir` option is backed up to the `${TIUP_HOME}/.tiup/storage/cluster/clusters/{cluster-name}/ansible-backup` directory. If there are multiple inventory files (which indicates multiple clusters are deployed) in this directory, it is recommended to add this option in the `import` command to disable the default backup step. -### --rename ${string} +### --rename +- Renames the imported cluster. - Data type: `STRING` -- Renames the imported cluster. -- If you do not specify this option in the command, the cluster_name specified in inventory is used as the cluster name. +- Default: NULL. If this option is not specified in the command, the cluster_name specified in inventory is used as the cluster name. ### -h, --help +- Shows the help information in the output. - Data type: `BOOLEAN` -- Shows the help information. -- If you do not specify this option in the command, the default value is `false` so the help information is not shown. +- Default: false ## Output diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index d4d8b272c2e6b..4eeedbd4998d3 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -33,26 +33,27 @@ tiup cluster scale-in [flags] ## Options -### -N, --node ${strings} +### -N, --node -- Data type: `STRING` - Specifies the nodes to be scaled down, split by commas if scaling multiple nodes. -- There is no default value. This option is mandatory. +- Data type: `STRING` +- There is no default value. This option is mandatory and the value must be not null. ### --force +- Controls whether to forcibly remove the specified nodes from the cluster. In some cases, it is possible that the host of the node to be scaled down is down, making it impossible to connect to the node via SSH for operations, so you can forcibly remove the node from the cluster using the `-force` option. - Data type: `BOOLEAN` -- Controls whether to forcibly remove the specified nodes from the cluster. In some cases, it is possible that the host of the node to be scaled down is down, making it impossible to connect to the node via SSH for operations, so you can forcibly remove it from the cluster using the `-force` option. -- The default value is `false`. If you do not add this option in the command, the specified nodes are not forcibly removed. +- Default: false. If this option is not specified in the command, the specified nodes are not forcibly removed. > **Note:** > > Because the forced removal of a TiKV node does not wait for data to be scheduled, removing more than one serving TiKV node is in the risk of data loss. -### --transfer-timeout ${unit} +### --transfer-timeout - When a PD or TiKV node is to be scaled down, the leader role of the node will be migrated to other nodes first. Because the migration process takes some time, you can set the maximum waiting time (in seconds) by configuring `-transfer-timeout`. After the timeout, the `tiup cluster scale-in` command skips waiting and starts the scaling down directly. -- If you do not add this option in the command, the default waiting time of leader migration is `300` seconds. +- Data type: `UINT` +- If this option is not specified in the command, the default waiting time of leader migration is `300` seconds. > **Note:** > @@ -60,10 +61,10 @@ tiup cluster scale-in [flags] ### -h, --help +- Shows the help information in the output. - Data type: `BOOLEAN` -- Shows the help information. -- If you do not specify this option in the command, the default value is `false` so the help information is not shown. +- Default: false ## Output -Shows the logs of the scaling down process. \ No newline at end of file +Shows the logs of the scaling down process. diff --git a/tiup/tiup-component-dm-list.md b/tiup/tiup-component-dm-list.md index e161023905a85..400200962d230 100644 --- a/tiup/tiup-component-dm-list.md +++ b/tiup/tiup-component-dm-list.md @@ -4,10 +4,10 @@ title: tiup dm list # tiup dm list -`tiup-dm` supports deploying multiple clusters with the same central console. You can use the command `tiup dm list` to check which clusters are deployed using the central console by the currently logged-in user. +`tiup-dm` supports deploying multiple clusters using the same central console. You can use the `tiup dm list` command to check which clusters are deployed using the central console by the currently logged-in user. > **Note:** -> +> > By default, the data of the deployed clusters is stored in the `~/.tiup/storage/dm/clusters/` directory. The currently logged-in user cannot view the clusters deployed by other users on the same central console. ## Syntax @@ -18,17 +18,18 @@ tiup dm list [flags] ## Options -### -h, --help (boolean, default false) +### -h, --help -Show help information in the output. +- Shows the help information in the output. +- Data type: `BOOLEAN` +- Default: false ## Output -The output is a table containing the following fields. +The output of the command is a table containing the following fields: - Name: the cluster name - User: the user who deployed the cluster - Version: the cluster version - Path: the path of the cluster deployment data on the central control machine - PrivateKey: the path of the private key to the cluster - From 0d217f531d238565a9844cf6b87015b050429209 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 9 Apr 2021 11:35:07 +0800 Subject: [PATCH 04/20] Updated the title --- tiup/tiup-component-cluster-scale-in.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index 4eeedbd4998d3..2c310371417c7 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -29,7 +29,7 @@ Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynch tiup cluster scale-in [flags] ``` -`` is the name of the cluster to be scaled down. If you forget the cluster name, check the name in [cluster-list](/tiup/tiup-component-cluster-list.md). +`` is the name of the cluster to be scaled down. If you forget the cluster name, check the name in [tiup cluster list](/tiup/tiup-component-cluster-list.md). ## Options From 2b94d6675a790f348be572c117b400d465f99f9c Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 9 Apr 2021 12:02:30 +0800 Subject: [PATCH 05/20] Aligned the style with other merged PRs --- tiup/tiup-component-dm-list.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tiup/tiup-component-dm-list.md b/tiup/tiup-component-dm-list.md index 400200962d230..efba5d34c01db 100644 --- a/tiup/tiup-component-dm-list.md +++ b/tiup/tiup-component-dm-list.md @@ -26,10 +26,10 @@ tiup dm list [flags] ## Output -The output of the command is a table containing the following fields: +A table consisting of the following fields: -- Name: the cluster name -- User: the user who deployed the cluster -- Version: the cluster version -- Path: the path of the cluster deployment data on the central control machine -- PrivateKey: the path of the private key to the cluster +- `Name`: the cluster name. +- `User`: the user who deployed the cluster. +- `Version`: the cluster version. +- `Path`: the path of the cluster deployment data on the central control machine. +- `PrivateKey`: the path of the private key to the cluster. From 25baa40c42e9f326856f2c12122e39763e3882e6 Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 12 Apr 2021 18:12:35 +0800 Subject: [PATCH 06/20] Updated the wording --- tiup/tiup-component-cluster-import.md | 12 ++++++------ tiup/tiup-component-cluster-scale-in.md | 25 ++++++++++++------------- tiup/tiup-component-dm-list.md | 4 ++-- 3 files changed, 20 insertions(+), 21 deletions(-) diff --git a/tiup/tiup-component-cluster-import.md b/tiup/tiup-component-cluster-import.md index 24a7258d84225..abcd4311da612 100644 --- a/tiup/tiup-component-cluster-import.md +++ b/tiup/tiup-component-cluster-import.md @@ -30,25 +30,25 @@ tiup cluster import [flags] - Specifies the directory where TiDB Ansible is located. - Data type: `STRING` -- If this option is not specified in the command, the current directory is regarded as the directory where TiDB Ansible is located. +- The option is enabled by default with the current directory (the default value) passed in. ### --ansible-config - Specifies the path of the Ansible configuration file. - Data type: `STRING` -- If this option is not specified in the command, the default path `. /ansible.cfg` is used in the import. +- The option is enabled by default with `. /ansible.cfg` (the default value) passed in. ### --inventory - Specifies the name of the Ansible inventory file. - Data type: `STRING` -- If this option is not specified in the command, the default name `inventory.ini` is used in the import. +- The option is enabled by default with `inventory.ini` (the default value) passed in. ### --no-backup - Controls whether to disable the backup of files in the directory where TiDB Ansible is located. - Data type: `BOOLEAN` -- Default: false. If this option is not specified in the command, after a successful import, everything in the directory specified by the `-dir` option is backed up to the `${TIUP_HOME}/.tiup/storage/cluster/clusters/{cluster-name}/ansible-backup` directory. If there are multiple inventory files (which indicates multiple clusters are deployed) in this directory, it is recommended to add this option in the `import` command to disable the default backup step. +- This option is disabled by default with the `false` value. After a successful import, everything in the directory specified by the `-dir` option is backed up to the `${TIUP_HOME}/.tiup/storage/cluster/clusters/{cluster-name}/ansible-backup` directory. If there are multiple inventory files (when multiple clusters are deployed) in this directory, it is recommended to enable this option. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. ### --rename @@ -58,9 +58,9 @@ tiup cluster import [flags] ### -h, --help -- Shows the help information in the output. +- Prints the help information. - Data type: `BOOLEAN` -- Default: false +- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. ## Output diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index 2c310371417c7..56d856bcb54d1 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -4,15 +4,15 @@ title: tiup cluster scale-in # tiup cluster scale-in -The `tiup cluster scale-in` command is used to scale down the cluster, which takes the services of the specified nodes offline, removes the specified nodes from the cluster, and deletes the remaining files from those nodes. +The `tiup cluster scale-in` command is used to scale in the cluster, which takes the services of the specified nodes offline, removes the specified nodes from the cluster, and deletes the remaining files from those nodes. Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynchronously (the removal needs to be executed by the API first) and the stopping process takes a long time (the command needs to keep checking whether the specified nodes have been successfully stopped), the `tiup cluster scale-in` command handles the TiKV, TiFlash and TiDB Binlog components particularly as follows: - For TiKV, TiFlash and TiDB Binlog components, the `tiup cluster scale-in` command makes the following operations: - - Exit tiup-cluster directly after it is stopped by the API without waiting for the entire stopping process to be completed. - - Execute the `tiup cluster display` command to check the status of the nodes being scaled down and wait for the status to change to `Tombstone`. - - Execute the `tiup cluster prune` command to clean up the nodes in the `Tombstone` status, which performs the following operations: + - Exit tiup-cluster directly after it is stopped by the API without waiting for the entire stopping process to be completed. + - Execute the `tiup cluster display` command to check the status of the nodes being scaled down and wait for the status to change to `Tombstone`. + - Execute the `tiup cluster prune` command to clean up the nodes in the `Tombstone` status, which performs the following operations: - Stop the services of the nodes that have been taken offline. - Clean up the data files of the nodes that have been taken offline. @@ -20,8 +20,8 @@ Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynch - For other components, the `tiup cluster scale-in` command makes the following operations: - - To take the PD nodes offline, the command uses the API to remove the specified PD nodes from the cluster (this process is fast), stops the services of the specified PD nodes, and then cleans up the data files of the specified PD nodes. - - To take other components offline, the command stops the nodes and cleans up the related data files directly. + - To take the PD nodes offline, the command uses the API to remove the specified PD nodes from the cluster (this process is fast), stops the services of the specified PD nodes, and then cleans up the data files of the specified PD nodes. + - To take other components offline, the command stops the nodes and cleans up the related data files directly. ## Syntax @@ -29,21 +29,20 @@ Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynch tiup cluster scale-in [flags] ``` -`` is the name of the cluster to be scaled down. If you forget the cluster name, check the name in [tiup cluster list](/tiup/tiup-component-cluster-list.md). +`` is the name of the cluster to scale down. If you forget the cluster name, check the name in [tiup cluster list](/tiup/tiup-component-cluster-list.md). ## Options ### -N, --node -- Specifies the nodes to be scaled down, split by commas if scaling multiple nodes. - Data type: `STRING` - There is no default value. This option is mandatory and the value must be not null. ### --force -- Controls whether to forcibly remove the specified nodes from the cluster. In some cases, it is possible that the host of the node to be scaled down is down, making it impossible to connect to the node via SSH for operations, so you can forcibly remove the node from the cluster using the `-force` option. +- Controls whether to forcibly remove the specified nodes from the cluster. In some cases, it is possible that the host of the node to scale down is down, making it impossible to connect to the node via SSH for operations, so you can forcibly remove the node from the cluster using the `-force` option. - Data type: `BOOLEAN` -- Default: false. If this option is not specified in the command, the specified nodes are not forcibly removed. +- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. > **Note:** > @@ -53,7 +52,7 @@ tiup cluster scale-in [flags] - When a PD or TiKV node is to be scaled down, the leader role of the node will be migrated to other nodes first. Because the migration process takes some time, you can set the maximum waiting time (in seconds) by configuring `-transfer-timeout`. After the timeout, the `tiup cluster scale-in` command skips waiting and starts the scaling down directly. - Data type: `UINT` -- If this option is not specified in the command, the default waiting time of leader migration is `300` seconds. +- The option is enabled by default with `300` seconds (the default value) passed in. > **Note:** > @@ -61,9 +60,9 @@ tiup cluster scale-in [flags] ### -h, --help -- Shows the help information in the output. +- Prints the help information. - Data type: `BOOLEAN` -- Default: false +- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. ## Output diff --git a/tiup/tiup-component-dm-list.md b/tiup/tiup-component-dm-list.md index efba5d34c01db..8c58e1ac10804 100644 --- a/tiup/tiup-component-dm-list.md +++ b/tiup/tiup-component-dm-list.md @@ -20,9 +20,9 @@ tiup dm list [flags] ### -h, --help -- Shows the help information in the output. +- Prints the help information. - Data type: `BOOLEAN` -- Default: false +- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. ## Output From f035621ca53c0af0feced470d4a7dae744825993 Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 12 Apr 2021 18:12:52 +0800 Subject: [PATCH 07/20] Update tiup-component-cluster-scale-in.md --- tiup/tiup-component-cluster-scale-in.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index 56d856bcb54d1..2d57f43e7e579 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -35,6 +35,7 @@ tiup cluster scale-in [flags] ### -N, --node +- Specifies the nodes to scale down, splitting by commas for multiple nodes. - Data type: `STRING` - There is no default value. This option is mandatory and the value must be not null. From dace733579c25c8a345578ad45d22600f6adadb1 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 9 Apr 2021 09:31:41 +0800 Subject: [PATCH 08/20] TiUP: add two documents for cluster import and scale-in --- tiup/tiup-component-cluster-import.md | 67 ++++++++++++++++++++++++ tiup/tiup-component-cluster-scale-in.md | 69 +++++++++++++++++++++++++ 2 files changed, 136 insertions(+) create mode 100644 tiup/tiup-component-cluster-import.md create mode 100644 tiup/tiup-component-cluster-scale-in.md diff --git a/tiup/tiup-component-cluster-import.md b/tiup/tiup-component-cluster-import.md new file mode 100644 index 0000000000000..c9c2596269e90 --- /dev/null +++ b/tiup/tiup-component-cluster-import.md @@ -0,0 +1,67 @@ +--- +title: tiup cluster import +--- + +# tiup cluster import + +Before TiDB 4.0, clusters were usually deployed using TiDB Ansible. From TiDB 4.0 onwards, TiUP Cluster provides the `import` command to transfer these clusters to the tiup-cluster component for the management. + +> **Note:** +> +> + After importing the TiDB Ansible configuration to TiUP for the management, do not use TiDB Ansible for cluster operations anymore. Otherwise, conflicts might be caused due to inconsistent meta information. +> + The `import` command does not support the import of the following clusters. If the clusters deployed using TiDB Ansible are in any of the following scenarios, do not use the `import` command. +> + Clusters with TLS encryption enabled +> + Pure KV clusters (clusters without TiDB instances) +> + Clusters with `Kafka` enabled +> + Clusters with `Spark` enabled +> + Clusters with TiDB Lightning/Importer enabled +> + Clusters still using the old `push` mode to collect monitoring metrics (if you keep the default mode `pull` unchanged, using the `import` command is supported) +> + Clusters in which the non-default ports (the ports configured in the `group_vars` directory are compatible) are separately configured in the `inventory.ini` configuration file using `node_exporter_port` / `blackbox_exporter_port` + +## Syntax + +```sh +tiup cluster import [flags] +``` + +## Options + +### -d, --dir ${string} + +- Data type: `STRING` +- Specifies the directory where TiDB Ansible is located. +- If you do not specify this option in the command, the current directory is regarded as the directory where TiDB Ansible is located. + +### --ansible-config ${string} + +- Data type: `STRING` +- Specifies the path of the Ansible configuration file. +- If you do not specify this option in the command, the default path `. /ansible.cfg` is used in the import. + +### --inventory ${string} + +- Data type: `STRING` +- Specifies the name of the Ansible inventory file. +- If you do not specify this option in the command, the default name `inventory.ini` is used in the import. + +### --no-backup + +- Data type: `BOOLEAN` +- Controls whether to disable the backup of files in the directory where TiDB Ansible is located. +- If you do not specify this option in the command, after a successful import, everything in the directory specified by the `-dir` option is backed up to the `${TIUP_HOME}/.tiup/storage/cluster/clusters/{cluster-name}/ansible-backup` directory. If there are multiple inventory files (which indicates multiple clusters are deployed) in this directory, it is recommended to include this option in the `import` command to disable the default backup step. + +### --rename ${string} + +- Data type: `STRING` +- Renames the imported cluster. +- If you do not specify this option in the command, the cluster_name specified in inventory is used as the cluster name. + +### -h, --help + +- Data type: `BOOLEAN` +- Shows the help information. +- If you do not specify this option in the command, the default value is `false` so the help information is not shown. + +## Output + +Shows the logs of the import process. diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md new file mode 100644 index 0000000000000..d4d8b272c2e6b --- /dev/null +++ b/tiup/tiup-component-cluster-scale-in.md @@ -0,0 +1,69 @@ +--- +title: tiup cluster scale-in +--- + +# tiup cluster scale-in + +The `tiup cluster scale-in` command is used to scale down the cluster, which takes the services of the specified nodes offline, removes the specified nodes from the cluster, and deletes the remaining files from those nodes. + +Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynchronously (the removal needs to be executed by the API first) and the stopping process takes a long time (the command needs to keep checking whether the specified nodes have been successfully stopped), the `tiup cluster scale-in` command handles the TiKV, TiFlash and TiDB Binlog components particularly as follows: + +- For TiKV, TiFlash and TiDB Binlog components, the `tiup cluster scale-in` command makes the following operations: + + - Exit tiup-cluster directly after it is stopped by the API without waiting for the entire stopping process to be completed. + - Execute the `tiup cluster display` command to check the status of the nodes being scaled down and wait for the status to change to `Tombstone`. + - Execute the `tiup cluster prune` command to clean up the nodes in the `Tombstone` status, which performs the following operations: + + - Stop the services of the nodes that have been taken offline. + - Clean up the data files of the nodes that have been taken offline. + - Update the cluster topology and remove the nodes that have been taken offline. + +- For other components, the `tiup cluster scale-in` command makes the following operations: + + - To take the PD nodes offline, the command uses the API to remove the specified PD nodes from the cluster (this process is fast), stops the services of the specified PD nodes, and then cleans up the data files of the specified PD nodes. + - To take other components offline, the command stops the nodes and cleans up the related data files directly. + +## Syntax + +```sh +tiup cluster scale-in [flags] +``` + +`` is the name of the cluster to be scaled down. If you forget the cluster name, check the name in [cluster-list](/tiup/tiup-component-cluster-list.md). + +## Options + +### -N, --node ${strings} + +- Data type: `STRING` +- Specifies the nodes to be scaled down, split by commas if scaling multiple nodes. +- There is no default value. This option is mandatory. + +### --force + +- Data type: `BOOLEAN` +- Controls whether to forcibly remove the specified nodes from the cluster. In some cases, it is possible that the host of the node to be scaled down is down, making it impossible to connect to the node via SSH for operations, so you can forcibly remove it from the cluster using the `-force` option. +- The default value is `false`. If you do not add this option in the command, the specified nodes are not forcibly removed. + +> **Note:** +> +> Because the forced removal of a TiKV node does not wait for data to be scheduled, removing more than one serving TiKV node is in the risk of data loss. + +### --transfer-timeout ${unit} + +- When a PD or TiKV node is to be scaled down, the leader role of the node will be migrated to other nodes first. Because the migration process takes some time, you can set the maximum waiting time (in seconds) by configuring `-transfer-timeout`. After the timeout, the `tiup cluster scale-in` command skips waiting and starts the scaling down directly. +- If you do not add this option in the command, the default waiting time of leader migration is `300` seconds. + +> **Note:** +> +> If a PD or TiKV node is scaled down directly without waiting for the leader role migration to be completed, the service performance may jitter. + +### -h, --help + +- Data type: `BOOLEAN` +- Shows the help information. +- If you do not specify this option in the command, the default value is `false` so the help information is not shown. + +## Output + +Shows the logs of the scaling down process. \ No newline at end of file From ee132c194225bf2bfe6f09d68e9c23f348b83f00 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 9 Apr 2021 10:05:43 +0800 Subject: [PATCH 09/20] Create tiup-component-dm-list.md --- tiup/tiup-component-dm-list.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 tiup/tiup-component-dm-list.md diff --git a/tiup/tiup-component-dm-list.md b/tiup/tiup-component-dm-list.md new file mode 100644 index 0000000000000..e161023905a85 --- /dev/null +++ b/tiup/tiup-component-dm-list.md @@ -0,0 +1,34 @@ +--- +title: tiup dm list +--- + +# tiup dm list + +`tiup-dm` supports deploying multiple clusters with the same central console. You can use the command `tiup dm list` to check which clusters are deployed using the central console by the currently logged-in user. + +> **Note:** +> +> By default, the data of the deployed clusters is stored in the `~/.tiup/storage/dm/clusters/` directory. The currently logged-in user cannot view the clusters deployed by other users on the same central console. + +## Syntax + +```sh +tiup dm list [flags] +``` + +## Options + +### -h, --help (boolean, default false) + +Show help information in the output. + +## Output + +The output is a table containing the following fields. + +- Name: the cluster name +- User: the user who deployed the cluster +- Version: the cluster version +- Path: the path of the cluster deployment data on the central control machine +- PrivateKey: the path of the private key to the cluster + From 4f5bf21baab54dd289a20aa669798ce198521f74 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 9 Apr 2021 11:17:38 +0800 Subject: [PATCH 10/20] Updated the style --- tiup/tiup-component-cluster-import.md | 34 ++++++++++++------------- tiup/tiup-component-cluster-scale-in.md | 21 +++++++-------- tiup/tiup-component-dm-list.md | 13 +++++----- 3 files changed, 35 insertions(+), 33 deletions(-) diff --git a/tiup/tiup-component-cluster-import.md b/tiup/tiup-component-cluster-import.md index c9c2596269e90..24a7258d84225 100644 --- a/tiup/tiup-component-cluster-import.md +++ b/tiup/tiup-component-cluster-import.md @@ -4,7 +4,7 @@ title: tiup cluster import # tiup cluster import -Before TiDB 4.0, clusters were usually deployed using TiDB Ansible. From TiDB 4.0 onwards, TiUP Cluster provides the `import` command to transfer these clusters to the tiup-cluster component for the management. +Before TiDB 4.0, clusters were usually deployed using TiDB Ansible. For TiDB 4.0 and later releases, TiUP Cluster provides the `import` command to transfer these clusters to the tiup-cluster component for the management. > **Note:** > @@ -26,41 +26,41 @@ tiup cluster import [flags] ## Options -### -d, --dir ${string} +### -d, --dir -- Data type: `STRING` - Specifies the directory where TiDB Ansible is located. -- If you do not specify this option in the command, the current directory is regarded as the directory where TiDB Ansible is located. +- Data type: `STRING` +- If this option is not specified in the command, the current directory is regarded as the directory where TiDB Ansible is located. -### --ansible-config ${string} +### --ansible-config -- Data type: `STRING` - Specifies the path of the Ansible configuration file. -- If you do not specify this option in the command, the default path `. /ansible.cfg` is used in the import. +- Data type: `STRING` +- If this option is not specified in the command, the default path `. /ansible.cfg` is used in the import. -### --inventory ${string} +### --inventory -- Data type: `STRING` - Specifies the name of the Ansible inventory file. -- If you do not specify this option in the command, the default name `inventory.ini` is used in the import. +- Data type: `STRING` +- If this option is not specified in the command, the default name `inventory.ini` is used in the import. ### --no-backup -- Data type: `BOOLEAN` - Controls whether to disable the backup of files in the directory where TiDB Ansible is located. -- If you do not specify this option in the command, after a successful import, everything in the directory specified by the `-dir` option is backed up to the `${TIUP_HOME}/.tiup/storage/cluster/clusters/{cluster-name}/ansible-backup` directory. If there are multiple inventory files (which indicates multiple clusters are deployed) in this directory, it is recommended to include this option in the `import` command to disable the default backup step. +- Data type: `BOOLEAN` +- Default: false. If this option is not specified in the command, after a successful import, everything in the directory specified by the `-dir` option is backed up to the `${TIUP_HOME}/.tiup/storage/cluster/clusters/{cluster-name}/ansible-backup` directory. If there are multiple inventory files (which indicates multiple clusters are deployed) in this directory, it is recommended to add this option in the `import` command to disable the default backup step. -### --rename ${string} +### --rename +- Renames the imported cluster. - Data type: `STRING` -- Renames the imported cluster. -- If you do not specify this option in the command, the cluster_name specified in inventory is used as the cluster name. +- Default: NULL. If this option is not specified in the command, the cluster_name specified in inventory is used as the cluster name. ### -h, --help +- Shows the help information in the output. - Data type: `BOOLEAN` -- Shows the help information. -- If you do not specify this option in the command, the default value is `false` so the help information is not shown. +- Default: false ## Output diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index d4d8b272c2e6b..4eeedbd4998d3 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -33,26 +33,27 @@ tiup cluster scale-in [flags] ## Options -### -N, --node ${strings} +### -N, --node -- Data type: `STRING` - Specifies the nodes to be scaled down, split by commas if scaling multiple nodes. -- There is no default value. This option is mandatory. +- Data type: `STRING` +- There is no default value. This option is mandatory and the value must be not null. ### --force +- Controls whether to forcibly remove the specified nodes from the cluster. In some cases, it is possible that the host of the node to be scaled down is down, making it impossible to connect to the node via SSH for operations, so you can forcibly remove the node from the cluster using the `-force` option. - Data type: `BOOLEAN` -- Controls whether to forcibly remove the specified nodes from the cluster. In some cases, it is possible that the host of the node to be scaled down is down, making it impossible to connect to the node via SSH for operations, so you can forcibly remove it from the cluster using the `-force` option. -- The default value is `false`. If you do not add this option in the command, the specified nodes are not forcibly removed. +- Default: false. If this option is not specified in the command, the specified nodes are not forcibly removed. > **Note:** > > Because the forced removal of a TiKV node does not wait for data to be scheduled, removing more than one serving TiKV node is in the risk of data loss. -### --transfer-timeout ${unit} +### --transfer-timeout - When a PD or TiKV node is to be scaled down, the leader role of the node will be migrated to other nodes first. Because the migration process takes some time, you can set the maximum waiting time (in seconds) by configuring `-transfer-timeout`. After the timeout, the `tiup cluster scale-in` command skips waiting and starts the scaling down directly. -- If you do not add this option in the command, the default waiting time of leader migration is `300` seconds. +- Data type: `UINT` +- If this option is not specified in the command, the default waiting time of leader migration is `300` seconds. > **Note:** > @@ -60,10 +61,10 @@ tiup cluster scale-in [flags] ### -h, --help +- Shows the help information in the output. - Data type: `BOOLEAN` -- Shows the help information. -- If you do not specify this option in the command, the default value is `false` so the help information is not shown. +- Default: false ## Output -Shows the logs of the scaling down process. \ No newline at end of file +Shows the logs of the scaling down process. diff --git a/tiup/tiup-component-dm-list.md b/tiup/tiup-component-dm-list.md index e161023905a85..400200962d230 100644 --- a/tiup/tiup-component-dm-list.md +++ b/tiup/tiup-component-dm-list.md @@ -4,10 +4,10 @@ title: tiup dm list # tiup dm list -`tiup-dm` supports deploying multiple clusters with the same central console. You can use the command `tiup dm list` to check which clusters are deployed using the central console by the currently logged-in user. +`tiup-dm` supports deploying multiple clusters using the same central console. You can use the `tiup dm list` command to check which clusters are deployed using the central console by the currently logged-in user. > **Note:** -> +> > By default, the data of the deployed clusters is stored in the `~/.tiup/storage/dm/clusters/` directory. The currently logged-in user cannot view the clusters deployed by other users on the same central console. ## Syntax @@ -18,17 +18,18 @@ tiup dm list [flags] ## Options -### -h, --help (boolean, default false) +### -h, --help -Show help information in the output. +- Shows the help information in the output. +- Data type: `BOOLEAN` +- Default: false ## Output -The output is a table containing the following fields. +The output of the command is a table containing the following fields: - Name: the cluster name - User: the user who deployed the cluster - Version: the cluster version - Path: the path of the cluster deployment data on the central control machine - PrivateKey: the path of the private key to the cluster - From cf44d11e1038b31a9f81cd391d82ff0bc78d5487 Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 9 Apr 2021 11:35:07 +0800 Subject: [PATCH 11/20] Updated the title --- tiup/tiup-component-cluster-scale-in.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index 4eeedbd4998d3..2c310371417c7 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -29,7 +29,7 @@ Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynch tiup cluster scale-in [flags] ``` -`` is the name of the cluster to be scaled down. If you forget the cluster name, check the name in [cluster-list](/tiup/tiup-component-cluster-list.md). +`` is the name of the cluster to be scaled down. If you forget the cluster name, check the name in [tiup cluster list](/tiup/tiup-component-cluster-list.md). ## Options From d73a10d169b3e6927da3421d2bf06552aaa8db2c Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 9 Apr 2021 12:02:30 +0800 Subject: [PATCH 12/20] Aligned the style with other merged PRs --- tiup/tiup-component-dm-list.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tiup/tiup-component-dm-list.md b/tiup/tiup-component-dm-list.md index 400200962d230..efba5d34c01db 100644 --- a/tiup/tiup-component-dm-list.md +++ b/tiup/tiup-component-dm-list.md @@ -26,10 +26,10 @@ tiup dm list [flags] ## Output -The output of the command is a table containing the following fields: +A table consisting of the following fields: -- Name: the cluster name -- User: the user who deployed the cluster -- Version: the cluster version -- Path: the path of the cluster deployment data on the central control machine -- PrivateKey: the path of the private key to the cluster +- `Name`: the cluster name. +- `User`: the user who deployed the cluster. +- `Version`: the cluster version. +- `Path`: the path of the cluster deployment data on the central control machine. +- `PrivateKey`: the path of the private key to the cluster. From 93fdca73ebb78559df47621d75bfa8b9e5b68104 Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 12 Apr 2021 18:12:35 +0800 Subject: [PATCH 13/20] Updated the wording --- tiup/tiup-component-cluster-import.md | 12 ++++++------ tiup/tiup-component-cluster-scale-in.md | 25 ++++++++++++------------- tiup/tiup-component-dm-list.md | 4 ++-- 3 files changed, 20 insertions(+), 21 deletions(-) diff --git a/tiup/tiup-component-cluster-import.md b/tiup/tiup-component-cluster-import.md index 24a7258d84225..abcd4311da612 100644 --- a/tiup/tiup-component-cluster-import.md +++ b/tiup/tiup-component-cluster-import.md @@ -30,25 +30,25 @@ tiup cluster import [flags] - Specifies the directory where TiDB Ansible is located. - Data type: `STRING` -- If this option is not specified in the command, the current directory is regarded as the directory where TiDB Ansible is located. +- The option is enabled by default with the current directory (the default value) passed in. ### --ansible-config - Specifies the path of the Ansible configuration file. - Data type: `STRING` -- If this option is not specified in the command, the default path `. /ansible.cfg` is used in the import. +- The option is enabled by default with `. /ansible.cfg` (the default value) passed in. ### --inventory - Specifies the name of the Ansible inventory file. - Data type: `STRING` -- If this option is not specified in the command, the default name `inventory.ini` is used in the import. +- The option is enabled by default with `inventory.ini` (the default value) passed in. ### --no-backup - Controls whether to disable the backup of files in the directory where TiDB Ansible is located. - Data type: `BOOLEAN` -- Default: false. If this option is not specified in the command, after a successful import, everything in the directory specified by the `-dir` option is backed up to the `${TIUP_HOME}/.tiup/storage/cluster/clusters/{cluster-name}/ansible-backup` directory. If there are multiple inventory files (which indicates multiple clusters are deployed) in this directory, it is recommended to add this option in the `import` command to disable the default backup step. +- This option is disabled by default with the `false` value. After a successful import, everything in the directory specified by the `-dir` option is backed up to the `${TIUP_HOME}/.tiup/storage/cluster/clusters/{cluster-name}/ansible-backup` directory. If there are multiple inventory files (when multiple clusters are deployed) in this directory, it is recommended to enable this option. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. ### --rename @@ -58,9 +58,9 @@ tiup cluster import [flags] ### -h, --help -- Shows the help information in the output. +- Prints the help information. - Data type: `BOOLEAN` -- Default: false +- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. ## Output diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index 2c310371417c7..56d856bcb54d1 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -4,15 +4,15 @@ title: tiup cluster scale-in # tiup cluster scale-in -The `tiup cluster scale-in` command is used to scale down the cluster, which takes the services of the specified nodes offline, removes the specified nodes from the cluster, and deletes the remaining files from those nodes. +The `tiup cluster scale-in` command is used to scale in the cluster, which takes the services of the specified nodes offline, removes the specified nodes from the cluster, and deletes the remaining files from those nodes. Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynchronously (the removal needs to be executed by the API first) and the stopping process takes a long time (the command needs to keep checking whether the specified nodes have been successfully stopped), the `tiup cluster scale-in` command handles the TiKV, TiFlash and TiDB Binlog components particularly as follows: - For TiKV, TiFlash and TiDB Binlog components, the `tiup cluster scale-in` command makes the following operations: - - Exit tiup-cluster directly after it is stopped by the API without waiting for the entire stopping process to be completed. - - Execute the `tiup cluster display` command to check the status of the nodes being scaled down and wait for the status to change to `Tombstone`. - - Execute the `tiup cluster prune` command to clean up the nodes in the `Tombstone` status, which performs the following operations: + - Exit tiup-cluster directly after it is stopped by the API without waiting for the entire stopping process to be completed. + - Execute the `tiup cluster display` command to check the status of the nodes being scaled down and wait for the status to change to `Tombstone`. + - Execute the `tiup cluster prune` command to clean up the nodes in the `Tombstone` status, which performs the following operations: - Stop the services of the nodes that have been taken offline. - Clean up the data files of the nodes that have been taken offline. @@ -20,8 +20,8 @@ Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynch - For other components, the `tiup cluster scale-in` command makes the following operations: - - To take the PD nodes offline, the command uses the API to remove the specified PD nodes from the cluster (this process is fast), stops the services of the specified PD nodes, and then cleans up the data files of the specified PD nodes. - - To take other components offline, the command stops the nodes and cleans up the related data files directly. + - To take the PD nodes offline, the command uses the API to remove the specified PD nodes from the cluster (this process is fast), stops the services of the specified PD nodes, and then cleans up the data files of the specified PD nodes. + - To take other components offline, the command stops the nodes and cleans up the related data files directly. ## Syntax @@ -29,21 +29,20 @@ Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynch tiup cluster scale-in [flags] ``` -`` is the name of the cluster to be scaled down. If you forget the cluster name, check the name in [tiup cluster list](/tiup/tiup-component-cluster-list.md). +`` is the name of the cluster to scale down. If you forget the cluster name, check the name in [tiup cluster list](/tiup/tiup-component-cluster-list.md). ## Options ### -N, --node -- Specifies the nodes to be scaled down, split by commas if scaling multiple nodes. - Data type: `STRING` - There is no default value. This option is mandatory and the value must be not null. ### --force -- Controls whether to forcibly remove the specified nodes from the cluster. In some cases, it is possible that the host of the node to be scaled down is down, making it impossible to connect to the node via SSH for operations, so you can forcibly remove the node from the cluster using the `-force` option. +- Controls whether to forcibly remove the specified nodes from the cluster. In some cases, it is possible that the host of the node to scale down is down, making it impossible to connect to the node via SSH for operations, so you can forcibly remove the node from the cluster using the `-force` option. - Data type: `BOOLEAN` -- Default: false. If this option is not specified in the command, the specified nodes are not forcibly removed. +- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. > **Note:** > @@ -53,7 +52,7 @@ tiup cluster scale-in [flags] - When a PD or TiKV node is to be scaled down, the leader role of the node will be migrated to other nodes first. Because the migration process takes some time, you can set the maximum waiting time (in seconds) by configuring `-transfer-timeout`. After the timeout, the `tiup cluster scale-in` command skips waiting and starts the scaling down directly. - Data type: `UINT` -- If this option is not specified in the command, the default waiting time of leader migration is `300` seconds. +- The option is enabled by default with `300` seconds (the default value) passed in. > **Note:** > @@ -61,9 +60,9 @@ tiup cluster scale-in [flags] ### -h, --help -- Shows the help information in the output. +- Prints the help information. - Data type: `BOOLEAN` -- Default: false +- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. ## Output diff --git a/tiup/tiup-component-dm-list.md b/tiup/tiup-component-dm-list.md index efba5d34c01db..8c58e1ac10804 100644 --- a/tiup/tiup-component-dm-list.md +++ b/tiup/tiup-component-dm-list.md @@ -20,9 +20,9 @@ tiup dm list [flags] ### -h, --help -- Shows the help information in the output. +- Prints the help information. - Data type: `BOOLEAN` -- Default: false +- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. ## Output From 27e90097e2cb8587a8b4d6d6f1eb223b82ed5ebb Mon Sep 17 00:00:00 2001 From: qiancai Date: Mon, 12 Apr 2021 18:12:52 +0800 Subject: [PATCH 14/20] Update tiup-component-cluster-scale-in.md --- tiup/tiup-component-cluster-scale-in.md | 1 + 1 file changed, 1 insertion(+) diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index 56d856bcb54d1..2d57f43e7e579 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -35,6 +35,7 @@ tiup cluster scale-in [flags] ### -N, --node +- Specifies the nodes to scale down, splitting by commas for multiple nodes. - Data type: `STRING` - There is no default value. This option is mandatory and the value must be not null. From 36de320a4d85486df45f309382218c29f33ba45d Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 15 Apr 2021 17:13:44 +0800 Subject: [PATCH 15/20] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- tiup/tiup-component-cluster-import.md | 14 +++++++------- tiup/tiup-component-cluster-scale-in.md | 14 +++++++------- tiup/tiup-component-dm-list.md | 8 ++++---- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/tiup/tiup-component-cluster-import.md b/tiup/tiup-component-cluster-import.md index abcd4311da612..e49c318cb0a46 100644 --- a/tiup/tiup-component-cluster-import.md +++ b/tiup/tiup-component-cluster-import.md @@ -4,23 +4,23 @@ title: tiup cluster import # tiup cluster import -Before TiDB 4.0, clusters were usually deployed using TiDB Ansible. For TiDB 4.0 and later releases, TiUP Cluster provides the `import` command to transfer these clusters to the tiup-cluster component for the management. +Before TiDB v4.0, TiDB clusters were mainly deployed using TiDB Ansible. For TiDB v4.0 and later releases, TiUP Cluster provides the `import` command to transfer the clusters to the tiup-cluster component for management. > **Note:** > -> + After importing the TiDB Ansible configuration to TiUP for the management, do not use TiDB Ansible for cluster operations anymore. Otherwise, conflicts might be caused due to inconsistent meta information. -> + The `import` command does not support the import of the following clusters. If the clusters deployed using TiDB Ansible are in any of the following scenarios, do not use the `import` command. +> + After importing the TiDB Ansible configuration to TiUP for management, **DO NOT** use TiDB Ansible for cluster operations anymore. Otherwise, conflicts might be caused due to inconsistent meta information. +> + If the clusters deployed using TiDB Ansible are in any of the following situations, do not use the `import` command. > + Clusters with TLS encryption enabled > + Pure KV clusters (clusters without TiDB instances) -> + Clusters with `Kafka` enabled -> + Clusters with `Spark` enabled -> + Clusters with TiDB Lightning/Importer enabled +> + Clusters with Kafka enabled +> + Clusters with Spark enabled +> + Clusters with TiDB Lightning/TiKV Importer enabled > + Clusters still using the old `push` mode to collect monitoring metrics (if you keep the default mode `pull` unchanged, using the `import` command is supported) > + Clusters in which the non-default ports (the ports configured in the `group_vars` directory are compatible) are separately configured in the `inventory.ini` configuration file using `node_exporter_port` / `blackbox_exporter_port` ## Syntax -```sh +```shell tiup cluster import [flags] ``` diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index 2d57f43e7e579..775a94aa0d7ab 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -12,7 +12,7 @@ Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynch - Exit tiup-cluster directly after it is stopped by the API without waiting for the entire stopping process to be completed. - Execute the `tiup cluster display` command to check the status of the nodes being scaled down and wait for the status to change to `Tombstone`. - - Execute the `tiup cluster prune` command to clean up the nodes in the `Tombstone` status, which performs the following operations: + - Execute the `tiup cluster prune` command to clean up the nodes in the `Tombstone` status. The `tiup cluster prune` command performs the following operations: - Stop the services of the nodes that have been taken offline. - Clean up the data files of the nodes that have been taken offline. @@ -21,15 +21,15 @@ Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynch - For other components, the `tiup cluster scale-in` command makes the following operations: - To take the PD nodes offline, the command uses the API to remove the specified PD nodes from the cluster (this process is fast), stops the services of the specified PD nodes, and then cleans up the data files of the specified PD nodes. - - To take other components offline, the command stops the nodes and cleans up the related data files directly. + - To take other components offline, the command directly stops the nodes and cleans up the related data files. ## Syntax -```sh +```shell tiup cluster scale-in [flags] ``` -`` is the name of the cluster to scale down. If you forget the cluster name, check the name in [tiup cluster list](/tiup/tiup-component-cluster-list.md). +`` is the name of the cluster to scale in. If you forget the cluster name, check the name returned by [`tiup cluster list`](/tiup/tiup-component-cluster-list.md). ## Options @@ -47,7 +47,7 @@ tiup cluster scale-in [flags] > **Note:** > -> Because the forced removal of a TiKV node does not wait for data to be scheduled, removing more than one serving TiKV node is in the risk of data loss. +> Because the forced removal of a TiKV node does not wait for data to be scheduled, removing more than one serving TiKV node is at the risk of data loss. ### --transfer-timeout @@ -57,7 +57,7 @@ tiup cluster scale-in [flags] > **Note:** > -> If a PD or TiKV node is scaled down directly without waiting for the leader role migration to be completed, the service performance may jitter. +> If a PD or TiKV node is taken offline directly without waiting for the leader transfer to be completed, the service performance might jitter. ### -h, --help @@ -67,4 +67,4 @@ tiup cluster scale-in [flags] ## Output -Shows the logs of the scaling down process. +Shows the logs of the scaling-in process. diff --git a/tiup/tiup-component-dm-list.md b/tiup/tiup-component-dm-list.md index 8c58e1ac10804..7339da8ef2927 100644 --- a/tiup/tiup-component-dm-list.md +++ b/tiup/tiup-component-dm-list.md @@ -4,15 +4,15 @@ title: tiup dm list # tiup dm list -`tiup-dm` supports deploying multiple clusters using the same central console. You can use the `tiup dm list` command to check which clusters are deployed using the central console by the currently logged-in user. +`tiup-dm` supports deploying multiple clusters using the same control machine. You can use the `tiup dm list` command to check which clusters are deployed using the control machine by the currently logged-in user. > **Note:** > -> By default, the data of the deployed clusters is stored in the `~/.tiup/storage/dm/clusters/` directory. The currently logged-in user cannot view the clusters deployed by other users on the same central console. +> By default, the data of the deployed clusters is stored in the `~/.tiup/storage/dm/clusters/` directory. The currently logged-in user cannot view the clusters deployed by other users on the same control machine. ## Syntax -```sh +```shell tiup dm list [flags] ``` @@ -31,5 +31,5 @@ A table consisting of the following fields: - `Name`: the cluster name. - `User`: the user who deployed the cluster. - `Version`: the cluster version. -- `Path`: the path of the cluster deployment data on the central control machine. +- `Path`: the path of the cluster deployment data on the control machine. - `PrivateKey`: the path of the private key to the cluster. From fa72f97bc7bd35fbdb9039914929c699108a85ba Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 16 Apr 2021 12:14:19 +0800 Subject: [PATCH 16/20] Update tiup/tiup-component-cluster-scale-in.md --- tiup/tiup-component-cluster-scale-in.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index b0d7c303b88c4..df238157060a9 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -6,7 +6,7 @@ title: tiup cluster scale-in The `tiup cluster scale-in` command is used to scale in the cluster, which takes the services of the specified nodes offline, removes the specified nodes from the cluster, and deletes the remaining files from those nodes. -Because the TiKV, TiFlash and TiDB Binlog components are taken to offline asynchronously (the removal needs to be executed by the API first) and the stopping process takes a long time (the command needs to keep checking whether the specified nodes have been successfully stopped), the `tiup cluster scale-in` command handles the TiKV, TiFlash and TiDB Binlog components particularly as follows: +Because the TiKV, TiFlash, and TiDB Binlog components are taken offline asynchronously (the removal needs to be executed through the API first) and the stopping process takes a long time (TiUP needs to keep checking whether the specified nodes have been successfully stopped), the `tiup cluster scale-in` command handles the TiKV, TiFlash, and TiDB Binlog components particularly as follows: - For TiKV, TiFlash and TiDB Binlog components, the `tiup cluster scale-in` command makes the following operations: From 91af73b90666f82a629e986b2f70055250a51e9c Mon Sep 17 00:00:00 2001 From: qiancai Date: Fri, 16 Apr 2021 14:01:56 +0800 Subject: [PATCH 17/20] Update tiup-component-cluster-scale-in.md --- tiup/tiup-component-cluster-scale-in.md | 26 ++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index df238157060a9..e1af54d85f5be 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -6,22 +6,22 @@ title: tiup cluster scale-in The `tiup cluster scale-in` command is used to scale in the cluster, which takes the services of the specified nodes offline, removes the specified nodes from the cluster, and deletes the remaining files from those nodes. -Because the TiKV, TiFlash, and TiDB Binlog components are taken offline asynchronously (the removal needs to be executed through the API first) and the stopping process takes a long time (TiUP needs to keep checking whether the specified nodes have been successfully stopped), the `tiup cluster scale-in` command handles the TiKV, TiFlash, and TiDB Binlog components particularly as follows: +Because the TiKV, TiFlash, and TiDB Binlog components are taken offline asynchronously (which requires TiUP to remove the node through API first) and the stopping process takes a long time (which requires TiUP to continuously check whether the node is successfully taken offline), the TiKV, TiFlash, and TiDB Binlog components are handled particularly as follows: -- For TiKV, TiFlash and TiDB Binlog components, the `tiup cluster scale-in` command makes the following operations: +- For TiKV, TiFlash and TiDB Binlog components: - - Exit tiup-cluster directly after it is stopped by the API without waiting for the entire stopping process to be completed. - - Execute the `tiup cluster display` command to check the status of the nodes being scaled down and wait for the status to change to `Tombstone`. - - Execute the `tiup cluster prune` command to clean up the nodes in the `Tombstone` status, which performs the following operations: + 1. TiUP takes the node offline through API and directly exits without waiting for the process to be completed. + 2. To check the status of the nodes being scaled in, you need to execute the `tiup cluster display` command, and wait for the status to be changed to `Tombstone`. + 3. To clean up the nodes in the `Tombstone` status, you need to execute the `tiup cluster prune` command. The `tiup cluster prune` command performs the following operations: - - Stop the services of the nodes that have been taken offline. - - Clean up the data files of the nodes that have been taken offline. - - Update the cluster topology and remove the nodes that have been taken offline. + - Stops the services of the nodes that have been taken offline. + - Cleans up the data files of the nodes that have been taken offline. + - Updates the cluster topology and remove the nodes that have been taken offline. -- For other components, the `tiup cluster scale-in` command makes the following operations: +- For other components: - - To take the PD nodes offline, the command uses the API to remove the specified PD nodes from the cluster (this process is fast), stops the services of the specified PD nodes, and then cleans up the data files of the specified PD nodes. - - To take other components offline, the command directly stops the nodes and cleans up the related data files. + - When taking the PD components offline, TiUP cluster quickly deletes the specified nodes from the cluster through API, stops the service of the specified PD nodes, and then deletes the related data files from the nodes. + - When taking other components down, TiUP cluster directly stops the node services and deletes the related data files from the specified nodes. ## Syntax @@ -29,13 +29,13 @@ Because the TiKV, TiFlash, and TiDB Binlog components are taken offline asynchro tiup cluster scale-in [flags] ``` -`` is the name of the cluster to scale in. If you forget the cluster name, check the name returned by [`tiup cluster list`](/tiup/tiup-component-cluster-list.md). +`` is the name of the cluster to scale in. If you forget the cluster name, you can check it using the [`tiup cluster list`](/tiup/tiup-component-cluster-list.md) command. ## Options ### -N, --node -- Specifies the nodes to scale down, splitting by commas for multiple nodes. +- Specifies the nodes to scale in, splitting by commas for multiple nodes. - Data type: `STRING` - There is no default value. This option is mandatory and the value must be not null. From bd46e29fcda62e33c86c2488001623d1a0aa8ca5 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 16 Apr 2021 14:02:28 +0800 Subject: [PATCH 18/20] Update tiup/tiup-component-cluster-scale-in.md Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- tiup/tiup-component-cluster-scale-in.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index e1af54d85f5be..ef2cb752623ec 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -51,7 +51,7 @@ tiup cluster scale-in [flags] ### --transfer-timeout -- When a PD or TiKV node is to be scaled down, the leader role of the node will be migrated to other nodes first. Because the migration process takes some time, you can set the maximum waiting time (in seconds) by configuring `-transfer-timeout`. After the timeout, the `tiup cluster scale-in` command skips waiting and starts the scaling down directly. +- When a PD or TiKV node is to be removed, the Region leader on the node will be transferred to another node first. Because the transferring process takes some time, you can set the maximum waiting time (in seconds) by configuring `--transfer-timeout`. After the timeout, the `tiup cluster scale-in` command skips waiting and starts the scaling-in directly. - Data type: `UINT` - The option is enabled by default with `300` seconds (the default value) passed in. From c89918958240686c7bd26544091afc1f6124a356 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 16 Apr 2021 14:02:41 +0800 Subject: [PATCH 19/20] Update tiup/tiup-component-cluster-scale-in.md Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- tiup/tiup-component-cluster-scale-in.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index ef2cb752623ec..d69112e120007 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -41,7 +41,7 @@ tiup cluster scale-in [flags] ### --force -- Controls whether to forcibly remove the specified nodes from the cluster. In some cases, it is possible that the host of the node to scale down is down, making it impossible to connect to the node via SSH for operations, so you can forcibly remove the node from the cluster using the `-force` option. +- Controls whether to forcibly remove the specified nodes from the cluster. Sometimes, the host of the node to take offline might be down, which makes it impossible to connect to the node via SSH for operations, so you can forcibly remove the node from the cluster using the `-force` option. - Data type: `BOOLEAN` - This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value. From 6036663ef0c3ce9eb3e80f60a66f749941c60a8c Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 16 Apr 2021 14:48:06 +0800 Subject: [PATCH 20/20] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- tiup/tiup-component-cluster-scale-in.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/tiup/tiup-component-cluster-scale-in.md b/tiup/tiup-component-cluster-scale-in.md index d69112e120007..aaa96dfa1934a 100644 --- a/tiup/tiup-component-cluster-scale-in.md +++ b/tiup/tiup-component-cluster-scale-in.md @@ -8,20 +8,20 @@ The `tiup cluster scale-in` command is used to scale in the cluster, which takes Because the TiKV, TiFlash, and TiDB Binlog components are taken offline asynchronously (which requires TiUP to remove the node through API first) and the stopping process takes a long time (which requires TiUP to continuously check whether the node is successfully taken offline), the TiKV, TiFlash, and TiDB Binlog components are handled particularly as follows: -- For TiKV, TiFlash and TiDB Binlog components: +- For TiKV, TiFlash and, TiDB Binlog components: - 1. TiUP takes the node offline through API and directly exits without waiting for the process to be completed. - 2. To check the status of the nodes being scaled in, you need to execute the `tiup cluster display` command, and wait for the status to be changed to `Tombstone`. + 1. TiUP Cluster takes the node offline through API and directly exits without waiting for the process to be completed. + 2. To check the status of the nodes being scaled in, you need to execute the `tiup cluster display` command and wait for the status to become `Tombstone`. 3. To clean up the nodes in the `Tombstone` status, you need to execute the `tiup cluster prune` command. The `tiup cluster prune` command performs the following operations: - Stops the services of the nodes that have been taken offline. - Cleans up the data files of the nodes that have been taken offline. - - Updates the cluster topology and remove the nodes that have been taken offline. + - Updates the cluster topology and removes the nodes that have been taken offline. -- For other components: +For other components: - - When taking the PD components offline, TiUP cluster quickly deletes the specified nodes from the cluster through API, stops the service of the specified PD nodes, and then deletes the related data files from the nodes. - - When taking other components down, TiUP cluster directly stops the node services and deletes the related data files from the specified nodes. +- When taking the PD components offline, TiUP Cluster quickly deletes the specified nodes from the cluster through API, stops the service of the specified PD nodes, and then deletes the related data files from the nodes. +- When taking other components down, TiUP Cluster directly stops the node services and deletes the related data files from the specified nodes. ## Syntax @@ -35,7 +35,7 @@ tiup cluster scale-in [flags] ### -N, --node -- Specifies the nodes to scale in, splitting by commas for multiple nodes. +- Specifies the nodes to take down. Multiple nodes are separated by commas. - Data type: `STRING` - There is no default value. This option is mandatory and the value must be not null.