diff --git a/check-before-deployment.md b/check-before-deployment.md index 7e6ddf5691adc..37db0decf8da7 100644 --- a/check-before-deployment.md +++ b/check-before-deployment.md @@ -106,20 +106,37 @@ Take the `/dev/nvme0n1` data disk as an example: ## Check and disable system swap -TiDB needs a sufficient amount of memory for operation. If the memory that TiDB uses gets swapped out and later gets swapped back in, this can cause latency spikes. If you want to maintain stable performance, it is recommended that you permanently disable the system swap, but it might trigger OOM issues when there is insufficient memory. If you want to avoid such OOM issues, you can just decrease the swap priority, instead of permanently disabling it. +Swapping TiDB memory out to disk and back can cause latency spikes. For stable performance, it is recommended that you permanently disable system swap. However, disabling swap can increase the risk of out-of-memory (OOM) issues when memory is insufficient. Choose one of the following options based on your memory capacity and latency requirements: -- Enabling and using swap might introduce performance jitter issues. It is recommended that you permanently disable the operating system tier swap for low-latency and stability-critical database services. To permanently disable swap, you can use the following method: +- Option 1: Disable swap for latency-sensitive workloads: - - During the initialization phase of the operating system, do not partition the swap partition disk separately. - - If you have already partitioned a separate swap partition disk during the initialization phase of the operating system and enabled swap, run the following command to disable it: + 1. When installing the operating system, do not create swap partitions or swap files. If swap is already enabled, first ensure that enough memory is available to reload the swapped-out data, then run the following command to disable swap: ```bash - echo "vm.swappiness = 0">> /etc/sysctl.conf - sysctl -p - swapoff -a && swapon -a + swapoff -a ``` -- If the host memory is insufficient, disabling the system swap might be more likely to trigger OOM issues. You can run the following command to decrease the swap priority instead of disabling it permanently: + 2. To prevent swap from being enabled at boot, remove or comment out all swap entries in `/etc/fstab`. + + On hosts that use `systemd-gpt-auto-generator`, GPT swap partitions on the same disk as the root partition can be activated automatically even without an `/etc/fstab` entry. On these hosts, list the swap unit files: + + ```bash + systemctl list-unit-files --type=swap + ``` + + For each swap unit you want to disable permanently, run the following command to prevent automatic activation. Replace `` with the actual unit name from the output, such as `dev-sda2.swap`: + + ```bash + systemctl mask + ``` + + For more information, see [systemd-gpt-auto-generator](https://www.freedesktop.org/software/systemd/man/latest/systemd-gpt-auto-generator.html) and [systemctl mask](https://www.freedesktop.org/software/systemd/man/latest/systemctl.html). + + 3. After disabling swap, and again after the next reboot, run `cat /proc/swaps`. If swap is disabled, the output contains only the header row. + +- Option 2: For hosts with limited memory, keep swap enabled and reduce the kernel's tendency to swap: + + Set `vm.swappiness=0` to reduce the kernel's tendency to swap. This setting does not disable swap: the kernel can still use it under memory pressure. Run the following commands to save the setting in `/etc/sysctl.conf` and apply it immediately: ```bash echo "vm.swappiness = 0">> /etc/sysctl.conf @@ -794,7 +811,7 @@ sudo yum -y install numactl 1. Follow [Deploy a TiDB Cluster Using TiUP](/production-deployment-using-tiup.md) to deploy a cluster `tidb-test`. If you have installed a TiDB cluster, you can skip this step. ```bash - tiup cluster deploy tidb-test v6.1.0 ./topology.yaml --user root [-p] [-i /home/root/.ssh/gcp_rsa] + tiup cluster deploy tidb-test {{{ .tidb-version }}} ./topology.yaml --user root [-p] [-i /home/root/.ssh/gcp_rsa] ``` 2. Run the `tiup cluster exec` command using the `sudo` privilege to install NUMA on all the target machines in the `tidb-test` cluster: diff --git a/post-installation-check.md b/post-installation-check.md index 8e991786dc586..3d23a6c84ceee 100644 --- a/post-installation-check.md +++ b/post-installation-check.md @@ -26,7 +26,13 @@ Expected output: If the `Status` information of each node is `Up`, the cluster r ### Use TiDB Dashboard -1. Log in to TiDB Dashboard at `${pd-ip}:${pd-port}/dashboard`. The username and password is the same as that of the TiDB `root` user. If you have modified the `root` password, enter the modified password. The password is empty by default. +1. Log in to TiDB Dashboard at `${pd-ip}:${pd-port}/dashboard` using the TiDB `root` account and its current password. + + > **Note:** + > + > If you initialized the cluster with `--init`, TiUP generates the initial root password. Otherwise, the initial password is empty. + > + > If you have changed the password, use the updated password. Restarting the cluster without `--init` does not reset an existing password. ![TiDB-Dashboard](/media/tiup/tidb-dashboard.png) @@ -48,10 +54,16 @@ Expected output: If the `Status` information of each node is `Up`, the cluster r > > Install the MySQL client before you log in to the database. -Log in to the database by running the following command: +To log in with a root password, run the following command and enter the password when prompted. If you used the recommended [safe start method](/production-deployment-using-tiup.md#step-7-start-a-tidb-cluster) (`tiup cluster start tidb-test --init`), use the password displayed in the TiUP command output, unless you have since changed it: {{< copyable "shell-regular" >}} +```shell +mysql -u root -p -h ${tidb_server_host_IP_address} -P 4000 +``` + +If the cluster was initially started without `--init` and no root password has been set, omit `-p`: + ```shell mysql -u root -h ${tidb_server_host_IP_address} -P 4000 ``` diff --git a/production-deployment-using-tiup.md b/production-deployment-using-tiup.md index e008bc48aa6d6..106fac27872db 100644 --- a/production-deployment-using-tiup.md +++ b/production-deployment-using-tiup.md @@ -250,7 +250,7 @@ alertmanager_servers: - host: 10.0.1.4 ``` -The following examples cover six common scenarios. You need to modify the configuration file (named `topology.yaml`) according to the topology description and templates in the corresponding links. For other scenarios, edit the configuration template accordingly. +The following examples cover five common scenarios. You need to modify the configuration file (named `topology.yaml`) according to the topology description and templates in the corresponding links. For other scenarios, edit the configuration template accordingly. | Application | Configuration task | Configuration file template | Topology description | | :-- | :-- | :-- | :-- |