Skip to content

tiup: optimize the structure and content of the deployment doc (#2326) #2362

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lilin90 merged 1 commit into from
Apr 21, 2020
Merged

tiup: optimize the structure and content of the deployment doc (#2326) #2362

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 52 additions & 46 deletions how-to/deploy/orchestrated/tiup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,27 @@ category: how-to

This document introduces how to use TiUP to deploy a TiDB cluster. The steps are as follows:

1. [Prepare the deployment environment](#1-prepare-the-deployment-environment)
2. [Configure the initialization parameter file `topology.yaml`](#2-configure-the-initialization-parameter-file-topologyyaml)
3. [Execute the deployment command](#3-execute-the-deployment-command)
4. [Verify the deployment status of the cluster](#4-verify-the-deployment-status-of-the-cluster)
5. [Start the cluster](#5-start-the-cluster)
6. [Verify the running status of the cluster](#6-verify-the-running-status-of-the-cluster)
- [Step 1: Prepare the right machines for deployment](#step-1-prepare-the-right-machines-for-deployment)
- [Step 2: Install TiUP on the Control Machine](#step-2-install-tiup-on-the-control-machine)
- [Step 3: Mount the data disk ext4 filesystem with options on the target machines that deploy TiKV](#step-3-mount-the-data-disk-ext4-filesystem-with-options-on-the-target-machines-that-deploy-tikv)
- [Step 4: Edit the initialization configuration file `topology.yaml`](#step-4-edit-the-initialization-configuration-file-topologyyaml)
- [Step 5: Execute the deployment command](#step-5-execute-the-deployment-command)
- [Step 6: Check the clusters managed by TiUP](#step-6-check-the-clusters-managed-by-tiup)
- [Step 7: Check the status of the deployed TiDB cluster](#step-7-check-the-status-of-the-deployed-tidb-cluster)
- [Step 8: Start the TiDB cluster](#step-8-start-the-tidb-cluster)
- [Step 9: Check the TiDB cluster status using TiUP](#step-9-check-the-tidb-cluster-status-using-tiup)
- [Step 10: Check the TiDB cluster status through TiDB Dashboard and Grafana](#step-10-check-the-tidb-cluster-status-through-tidb-dashboard-and-grafana)
- [Step 11: Log in to the TiDB database to execute simple SQL statements](#step-11-log-in-to-the-tidb-database-to-execute-simple-sql-statements)

This document also provides commands to stop and destroy a TiDB cluster using TiUP, as well as FAQs of the TiUP deployment method. See the following sections for details:

- [Stop a TiDB cluster using TiUP](#stop-a-tidb-cluster-using-tiup)
- [Destroy a TiDB cluster using TiUP](#destroy-a-tidb-cluster-using-tiup)
- [TiUP Deployment FAQs](#tiup-deployment-faqs)

## 1. Prepare the deployment environment
## Prepare the deployment environment

Here are the steps of preparing your deployment environment:

- [Step 1: Prepare the right machines for deployment](#step-1-prepare-the-right-machines-for-deployment)
- [Step 2: Install TiUP on the Control Machine](#step-2-install-tiup-on-the-control-machine)
- [Step 3: Mount the data disk ext4 filesystem with options on the target machines that deploy TiKV](#step-3-mount-the-data-disk-ext4-filesystem-with-options-on-the-target-machines-that-deploy-tikv)
Here are the steps of preparing your deployment environment.

### Step 1: Prepare the right machines for deployment

Expand Down Expand Up @@ -280,17 +281,17 @@ Take the `/dev/nvme0n1` data disk as an example:

If the filesystem is ext4 and `nodelalloc` is included in the mount options, you have successfully mount the data disk ext4 filesystem with options on the target machines.

## 2. Configure the initialization parameter file `topology.yaml`
## Step 4: Edit the initialization configuration file `topology.yaml`

You need to manually write the cluster initialization configuration file. For the full configuration parameter template, refer to [Github TiUP Project](https://github.com/pingcap-incubator/tiops/blob/master/topology.example.yaml).
You need to manually create and edit the cluster initialization configuration file. For the full configuration template, refer to [Github TiUP Project](https://github.com/pingcap-incubator/tiops/blob/master/topology.example.yaml).

You need to create a YAML configuration file on the Control Machine, such as `topology.yaml`.

The following sections provide a cluster configuration template for each of the following common scenarios:

- [Scenario 1: Single machine with single instance](#scenario-1-single-machine-with-single-instance)
- [Scenario 2: Single machine with multiple instances](#scenario-2-single-machine-with-multiple-instances)
- [Scenario 3: Use TiDB Binlog deployment template](#scenario-3-use-tidb-binlog-deployment-template)
- [Scenario 3: Replicate to the downstream using TiDB Binlog](#scenario-3-replicate-to-the-downstream-using-tidb-binlog)

### Scenario 1: Single machine with single instance

Expand All @@ -310,7 +311,7 @@ The following sections provide a cluster configuration template for each of the
| PD | 3 |4 Vcore 8GB * 1 |10.0.1.4 <br> 10.0.1.5 <br> 10.0.1.6 | Default port configuration; <br> Global directory configuration |
| TiFlash | 1 | 32 VCore 64 GB * 1 | 10.0.1.10 | Default port configuration; <br> Global directory configuration |

#### Step 4: Edit the configuration file template topology.yaml
#### Edit the configuration file template topology.yaml

> **Note:**
>
Expand Down Expand Up @@ -597,7 +598,7 @@ You need to fill in the result in the configuration file (as described in the St
| PD | 3 | 16 Vcore 32 GB | 10.0.1.4<br> 10.0.1.5<br> 10.0.1.6 | Configure `location_lables` parameter |
| TiFlash | 1 | 32 VCore 64 GB | 10.0.1.10 | Default port; <br> Customized deployment directory - the `data_dir` parameter is set to `/data1/tiflash/data` |

#### Step 4: Edit the configuration file template topology.yaml
#### Edit the configuration file template topology.yaml

> **Note:**
>
Expand Down Expand Up @@ -754,7 +755,7 @@ alertmanager_servers:
- host: 10.0.1.7
```

### Scenario 3: Use TiDB Binlog deployment template
### Scenario 3: Replicate to the downstream using TiDB Binlog

#### Deployment requirements

Expand Down Expand Up @@ -785,7 +786,7 @@ Key parameters of TiDB:
| Pump|8 Vcore 16GB * 3|10.0.1.6<br>10.0.1.7<br>10.0.1.8 | Default port configuration; <br> The GC time is set to 7 days |
| Drainer | 8 Vcore 16GB | 10.0.1.9 | Default port configuration; <br>Set default initialization commitTS |

#### Step 4: Edit the configuration file template topology.yaml
#### Edit the configuration file template topology.yaml

> **Note:**
>
Expand Down Expand Up @@ -891,7 +892,7 @@ alertmanager_servers:
- host: 10.0.1.4
```

## 3. Execute the deployment command
## Execute the deployment command

### Deployment command introduction

Expand Down Expand Up @@ -942,7 +943,7 @@ In the above command:

At the end of the output log, you will see ```Deployed cluster `tidb-test` successfully```. This indicates that the deployment is successful.

## 4. Verify the deployment status of the cluster
## Verify the deployment status of the cluster

### Verification command introduction

Expand All @@ -964,7 +965,7 @@ Flags:
# Usage shows the execution command, which shows the list of all the managed TiDB clusters.
```

### Step 6: Check the cluster managed by TiUP
### Step 6: Check the clusters managed by TiUP

{{< copyable "shell-regular" >}}

Expand All @@ -981,7 +982,9 @@ Name User Version Path
tidb-test tidb v4.0.0-rc /home/tidb/.tiup/storage/cluster/clusters/tidb-test /home/tidb/.tiup/storage/cluster/clusters/tidb-test/ssh/id_rsa
```

### Step 7: Check the status of `tidb-test`
### Step 7: Check the status of the deployed TiDB cluster

For example, execute the following command to check the status of the `tidb-test` cluster:

{{< copyable "shell-regular" >}}

Expand Down Expand Up @@ -1012,9 +1015,7 @@ ID Role Host Ports
10.0.1.3:20160 tikv 10.0.1.4 20160/20180 Down /tidb-data/tikv-20160 /tidb-deploy/tikv-2060
```

## 5. Start the cluster

### Step 8: Start the `tidb-test` cluster
## Step 8: Start the TiDB cluster

{{< copyable "shell-regular" >}}

Expand All @@ -1024,9 +1025,9 @@ tiup cluster start tidb-test

If the output log includes ```Started cluster `tidb-test` successfully```, it means that the startup is successful.

## 6. Verify the running status of the cluster
## Verify the running status of the TiDB cluster

### Step 9: Check the `tidb-test` cluster status using TiUP
### Step 9: Check the TiDB cluster status using TiUP

{{< copyable "shell-regular" >}}

Expand Down Expand Up @@ -1057,7 +1058,7 @@ ID Role Host Ports Status
10.0.1.3:2060 tikv 10.0.1.4 2060/20080 Up /tidb-data/tikv-2060 /tidb-deploy/tikv-2060
```

### Step 10: Check TiDB cluster status through TiDB Dashboard and Grafana
### Step 10: Check the TiDB cluster status through TiDB Dashboard and Grafana

#### Check TiDB cluster status through TiDB Dashboard

Expand All @@ -1079,7 +1080,7 @@ Click Overview monitoring page to check TiDB port and load information:

![Grafana-overview](/media/tiup/grafana-overview.png)

### Step 11: Log in to the database to execute simple SQL statements
### Step 11: Log in to the TiDB database to execute simple SQL statements

> **Note:**
>
Expand Down Expand Up @@ -1350,25 +1351,30 @@ Available versions for tidb (Last Modified: 2020-02-26T15:20:35+08:00):
Version Installed Release: Platforms
------- --------- -------- ---------
master 2020-03-18T08:39:11.753360611+08:00 linux/amd64,darwin/amd64
v3.0.1 2020-04-07T17:53:00+08:00 linux/amd64,darwin/amd64
v3.0.2 2020-04-08T23:38:37+08:00 linux/amd64,darwin/amd64
v3.0.3 2020-03-27T22:41:16.279411145+08:00 linux/amd64,darwin/amd64
v3.0.4 2020-03-27T22:43:35.362550386+08:00 linux/amd64,darwin/amd64
v3.0.5 2020-03-27T22:46:01.016467032+08:00 linux/amd64,darwin/amd64
v3.0.6 2020-03-13T11:55:17.941641963+08:00 linux/amd64,darwin/amd64
v3.0.7 2020-03-13T12:02:22.538128662+08:00 linux/amd64,darwin/amd64
v3.0.8 2020-03-17T14:03:29.575448277+08:00 linux/amd64,darwin/amd64
v3.0.9 2020-03-13T13:02:15.947260351+08:00 linux/amd64,darwin/amd64
v3.0.0 2020-04-16T14:03:31+08:00 linux/amd64,darwin/amd64
v3.0 2020-04-16T16:58:06+08:00 linux/amd64,darwin/amd64
v3.0.1 2020-04-17T18:33:22+08:00 linux/amd64,darwin/amd64
v3.0.2 2020-04-16T23:55:11+08:00 linux/amd64,darwin/amd64
v3.0.3 2020-04-17T00:16:31+08:00 linux/amd64,darwin/amd64
v3.0.4 2020-04-17T00:22:46+08:00 linux/amd64,darwin/amd64
v3.0.5 2020-04-17T00:29:45+08:00 linux/amd64,darwin/amd64
v3.0.6 2020-04-17T00:39:33+08:00 linux/amd64,darwin/amd64
v3.0.7 2020-04-17T00:46:32+08:00 linux/amd64,darwin/amd64
v3.0.8 2020-04-17T00:54:19+08:00 linux/amd64,darwin/amd64
v3.0.9 2020-04-17T01:00:58+08:00 linux/amd64,darwin/amd64
v3.0.10 2020-03-13T14:11:53.774527401+08:00 linux/amd64,darwin/amd64
v3.0.11 2020-03-13T15:31:06.94547891+08:00 linux/amd64,darwin/amd64
v3.0.12 2020-03-20T11:36:28.18950808+08:00 linux/amd64,darwin/amd64
v3.0.11 2020-04-17T01:09:20+08:00 linux/amd64,darwin/amd64
v3.0.12 2020-04-17T01:16:04+08:00 linux/amd64,darwin/amd64
v3.1.0-beta 2020-04-13T16:07:51+08:00 linux/amd64,darwin/amd64
v3.1.0-beta.1 2020-04-13T15:45:38+08:00 linux/amd64,darwin/amd64
v3.1.0-beta.2 2020-03-19T00:48:48.266468238+08:00 linux/amd64,darwin/amd64
v3.1.0-rc 2020-04-02T23:43:17.456327834+08:00 linux/amd64,darwin/amd64
v3.1.0 2020-04-17T11:07:54+08:00 linux/amd64,darwin/amd64
v4.0.0-beta 2020-03-13T12:43:55.508190493+08:00 linux/amd64,darwin/amd64
v4.0.0-beta.1 2020-03-13T12:30:08.913759828+08:00 linux/amd64,darwin/amd64
v4.0.0-beta.2 2020-03-18T22:52:00.830626492+08:00 linux/amd64,darwin/amd64
v4.0.0-rc YES 2020-04-09T00:10:32+08:00 linux/amd64,darwin/amd64
nightly 2020-04-10T08:42:23+08:00 darwin/amd64,linux/amd64
v4.0.0-rc YES 2020-04-17T01:22:03+08:00 linux/amd64,darwin/amd64
nightly 2020-04-18T08:54:10+08:00 darwin/amd64,linux/amd64
```

### How to view the TiDB components supported by TiUP
Expand All @@ -1390,9 +1396,9 @@ In the following output:
Available components (Last Modified: 2020-02-27T15:20:35+08:00):
Name Installed Platforms Description
---- --------- --------- -----------
tidb YES(v4.0.0-rc) darwin/amd64,linux/amd64 TiDB is an open source distributed HTAP database compatible with the MySQL protocol
tikv YES(v4.0.0-rc) darwin/amd64,linux/amd64 Distributed transactional key-value database, originally created to complement TiDB
pd YES(v4.0.0-rc) darwin/amd64,linux/amd64 PD is the abbreviation for Placement Driver. It is used to manage and schedule the TiKV cluster
tidb YES(v4.0.0-rc) darwin/amd64,linux/amd64 TiDB is an open source distributed HTAP database compatible with the MySQL protocol
tikv YES(v4.0.0-rc) darwin/amd64,linux/amd64 Distributed transactional key-value database, originally created to complement TiDB
pd YES(v4.0.0-rc) darwin/amd64,linux/amd64 PD is the abbreviation for Placement Driver. It is used to manage and schedule the TiKV cluster
playground YES(v0.0.5) darwin/amd64,linux/amd64 Bootstrap a local TiDB cluster
client darwin/amd64,linux/amd64 A simple mysql client to connect TiDB
prometheus darwin/amd64,linux/amd64 The Prometheus monitoring system and time series database.
Expand Down