Deploy a TiDB Cluster Using TiUP
TiUP is a cluster operation and maintenance tool introduced in TiDB 4.0. TiUP provides TiUP cluster, a cluster management component written in Golang. By using TiUP cluster, you can easily perform daily database operations, including deploying, starting, stopping, destroying, scaling, and upgrading a TiDB cluster, and manage TiDB cluster parameters.
TiUP supports deploying TiDB, TiFlash, TiDB Binlog, TiCDC, and the monitoring system. This document introduces how to deploy TiDB clusters of different topologies.
Step 1. Prerequisites and precheck
Make sure that you have read the following documents:
Step 2. Deploy TiUP on the control machine
You can deploy TiUP on the control machine in either of the two ways: online deployment and offline deployment.
Deploy TiUP online
Log in to the control machine using a regular user account (take the tidb
user as an example). Subsequent TiUP installation and cluster management can be performed by the tidb
user.
Install TiUP by running the following command:
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | shSet TiUP environment variables:
Redeclare the global environment variables:
source .bash_profileConfirm whether TiUP is installed:
which tiup
Install the TiUP cluster component:
tiup clusterIf TiUP is already installed, update the TiUP cluster component to the latest version:
tiup update --self && tiup update clusterIf
“Update successfully!”
is displayed, the TiUP cluster is updated successfully.Verify the current version of your TiUP cluster:
tiup --binary cluster
Deploy TiUP offline
Perform the following steps in this section to deploy a TiDB cluster offline using TiUP:
Prepare the TiUP offline component package
To prepare the TiUP offline component package, you can manually pack an offline component package using tiup mirror clone
.
Install the TiUP package manager online.
Install the TiUP tool:
curl --proto '=https' --tlsv1.2 -sSf https://tiup-mirrors.pingcap.com/install.sh | shRedeclare the global environment variables:
source .bash_profileConfirm whether TiUP is installed:
which tiup
Pull the mirror using TiUP.
Pull the needed components on a machine that has access to the Internet:
tiup mirror clone tidb-community-server-${version}-linux-amd64 ${version} --os=linux --arch=amd64The command above creates a directory named
tidb-community-server-${version}-linux-amd64
in the current directory, which contains the component package necessary for starting a cluster.Pack the component package by using the
tar
command and send the package to the control machine in the isolated environment:tar czvf tidb-community-server-${version}-linux-amd64.tar.gz tidb-community-server-${version}-linux-amd64tidb-community-server-${version}-linux-amd64.tar.gz
is an independent offline environment package.
Customize the offline mirror, or adjust the contents of an existing offline mirror.
If you want to adjust an existing offline mirror (such as adding a new version of a component), take the following steps:
When pulling an offline mirror, you can get an incomplete offline mirror by specifying specific information via parameters, such as the component and version information. For example, you can pull an offline mirror that includes only the offline mirror of TiUP v1.11.0 and TiUP Cluster v1.11.0 by running the following command:
tiup mirror clone tiup-custom-mirror-v1.11.0 --tiup v1.11.0 --cluster v1.11.0If you only need the components for a particular platform, you can specify them using the
--os
or--arch
parameters.Refer to the step 2 of "Pull the mirror using TiUP", and send this incomplete offline mirror to the control machine in the isolated environment.
Check the path of the current offline mirror on the control machine in the isolated environment. If your TiUP tool is of a recent version, you can get the current mirror address by running the following command:
tiup mirror showIf the output of the above command indicates that the
show
command does not exist, you might be using an older version of TiUP. In this case, you can get the current mirror address from$HOME/.tiup/tiup.toml
. Record this mirror address. In the following steps,${base_mirror}
is used to refer to this address.Merge an incomplete offline mirror into an existing offline mirror:
First, copy the
keys
directory in the current offline mirror to the$HOME/.tiup
directory:cp -r ${base_mirror}/keys $HOME/.tiup/Then use the TiUP command to merge the incomplete offline mirror into the mirror in use:
tiup mirror merge tiup-custom-mirror-v1.11.0When the above steps are completed, check the result by running the
tiup list
command. In this document's example, the outputs of bothtiup list tiup
andtiup list cluster
show that the corresponding components ofv1.11.0
are available.
Deploy the offline TiUP component
After sending the package to the control machine of the target cluster, install the TiUP component by running the following commands:
tar xzvf tidb-community-server-${version}-linux-amd64.tar.gz && \
sh tidb-community-server-${version}-linux-amd64/local_install.sh && \
source /home/tidb/.bash_profile
The local_install.sh
script automatically runs the tiup mirror set tidb-community-server-${version}-linux-amd64
command to set the current mirror address to tidb-community-server-${version}-linux-amd64
.
To switch the mirror to another directory, run the tiup mirror set <mirror-dir>
command. To switch the mirror to the online environment, run the tiup mirror set https://tiup-mirrors.pingcap.com
command.
Step 3. Initialize cluster topology file
Run the following command to create a cluster topology file:
tiup cluster template > topology.yaml
In the following two common scenarios, you can generate recommended topology templates by running commands:
For hybrid deployment: Multiple instances are deployed on a single machine. For details, see Hybrid Deployment Topology.
tiup cluster template --full > topology.yamlFor geo-distributed deployment: TiDB clusters are deployed in geographically distributed data centers. For details, see Geo-Distributed Deployment Topology.
tiup cluster template --multi-dc > topology.yaml
Run vi topology.yaml
to see the configuration file content:
global:
user: "tidb"
ssh_port: 22
deploy_dir: "/tidb-deploy"
data_dir: "/tidb-data"
server_configs: {}
pd_servers:
- host: 10.0.1.4
- host: 10.0.1.5
- host: 10.0.1.6
tidb_servers:
- host: 10.0.1.7
- host: 10.0.1.8
- host: 10.0.1.9
tikv_servers:
- host: 10.0.1.1
- host: 10.0.1.2
- host: 10.0.1.3
monitoring_servers:
- host: 10.0.1.4
grafana_servers:
- host: 10.0.1.4
alertmanager_servers:
- host: 10.0.1.4
The following examples cover seven 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 |
---|---|---|---|
OLTP | Deploy minimal topology | Simple minimal configuration template Full minimal configuration template | This is the basic cluster topology, including tidb-server, tikv-server, and pd-server. |
HTAP | Deploy the TiFlash topology | Simple TiFlash configuration template Full TiFlash configuration template | This is to deploy TiFlash along with the minimal cluster topology. TiFlash is a columnar storage engine, and gradually becomes a standard cluster topology. |
Replicate incremental data using TiCDC | Deploy the TiCDC topology | Simple TiCDC configuration template Full TiCDC configuration template | This is to deploy TiCDC along with the minimal cluster topology. TiCDC supports multiple downstream platforms, such as TiDB, MySQL, and MQ. |
Replicate incremental data using TiDB Binlog | Deploy the TiDB Binlog topology | Simple TiDB Binlog configuration template (MySQL as downstream) Simple TiDB Binlog configuration template (Files as downstream) Full TiDB Binlog configuration template | This is to deploy TiDB Binlog along with the minimal cluster topology. |
Use OLAP on Spark | Deploy the TiSpark topology | Simple TiSpark configuration template Full TiSpark configuration template | This is to deploy TiSpark along with the minimal cluster topology. TiSpark is a component built for running Apache Spark on top of TiDB/TiKV to answer the OLAP queries. Currently, TiUP cluster's support for TiSpark is still experimental. |
Deploy multiple instances on a single machine | Deploy a hybrid topology | Simple configuration template for hybrid deployment Full configuration template for hybrid deployment | The deployment topologies also apply when you need to add extra configurations for the directory, port, resource ratio, and label. |
Deploy TiDB clusters across data centers | Deploy a geo-distributed deployment topology | Configuration template for geo-distributed deployment | This topology takes the typical architecture of three data centers in two cities as an example. It introduces the geo-distributed deployment architecture and the key configuration that requires attention. |
For more configuration description, see the following configuration examples:
Step 4. Run the deployment command
Before you run the deploy
command, use the check
and check --apply
commands to detect and automatically repair potential risks in the cluster:
Check for potential risks:
tiup cluster check ./topology.yaml --user root [-p] [-i /home/root/.ssh/gcp_rsa]Enable automatic repair:
tiup cluster check ./topology.yaml --apply --user root [-p] [-i /home/root/.ssh/gcp_rsa]Deploy a TiDB cluster:
tiup cluster deploy tidb-test v6.3.0 ./topology.yaml --user root [-p] [-i /home/root/.ssh/gcp_rsa]
In the tiup cluster deploy
command above:
tidb-test
is the name of the TiDB cluster to be deployed.v6.3.0
is the version of the TiDB cluster to be deployed. You can see the latest supported versions by runningtiup list tidb
.topology.yaml
is the initialization configuration file.--user root
indicates logging into the target machine as theroot
user to complete the cluster deployment. Theroot
user is expected to havessh
andsudo
privileges to the target machine. Alternatively, you can use other users withssh
andsudo
privileges to complete the deployment.[-i]
and[-p]
are optional. If you have configured login to the target machine without password, these parameters are not required. If not, choose one of the two parameters.[-i]
is the private key of the root user (or other users specified by--user
) that has access to the target machine.[-p]
is used to input the user password interactively.
At the end of the output log, you will see Deployed cluster `tidb-test` successfully
. This indicates that the deployment is successful.
Step 5. Check the clusters managed by TiUP
tiup cluster list
TiUP supports managing multiple TiDB clusters. The preceding command outputs information of all the clusters currently managed by TiUP, including the cluster name, deployment user, version, and secret key information:
Step 6. Check the status of the deployed TiDB cluster
For example, run the following command to check the status of the tidb-test
cluster:
tiup cluster display tidb-test
Expected output includes the instance ID, role, host, listening port, and status (because the cluster is not started yet, so the status is Down
/inactive
), and directory information.
Step 7. Start a TiDB cluster
Since TiUP cluster v1.9.0, safe start is introduced as a new start method. Starting a database using this method improves the security of the database. It is recommended that you use this method.
After safe start, TiUP automatically generates a password for the TiDB root user and returns the password in the command-line interface.
Method 1: Safe start
tiup cluster start tidb-test --init
If the output is as follows, the start is successful:
Started cluster `tidb-test` successfully.
The root password of TiDB database has been changed.
The new password is: 'y_+3Hwp=*AWz8971s6'.
Copy and record it to somewhere safe, it is only displayed once, and will not be stored.
The generated password can NOT be got again in future.
Method 2: Standard start
tiup cluster start tidb-test
If the output log includes Started cluster `tidb-test` successfully
, the start is successful. After standard start, you can log in to a database using a root user without a password.
Step 8. Verify the running status of the TiDB cluster
tiup cluster display tidb-test
If the output log shows Up
status, the cluster is running properly.
See also
If you have deployed TiFlash along with the TiDB cluster, see the following documents:
If you have deployed TiCDC along with the TiDB cluster, see the following documents: