Skip to content

Commit a25da5d

Browse files
ti-srebotti-srebot
authored
TiUP: Add three docs about tiup dm display, upgrade, and cluster check (#5291) (#5362)
1 parent 2256e0f commit a25da5d

File tree

3 files changed

+302
-0
lines changed

3 files changed

+302
-0
lines changed

‎tiup/tiup-component-cluster-check.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
---
2+
title: tiup cluster check
3+
---
4+
5+
# tiup cluster check
6+
7+
For a formal production environment, before the environment goes live, you need to perform a series of checks to ensure the clusters are in their best performance. To simplify the manual check steps, TiUP Cluster provides the `check` command to check whether the hardware and software environments of the target machines of a specified cluster meet the requirements to work normally.
8+
9+
## List of check items
10+
11+
### Operating system version
12+
13+
Check the operating system distribution and version of the deployed machines. Currently, only CentOS 7 is supported for deployment. More system versions may be supported in later releases for compatibility improvement.
14+
15+
### CPU EPOLLEXCLUSIVE
16+
17+
Check whether the CPU of the target machine supports EPOLLEXCLUSIVE.
18+
19+
### numactl
20+
21+
Check whether numactl is installed on the target machine. If tied cores are configured on the target machine, you must install numactl.
22+
23+
### System time
24+
25+
Check whether the system time of the target machine is synchronized. Compare the system time of the target machine with that of the central control machine, and report an error if the deviation exceeds a certain threshold (500ms).
26+
27+
### Time synchronization service
28+
29+
Check whether the time synchronization service is configured on the target machine. Namely, check whether ntpd is running.
30+
31+
### Swap partitioning
32+
33+
Check whether swap partitioning is enabled on the target machine. It is recommended to disable swap partitioning.
34+
35+
### Kernel parameters
36+
37+
Check the values of the following kernel parameters:
38+
39+
- `net.ipv4.tcp_tw_recycle`: 0
40+
- `net.ipv4.tcp_syncookies`: 0
41+
- `net.core.somaxconn`: 32768
42+
- `vm.swappiness`: 0
43+
- `vm.overcommit_memory`: 0 or 1
44+
- `fs.file-max`: 1000000
45+
46+
### Transparent Huge Pages (THP)
47+
48+
Check whether THP is enabled on the target machine. It is recommended to disable THP.
49+
50+
### System limits
51+
52+
Check the limit values in the `/etc/security/limits.conf` file:
53+
54+
```
55+
<deploy-user> soft nofile 1000000
56+
<deploy-user> hard nofile 1000000
57+
<deploy-user> soft stack 10240
58+
```
59+
60+
`<deploy-user>` is the user who deploys and runs the TiDB cluster, and the last column is the minimum value required for the system.
61+
62+
### SELinux
63+
64+
Check whether SELinux is enabled. It is recommended to disable SELinux.
65+
66+
### Firewall
67+
68+
Check whether the FirewallD service is enabled. It is recommended to either disable the FirewallD service or add permission rules for each service in the TiDB cluster.
69+
70+
### irqbalance
71+
72+
Check whether the irqbalance service is enabled. It is recommended to enable the irqbalance service.
73+
74+
### Disk mount options
75+
76+
Check the mount options for ext4 partitions. Make sure the mount options include the nodelalloc option and the noatime option.
77+
78+
### Port usage
79+
80+
Check if the ports defined in the topology (including the auto-completion default ports) are already used by the processes on the target machine.
81+
82+
> **Note:**
83+
>
84+
> The port usage check assumes that a cluster is not started yet. If a cluster is already deployed and started, the port usage check on the cluster fails because the ports must be in use in this case.
85+
86+
### CPU core number
87+
88+
Check the CPU information of the target machine. For a production cluster, it is recommended that the number of the CPU logical core is greater than or equal to 16.
89+
90+
> **Note:**
91+
>
92+
> CPU core number is not checked by default. To enable the check, you need to add the `-enable-cpu` option to the command.
93+
94+
### Memory size
95+
96+
Check the memory size of the target machine. For a production cluster, it is recommended that the total memory capacity is greater than or equal to 32GB.
97+
98+
> **Note:**
99+
>
100+
> Memory size is not checked by default. To enable the check, you need to add the `-enable-mem` option to the command.
101+
102+
### Fio disk performance test
103+
104+
Use flexible I/O tester (fio) to test the performance of the disk where `data_dir` is located, including the following three test items:
105+
106+
- fio_randread_write_latency
107+
- fio_randread_write
108+
- fio_randread
109+
110+
> **Note:**
111+
>
112+
> The fio disk performance test is not performed by default. To perform the test, you need to add the `-enable-disk` option to the command.
113+
114+
## Syntax
115+
116+
```shell
117+
tiup cluster check <topology.yml | cluster-name> [flags]
118+
```
119+
120+
- If a cluster is not deployed yet, you need to pass the topology.yml <!--[topology.yml](/tiup/tiup-cluster-topology-reference.md)--> file that is used to deploy the cluster. According to the content in this file, tiup-cluster connects to the corresponding machine to perform the check.
121+
- If a cluster is already deployed, you can use the `<cluster-name>` as the check object.
122+
123+
> **Note:**
124+
>
125+
> If `<cluster-name>` is used for the check, you need to add the `--cluster` option in the command.
126+
127+
## Options
128+
129+
### --apply
130+
131+
- Attempts to automatically repair the failed check items. Currently, tiup-cluster only attempts to repair the following check items:
132+
- SELinux
133+
- firewall
134+
- irqbalance
135+
- kernel parameters
136+
- System limits
137+
- THP (Transparent Huge Pages)
138+
- Data type: `BOOLEAN`
139+
- 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.
140+
141+
### --cluster
142+
143+
- Indicates that the check is for the deployed clusters.
144+
- Data type: `BOOLEAN`
145+
- 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.
146+
147+
> **Note:**
148+
>
149+
> tiup-cluster supports checking both un-deployed clusters and deployed clusters with the following command format:
150+
>
151+
> ```shell
152+
> tiup cluster check <topology.yml | cluster-name> [flags]
153+
> ```
154+
>
155+
> If the `tiup cluster check <cluster-name>` command is used, you must add the `--cluster` option: `tiup cluster check <cluster-name> --cluster`.
156+
157+
### --enable-cpu
158+
159+
- Enables the check of CPU core number.
160+
- Data type: `BOOLEAN`
161+
- 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.
162+
163+
### --enable-disk
164+
165+
- Enables the fio disk performance test.
166+
- Data type: `BOOLEAN`
167+
- 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.
168+
169+
### --enable-mem
170+
171+
- Enables the memory size check.
172+
- Data type: `BOOLEAN`
173+
- 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.
174+
175+
### --u, --user
176+
177+
- Specifies the user name to connect to the target machine. The specified user needs to have the password-free sudo root privileges on the target machine.
178+
- Data type: `STRING`
179+
- If this option is not specified in the command, the user who executes the command is used as the default value.
180+
181+
> **Note:**
182+
>
183+
> This option is valid only if the `-cluster` option is false. Otherwise, the value of this option is fixed to the username specified in the topology file for the cluster deployment.
184+
185+
### -i, --identity_file
186+
187+
- Specifies the key file to connect to the target machine.
188+
- Data type: `STRING`
189+
- The option is enabled by default with `~/.ssh/id_rsa` (the default value) passed in.
190+
191+
> **Note:**
192+
>
193+
> This option is valid only if the `--cluster` option is false. Otherwise, the value of this option is fixed to `${TIUP_HOME}/storage/cluster/clusters/<cluster-name>/ssh/id_rsa`.
194+
195+
### -p, --password
196+
197+
- Logs in with a password when connecting to the target machine.
198+
- If the `--cluster` option is added for a cluster, the password is the password of the user specified in the topology file when the cluster was deployed.
199+
- If the `--cluster` option is not added for a cluster, the password is the password of the user specified in the `-u/--user` option.
200+
- Data type: `BOOLEAN`
201+
- 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.
202+
203+
### -h, --help
204+
205+
- Prints the help information of the related commands.
206+
- Data type: `BOOLEAN`
207+
- 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.
208+
209+
## Output
210+
211+
A table containing the following fields:
212+
213+
- `Node`: the target node
214+
- `Check`: the check item
215+
- `Result`: the check result (Pass, Warn, or Fail)
216+
- `Message`: the result description

‎tiup/tiup-component-dm-display.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: tiup dm display
3+
---
4+
5+
# tiup dm display
6+
7+
If you want to check the operational status of each component in a DM cluster, it is inefficient to log in to each machine one by one. Therefore, tiup-dm provides the `tiup dm display` command to do this job efficiently.
8+
9+
## Syntax
10+
11+
```shell
12+
tiup dm display <cluster-name> [flags]
13+
```
14+
15+
`<cluster-name>` is the name of the cluster to be operated. If you forget the cluster name, you can use the `[tiup dm list](/tiup/tiup-component-dm-list.md)` command to check it.
16+
17+
## Options
18+
19+
### -N, --node
20+
21+
- Specifies the IDs of the nodes to query, splitting by commas for multiple nodes. If you are not sure about the ID of a node, you can skip this option in the command to show the IDs and status of all nodes in the output.
22+
- Data type: `STRING`
23+
- This option is enabled by default with `[]` (which means all nodes) passed in.
24+
25+
> **Note:**
26+
>
27+
> If `-R, --role` is also specified, only the services in the intersection of the specified nodes and roles is queried.
28+
29+
### -R, --role
30+
31+
- Specifies the roles to query, splitting by commas for multiple roles. If you are not sure about the role deployed on a node, you can skip this option in the command to show the roles and status of all nodes in the output.
32+
- Data type: `STRING`
33+
- This option is enabled by default with `[]` (which means all roles) passed in.
34+
35+
> **Note:**
36+
>
37+
> If `-N, --node` is also specified, only the services in the intersection of the specified nodes and roles is queried.
38+
39+
### -h, --help
40+
41+
- Prints the help information.
42+
- Data type: `BOOLEAN`
43+
- 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.
44+
45+
## Output
46+
47+
- Cluster name
48+
- Cluster version
49+
- SSH client type
50+
- A table containing the following fields:
51+
- `ID`: the node ID, consisting of IP:PORT.
52+
- `Role`: the service role deployed on the node (for example, TiDB or TiKV).
53+
- `Host`: the IP address of the machine corresponding to the node.
54+
- `Ports`: the port number used by the service.
55+
- `OS/Arch`: the operating system and machine architecture of the node.
56+
- `Status`: the current status of the services on the node.
57+
- `Data Dir`: the data directory of the service. `-` means that there is no data directory.
58+
- `Deploy Dir`: the deployment directory of the service.

‎tiup/tiup-component-dm-upgrade.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: tiup dm upgrade
3+
---
4+
5+
# tiup dm upgrade
6+
7+
The `tiup dm upgrade` command is used to upgrade a specified cluster to a specific version.
8+
9+
## Syntax
10+
11+
```shell
12+
tiup dm upgrade <cluster-name> <version> [flags]
13+
```
14+
15+
- `<cluster-name>` is the name of the cluster to be operated on. If you forget the cluster name, you can use the `[tiup dm list](/tiup/tiup-component-dm-list.md)` command to check it.
16+
- `<version>` is the target version to be upgraded to. Currently, only upgrading to a later version is allowed, and upgrading to an earlier version is not allowed, which means the downgrade is not allowed. Upgrading to a nightly version is not allowed either.
17+
18+
## Options
19+
20+
### -h, --help
21+
22+
- Prints the help information.
23+
- Data type: `BOOLEAN`
24+
- 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.
25+
26+
## Output
27+
28+
Log of the service upgrade process.

0 commit comments

Comments
 (0)