From b00262e89465367ddbd0caf46229bba1528220d1 Mon Sep 17 00:00:00 2001 From: yikeke Date: Sun, 28 Jun 2020 13:07:46 +0800 Subject: [PATCH 01/11] create and rename file; update TOC and docs guide --- TOC.md | 6 ++- tiup/tiup-cluster.md | 4 ++ ...ponent.md => tiup-component-management.md} | 0 tiup/tiup-documentation-guide.md | 25 ++++++++++ tiup/tiup-faq.md | 50 +++++++++++++++++++ tiup/{tiup-mirrors.md => tiup-mirror.md} | 0 tiup/tiup-terminology-and-concepts.md | 0 tiup/tiup-troubleshooting-guide.md | 0 8 files changed, 84 insertions(+), 1 deletion(-) rename tiup/{manage-tiup-component.md => tiup-component-management.md} (100%) create mode 100644 tiup/tiup-documentation-guide.md create mode 100644 tiup/tiup-faq.md rename tiup/{tiup-mirrors.md => tiup-mirror.md} (100%) create mode 100644 tiup/tiup-terminology-and-concepts.md create mode 100644 tiup/tiup-troubleshooting-guide.md diff --git a/TOC.md b/TOC.md index 2917937ac066c..4958dfb7aab43 100644 --- a/TOC.md +++ b/TOC.md @@ -407,8 +407,12 @@ + [Use TiFlash](/tiflash/use-tiflash.md) + [FAQ](/tiflash/tiflash-faq.md) + TiUP + + [Documentation Guide](/tiup/tiup-documentation-guide.md) + [Overview](/tiup/tiup-overview.md) - + [Manage TiUP Components](/tiup/manage-tiup-component.md) + + [Terminology and Concepts](/tiup/tiup-terminology-and-concepts.md) + + [Manage TiUP Components](/tiup/tiup-component-management.md) + + [FAQ](/tiup/tiup-faq.md) + + [Troubleshooting Guide](/tiup/tiup-troubleshooting-guide.md) + TiUP Components + [tiup-playground](/tiup/tiup-playground.md) + [tiup-cluster](/tiup/tiup-cluster.md) diff --git a/tiup/tiup-cluster.md b/tiup/tiup-cluster.md index eff3b531d18fd..f8e89699d7cac 100644 --- a/tiup/tiup-cluster.md +++ b/tiup/tiup-cluster.md @@ -65,6 +65,10 @@ This command requires you to provide the cluster name, the TiDB cluster version, To write a topology file, refer to [the example](https://github.com/pingcap-incubator/tiup-cluster/blob/master/examples/topology.example.yaml). The following file is an example of the simplest topology: +> **Note:** +> +> The deployment and scale topology file used by the TiUP cluster component is written using [yaml](https://yaml.org/spec/1.2/spec.html) syntax, so make sure that the indentation is correct. + ```yaml --- diff --git a/tiup/manage-tiup-component.md b/tiup/tiup-component-management.md similarity index 100% rename from tiup/manage-tiup-component.md rename to tiup/tiup-component-management.md diff --git a/tiup/tiup-documentation-guide.md b/tiup/tiup-documentation-guide.md new file mode 100644 index 0000000000000..7ae6809495663 --- /dev/null +++ b/tiup/tiup-documentation-guide.md @@ -0,0 +1,25 @@ +--- +title: TiUP Documentation Guide +category: tools +--- + +# TiUP Documentation Guide + +## TiUP user guide + +- [TiUP Overview](/tiup/tiup-overview.md): Give an overall introduction to TiUP, for example, how to install and use TiUP +- [TiUP Terminology and Concepts](/tiup/tiup-terminology-and-concepts.md): Explain the terms that you might bump into when using TiUP, and help you understand the key concepts of TiUP +- [TiUP Component Management](/tiup/tiup-component-management.md): Introduce all TiUP commands in detail, and how to use TiUP to download, update and delete components +- [TiUP FAQ](/tiup/tiup-faq.md): Introduce common issues when you use TiUP, including FAQs of the third-party components of TiUP +- [TiUP Troubleshooting Guide](/tiup/tiup-troubleshooting-guide.md): Introduce the troubleshooting methods and solutions if you encounter issues when using TiUP + +## TiUP component user guide + +- [tiup-playground](/tiup/tiup-playground.md): Introduce how to use the TiUP playground component to quickly build a local TiDB cluster for testing +- [tiup-cluster](/tiup/tiup-cluster.md): Introduce the usage and command-line flags of the TiUP cluster component, which is used to deploy and maintain a TiDB cluster for production +- [tiup-mirror](/tiup/tiup-mirror.md): Introduce how to use the TiUP mirror component to customize a local offline mirror +- [tiup-bench](/tiup/tiup-bench.md): Introduce how to use the TiUP bench component for common stress testings, such as TPCC/TPCH + +## TiUP resources + +- [TiUP Issues](https://github.com/pingcap/tiup/issues): TiUP Github issue list \ No newline at end of file diff --git a/tiup/tiup-faq.md b/tiup/tiup-faq.md new file mode 100644 index 0000000000000..a75b97575d8df --- /dev/null +++ b/tiup/tiup-faq.md @@ -0,0 +1,50 @@ +--- +title: TiUP FAQ +category: tools +--- + +# TiUP FAQ + +## TiUP 是否可以不使用官方镜像源？ + +TiUP 支持通过环境变量 TIUP_MIRRORS 指定镜像源，镜像源的地址可以是一个本地目录或 HTTP 服务器地址。如果用户的环境不能访问网络，可以建立自己的离线镜像源使用 TiUP。 + +## 如何将自己编写的组件放入 TiUP 镜像仓库？ + +TiUP 暂时不支持外部开发的组件，但是 TiUP Team 已经制定了 TiUP 组件开发规范，同时正在开发 tiup-publish 组件，完成 tiup-publish 组件后，开发者可以通过 `tiup publish ` 将自己开发的组件发布到 TiUP 的官方镜像仓库。 + +## tiup-playground 和 tiup-cluster 有什么区别？ + +TiUP Playground 组件主要定位是快速上手和搭建单机的开发环境，支持 Linux/MacOS，要运行一个指定版本的 TiUP 集群更加简单。TiUP Cluster 组件主要是部署生成环境集群，通常是一个大规模的集群，还包含运维相关操作。 + +## 怎么样编写 tiup-cluster 组件的拓扑文件？ + +可以参考拓扑文件的 [样例](https://github.com/pingcap/tiup/tree/master/examples)，样例中包含了： + +1. 两地三中心 +2. 最小部署拓扑 +3. 完整拓扑文件 + +可以根据自己的需求选择不同的模板，进行编辑。 + +## 同一个主机是否可以部署多个实例？ + +同一个主机可以使用 TiUP Cluster 部署多个实例，但是需要配置不同的端口和目录信息，否则可能导致目录以及端口冲突。 + +## 是否可以检测同一个集群内的端口和目录冲突？ + +同一个集群的端口和目录冲突会在部署和扩容的时候进行检测，如果有目录和端口冲突，本次部署或扩容会中断。 + +## 是否可以检测不同集群的端口和目录冲突？ + +如果不同集群是由同一个 TiUP 中控机部署的，会在部署和扩容时进行检测，如果属于不同的 TiUP 中控机，目前不支持检测。 + +## 集群部署期间，TiUP 收到报错 `ssh: handshake failed: read tcp 10.10.10.34:38980 -> 10.10.10.34:3600: read: connection reset by peer` + +该报错可能是因为 TiUP 默认并发超过 ssh 默认最大连接数导致，可尝试加大 ssh 默认连接数，然后重启 sshd 服务解决： + +``` +vi /etc/ssh/sshd_config +MaxSessions 1000 +MaxStartups 1000 +``` diff --git a/tiup/tiup-mirrors.md b/tiup/tiup-mirror.md similarity index 100% rename from tiup/tiup-mirrors.md rename to tiup/tiup-mirror.md diff --git a/tiup/tiup-terminology-and-concepts.md b/tiup/tiup-terminology-and-concepts.md new file mode 100644 index 0000000000000..e69de29bb2d1d diff --git a/tiup/tiup-troubleshooting-guide.md b/tiup/tiup-troubleshooting-guide.md new file mode 100644 index 0000000000000..e69de29bb2d1d From 1ce13ebf4c55b35ab0c71e09aa7a8e5cbde91442 Mon Sep 17 00:00:00 2001 From: yikeke Date: Sun, 28 Jun 2020 16:34:18 +0800 Subject: [PATCH 02/11] align the rest of https://github.com/pingcap/docs-cn/pull/3197/ --- tiup/tiup-faq.md | 47 ++++++++++++---------- tiup/tiup-overview.md | 7 ---- tiup/tiup-terminology-and-concepts.md | 34 ++++++++++++++++ tiup/tiup-troubleshooting-guide.md | 56 +++++++++++++++++++++++++++ 4 files changed, 116 insertions(+), 28 deletions(-) diff --git a/tiup/tiup-faq.md b/tiup/tiup-faq.md index a75b97575d8df..1a3be923c9798 100644 --- a/tiup/tiup-faq.md +++ b/tiup/tiup-faq.md @@ -5,46 +5,51 @@ category: tools # TiUP FAQ -## TiUP 是否可以不使用官方镜像源？ +## Can TiUP not use the official mirror source? -TiUP 支持通过环境变量 TIUP_MIRRORS 指定镜像源，镜像源的地址可以是一个本地目录或 HTTP 服务器地址。如果用户的环境不能访问网络，可以建立自己的离线镜像源使用 TiUP。 +TiUP supports specifying the mirror source through the `TIUP_MIRRORS` environment variable. The address of the mirror source can be a local directory or an HTTP server address. If your environment cannot access the network, you can create your own offline mirror source to use TiUP. -## 如何将自己编写的组件放入 TiUP 镜像仓库？ +## How do I put my own component into the TiUP mirrors? -TiUP 暂时不支持外部开发的组件，但是 TiUP Team 已经制定了 TiUP 组件开发规范，同时正在开发 tiup-publish 组件，完成 tiup-publish 组件后，开发者可以通过 `tiup publish ` 将自己开发的组件发布到 TiUP 的官方镜像仓库。 +TiUP does not support third-party components for the time being, but the TiUP Team has developed the TiUP component development specifications and is developing the tiup-publish component. After everything is ready, a contributor can publish their own components to TiUP's official mirrors by using the `tiup publish ` command. -## tiup-playground 和 tiup-cluster 有什么区别？ +## What is the difference between tiup-playground and tiup-cluster? -TiUP Playground 组件主要定位是快速上手和搭建单机的开发环境，支持 Linux/MacOS，要运行一个指定版本的 TiUP 集群更加简单。TiUP Cluster 组件主要是部署生成环境集群，通常是一个大规模的集群，还包含运维相关操作。 +The TiUP playground component is mainly used to build a stand-alone development environment on Linux or Mac operating systems. It helps you get started quickly and run a specified version of the TiUP cluster easily. The TiUP cluster component is mainly used to deploy and maintain a production environment cluster, which is usually a large-scale cluster. -## 怎么样编写 tiup-cluster 组件的拓扑文件？ +## How do I write the topology file for the tiup-cluster component? -可以参考拓扑文件的 [样例](https://github.com/pingcap/tiup/tree/master/examples)，样例中包含了： +Refer to [these templates](https://github.com/pingcap/tiup/tree/master/examples) to write the topology file. The templates includes: -1. 两地三中心 -2. 最小部署拓扑 -3. 完整拓扑文件 +1. Multi-DC deployment topology +2. Minimal deployment topology +3. Complete topology file -可以根据自己的需求选择不同的模板，进行编辑。 +You can edit your topology file based on the templates and your needs. -## 同一个主机是否可以部署多个实例？ +## Can multiple instances be deployed on the same host? -同一个主机可以使用 TiUP Cluster 部署多个实例，但是需要配置不同的端口和目录信息，否则可能导致目录以及端口冲突。 +You can use the TiUP cluster component to deploy multiple instances on the same host, but with different ports and directories configured, otherwise directory and port conflicts might occur. -## 是否可以检测同一个集群内的端口和目录冲突？ +## Are port and directory conflicts detected within the same cluster? -同一个集群的端口和目录冲突会在部署和扩容的时候进行检测，如果有目录和端口冲突，本次部署或扩容会中断。 +Port and directory conflicts in the same cluster are detected during deployment and scaling. If there are any directory or port conflict, the deployment or scaling process is interrupted. -## 是否可以检测不同集群的端口和目录冲突？ +## Are port and directory conflicts detected among different clusters? -如果不同集群是由同一个 TiUP 中控机部署的，会在部署和扩容时进行检测，如果属于不同的 TiUP 中控机，目前不支持检测。 +If multiple different clusters are deployed by the same TiUP control machine, the port and directory conflicts among these clusters are detected during deployment and scaling. If the clusters are deployed by different TiUP control machines, conflict detection is not supported currently. -## 集群部署期间，TiUP 收到报错 `ssh: handshake failed: read tcp 10.10.10.34:38980 -> 10.10.10.34:3600: read: connection reset by peer` +## During cluster deployment, TiUP received an `ssh: handshake failed: read tcp 10.10.10.34:38980 -> 10.10.10.34:3600: read: connection reset by peer` error -该报错可能是因为 TiUP 默认并发超过 ssh 默认最大连接数导致，可尝试加大 ssh 默认连接数，然后重启 sshd 服务解决： +The error might occur because the default number of concurrent threads of TiUP exceeds the default maximum number of SSH connections. To solve the issue, you can increase the default number of SSH connections, and then restart the sshd service: -``` +{{< copyable "shell-regular" >}} + +```shell vi /etc/ssh/sshd_config +``` + +```bash MaxSessions 1000 MaxStartups 1000 ``` diff --git a/tiup/tiup-overview.md b/tiup/tiup-overview.md index 0f7187fdb5d09..2f38d2e532c52 100644 --- a/tiup/tiup-overview.md +++ b/tiup/tiup-overview.md @@ -125,10 +125,3 @@ The output is long but you can focus on only two parts: TiUP commands are implemented in TiUP's internal code and used for package management operations, while TiUP components are independent component packages installed by TiUP commands. For example, if you run the `tiup list` command, TiUP directly runs its own internal code; if you run the `tiup playground` command, TiUP first checks whether there is a local package named "playground", and if not, TiUP downloads the package from the mirror, and then run it. - -All TiUP commands are described in [Manage TiUP Components with TiUP Commands](/tiup/manage-tiup-component.md). All TiUP components are divided into the following topics by component: - -- [Quickly Deploy a Local TiDB Cluster](/tiup/tiup-playground.md): introduce the playground component -- [Deploy and Maintain an Online TiDB Cluster](/tiup/tiup-cluster.md): introduce the cluster component -- [Create a Private Mirror](/tiup/tiup-mirrors.md): introduce the mirrors component -- [Stress Test TiDB Using TiUP](/tiup/tiup-bench.md): introduce the bench component diff --git a/tiup/tiup-terminology-and-concepts.md b/tiup/tiup-terminology-and-concepts.md index e69de29bb2d1d..31e7179c1d3ca 100644 --- a/tiup/tiup-terminology-and-concepts.md +++ b/tiup/tiup-terminology-and-concepts.md @@ -0,0 +1,34 @@ +--- +title: TiUP Terminology and Concepts +category: tools +--- + +# TiUP Terminology and Concepts + +This document explains important terms and concepts of TiUP. + +## TiUP components + +The TiUP program contains only a few commands for downloading, updating, and uninstalling components. TiUP expands its functions with various components. A **component** is a program or script that can be run. When running a component through `tiup `, TiUP adds a set of environment variables, creates the data directory for the program, and then runs the program. + +By running the `tiup ` command, you can run a component supported by TiUP. The running logic is: + +1. If you specify a version of a component through `tiup [:version]`: + + - If the component does not have any version installed locally, TiUP downloads the latest stable version from the mirror server. + - If the component has one or more versions installed locally, but there is no version specified by you, TiUP downloads the version from the mirror server. + - If the specified version of the component is installed locally, TiUP sets the environment variable to run the installed version. + +2. If you run a component through `tiup ` and specify no version: + + - If the component does not have any version installed locally, TiUP downloads the latest stable version from the mirror server. + - If one or more versions have been installed locally, TiUP sets the environment variable to run the latest installed version. + +## TiUP mirrors + +All components of TiUP are downloaded from the TiUP mirrors. TiUP mirrors contain the TAR package of each component and the corresponding meta information (version, entry startup file, checksum). TiUP uses PingCAP's official mirrors by default. You can customize the mirror source through the `TIUP_MIRRORS` environment variable. + +TiUP mirrors can be a local file directory or an online HTTP server: + +1. `TIUP_MIRRORS=/path/to/local tiup list` +2. `TIUP_MIRRORS=https://private-mirrors.example.com tiup list` diff --git a/tiup/tiup-troubleshooting-guide.md b/tiup/tiup-troubleshooting-guide.md index e69de29bb2d1d..6f1eefbbdede9 100644 --- a/tiup/tiup-troubleshooting-guide.md +++ b/tiup/tiup-troubleshooting-guide.md @@ -0,0 +1,56 @@ +--- +title: TiUP Troubleshooting Guide +category: tools +--- + +# TiUP Troubleshooting Guide + +This document introduces some common issues when you use TiUP and the troubleshooting methods. If this document does not include the issues you bump into, [file a new issue](https://github.com/pingcap/tiup/issues) in the Github TiUP repository. + +## Troubleshoot TiUP commands + +### Can't see the latest component list using `tiup list` + +TiUP does not update the latest component list from the mirror server every time. You can force refresh the component list by running `tiup list`. + +### Can't see the latest version information of a component using `tiup list ` + +Same as the previous issue, the component version information is only obtained from the mirror server when there is no local cache. You can refresh the component list by running `tiup list `. + +### Component downloading process is interrupted + +Unstable network might result in an interrupted component downloading process. You can try to download again. If you cannot download it after trying multiple times, it might be caused by the CDN server and you can report the issue [here](https://github.com/pingcap/tiup/issues). + +### A checksum error occurs during component downloading process + +Because the CDN server has a short cache time, the new checksum file might not match the component package. Try to download again after 5 minutes. If it still does not match, report the issue [here](https://github.com/pingcap/tiup/issues). + +## Troubleshoot TiUP cluster component + +### Prompt `unable to authenticate, attempted methods [none publickey]` during deployment + +During deployment, component packages are uploaded to the remote host and the initialization is performed. This process requires connecting to the remote host. This error is caused by the failure to find the SSH private key to connect to the remote host. + +To solve this issue, confirm whether you specify the private key by running `tiup cluster deploy -i identity_file`: + +1. If the `-i` flag is not specified, it might be that TiUP does not automatically find the private key path. It is recommended to explicitly specify the private key path using `-i`. +2. If the `-i` flag is specified, it might be that TiUP cannot log in to the remote host using the specified private key. You can verify it by manually executing the `ssh -i identity_file user@remote` command. +3. If a password is used to log in to the remote host, make sure that you have specified the `-p` parameter and entered the correct login password. + +### The process of upgrading the cluster using the TiUP cluster component is interrupted + +To avoid misuse cases, the TiUP cluster component does not support the upgrade of specified nodes, so after the upgrade fails, you need to perform the upgrade operations again, including idempotent operations during the upgrade process. + +The upgrade process can be divided into the following steps: + +1. Back up the old version of components on all nodes +2. Distribute new components to remote +3. Rolling restart all components + +If the upgrade is interrupted during a rolling restart, instead of repeating the `tiup cluster upgrade` operation, you can use `tiup cluster restart -N -N ` to restart the nodes that have not completed the restart. + +If the number of un-restarted nodes of the same component is relatively large, you can also restart a certain type of component by running `tiup cluster restart -R `. + +### During the upgrade, you find that `node_exporter-9100.service/blackbox_exporter-9115.service` does not exist + +If you previously migrated your cluster from TiDB Ansible and the exporter was not deployed before in TiDB Ansible, this situation might happen. To solve it, you can manually copy the missing files from other nodes to the new node for the time being. The TiUP team will complete the missing components during the migration process. From 0d24f21cca0efba2f0965391d35f16e8162c945e Mon Sep 17 00:00:00 2001 From: yikeke Date: Sun, 28 Jun 2020 16:38:12 +0800 Subject: [PATCH 03/11] Update TOC.md --- TOC.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/TOC.md b/TOC.md index 4958dfb7aab43..ae4c1ff25eb08 100644 --- a/TOC.md +++ b/TOC.md @@ -416,7 +416,7 @@ + TiUP Components + [tiup-playground](/tiup/tiup-playground.md) + [tiup-cluster](/tiup/tiup-cluster.md) - + [tiup-mirror](/tiup/tiup-mirrors.md) + + [tiup-mirror](/tiup/tiup-mirror.md) + [tiup-bench](/tiup/tiup-bench.md) + [Errors Codes](/error-codes.md) + [TiCDC Overview](/ticdc/ticdc-overview.md) From ac34b826803d78b3cd19dc6c8f16b4ba31df0fe6 Mon Sep 17 00:00:00 2001 From: yikeke Date: Sun, 28 Jun 2020 17:09:02 +0800 Subject: [PATCH 04/11] add an alias --- tiup/tiup-component-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tiup/tiup-component-management.md b/tiup/tiup-component-management.md index eb880a912e542..2585f4dff877f 100644 --- a/tiup/tiup-component-management.md +++ b/tiup/tiup-component-management.md @@ -2,7 +2,7 @@ title: Manage TiUP Components with TiUP Commands summary: Learn how to manage TiUP components using TiUP commands. category: tools -aliases: ['/docs/dev/tiup/manage-tiup-component/','/docs/dev/reference/tools/tiup/manage-component/'] +aliases: ['/tidb/dev/manage-tiup-component/','/docs/dev/tiup/manage-tiup-component/','/docs/dev/reference/tools/tiup/manage-component/'] --- # Manage TiUP Components with TiUP Commands From 35cc2faee2e23c7d0922f601981df833bbcd186d Mon Sep 17 00:00:00 2001 From: yikeke Date: Sun, 28 Jun 2020 17:20:51 +0800 Subject: [PATCH 05/11] align https://github.com/pingcap/docs-cn/pull/3417/files --- tiup/tiup-component-management.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tiup/tiup-component-management.md b/tiup/tiup-component-management.md index 2585f4dff877f..c6b05d0d84c27 100644 --- a/tiup/tiup-component-management.md +++ b/tiup/tiup-component-management.md @@ -26,10 +26,11 @@ You can use the `tiup list` command to query the component list. This usage of t - `tiup list`: checks which components can be installed. - `tiup list ${component}`: checks which versions of a specific component can be installed. -You can also use the following two flags in the above commands: +You can also use the following flags in the above commands: - `--installed`: checks which components or which version of a specific component has been installed locally. -- `--refresh`: gets the latest list of components on the server and the version list of each component. +-`--all`: View all components, including the hidden ones +-`--verbose`: View all columns (including installed versions and supported platforms) Example 1: View all currently installed components. From bebb1eded39e6f773d22cb2392271c0accc09da9 Mon Sep 17 00:00:00 2001 From: yikeke Date: Sun, 28 Jun 2020 17:50:18 +0800 Subject: [PATCH 06/11] align https://github.com/pingcap/docs-cn/pull/3463 and https://github.com/pingcap/docs-cn/pull/3425 --- overview.md | 2 +- production-offline-deployment-using-tiup.md | 2 +- tiup/tiup-cluster.md | 2 +- tiup/tiup-mirror.md | 165 +++++--------------- tiup/tiup-overview.md | 15 +- 5 files changed, 45 insertions(+), 141 deletions(-) diff --git a/overview.md b/overview.md index 147535ad0aea0..5338753fb51a0 100644 --- a/overview.md +++ b/overview.md @@ -11,7 +11,7 @@ aliases: ['/docs/dev/overview/'] TiDB can be deployed on-premise or in-cloud. The following deployment options are officially supported by PingCAP: -- [TiUP Deployment](/production-deployment-using-tiup.md): This guide describes how to deploy TiDB using [TiUP](https://github.com/pingcap-incubator/tiup). It is strongly recommended for production deployment. +- [TiUP Deployment](/production-deployment-using-tiup.md): This guide describes how to deploy TiDB using [TiUP](https://github.com/pingcap/tiup). It is strongly recommended for production deployment. - [Docker Deployment](/test-deployment-using-docker.md): This guide describes how to deploy TiDB using Docker. - [Docker Compose Deployment](/deploy-test-cluster-using-docker-compose.md): This guide describes how to deploy TiDB using Docker compose. You can follow this guide to quickly deploy a TiDB cluster for testing and development on your local drive. - Kubernetes Deployment: diff --git a/production-offline-deployment-using-tiup.md b/production-offline-deployment-using-tiup.md index 3b85ed9421d05..b6b11c8edcd0c 100644 --- a/production-offline-deployment-using-tiup.md +++ b/production-offline-deployment-using-tiup.md @@ -15,7 +15,7 @@ You can either download the official package, or manually pack a component packa ### Download the official TiUP offline component package -Download the prepared offline mirror package at by running the following command: +Download the prepared offline mirror package at `http://download.pingcap.org` by running the following command: {{< copyable "shell-regular" >}} diff --git a/tiup/tiup-cluster.md b/tiup/tiup-cluster.md index f8e89699d7cac..532f79198db41 100644 --- a/tiup/tiup-cluster.md +++ b/tiup/tiup-cluster.md @@ -63,7 +63,7 @@ tiup cluster deploy [flags] This command requires you to provide the cluster name, the TiDB cluster version, and a topology file of the cluster. -To write a topology file, refer to [the example](https://github.com/pingcap-incubator/tiup-cluster/blob/master/examples/topology.example.yaml). The following file is an example of the simplest topology: +To write a topology file, refer to [the example](https://github.com/pingcap/tiup/blob/master/examples/topology.example.yaml). The following file is an example of the simplest topology: > **Note:** > diff --git a/tiup/tiup-mirror.md b/tiup/tiup-mirror.md index 17025124a3429..7e12d23f1cbda 100644 --- a/tiup/tiup-mirror.md +++ b/tiup/tiup-mirror.md @@ -7,73 +7,56 @@ aliases: ['/docs/dev/tiup/tiup-mirrors/','/docs/dev/reference/tools/tiup/mirrors # Create a Private Mirror -When creating a private cloud, usually, you need to use an isolated network environment, where the official mirror of TiUP is not accessible. Therefore, you can create a private mirror, which is mainly implemented by the `mirrors` component. You can also use `mirrors` for offline deployment. +When creating a private cloud, usually, you need to use an isolated network environment, where the official mirror of TiUP is not accessible. Therefore, you can create a private mirror, which is mainly implemented by the `mirror` command. You can also use the `mirror` command for offline deployment. -## TiUP `mirrors` overview +## TiUP `mirror` overview -Execute the following command to get the help information of the `mirrors` component: +Execute the following command to get the help information of the `mirror` command: {{< copyable "shell-regular" >}} ```bash -tiup mirrors --help +tiup mirror --help ``` -``` -Starting component `mirrors`: /Users/joshua/.tiup/components/mirrors/v0.0.1/mirrors -Build a local mirrors and download all selected components +```bash +The 'mirror' command is used to manage a component repository for TiUP, you can use +it to create a private repository, or to add new component to an existing repository. +The repository can be used either online or offline. +It also provides some useful utilities to help managing keys, users and versions +of components or the repository itself. Usage: - tiup mirrors [global-version] [flags] -Examples: - tiup mirrors local-path --arch amd64,arm --os linux,darwin # Specify the architectures and OSs - tiup mirrors local-path --full # Build a full local mirrors - tiup mirrors local-path --tikv v4 # Specify the version via prefix - tiup mirrors local-path --tidb all --pd all # Download all version for specific component + tiup mirror [flags] +Available Commands: + init Initialize an empty repository + sign Add signatures to a manifest file + genkey Generate a new key pair + clone Clone a local mirror from remote mirror and download all selected components + publish Publish a component Flags: - --overwrite Overwrite the exists tarball - -f, --full Build a full mirrors repository - -a, --arch strings Specify the downloading architecture (default [amd64]) - -o, --os strings Specify the downloading os (default [linux,darwin]) - --tidb strings Specify the versions for component tidb - --tikv strings Specify the versions for component tikv - --pd strings Specify the versions for component pd - --playground strings Specify the versions for component playground - --client strings Specify the versions for component client - --prometheus strings Specify the versions for component prometheus - --package strings Specify the versions for component package - --grafana strings Specify the versions for component grafana - --alertmanager strings Specify the versions for component alertmanager - --blackbox_exporter strings Specify the versions for component blackbox_exporter - --node_exporter strings Specify the versions for component node_exporter - --pushgateway strings Specify the versions for component pushgateway - --tiflash strings Specify the versions for component tiflash - --drainer strings Specify the versions for component drainer - --pump strings Specify the versions for component pump - --cluster strings Specify the versions for component cluster - --mirrors strings Specify the versions for component mirrors - --bench strings Specify the versions for component bench - --insight strings Specify the versions for component insight - --doc strings Specify the versions for component doc - --ctl strings Specify the versions for component ctl - -h, --help help for tiup + -h, --help help for mirror + --repo string Path to the repository +Global Flags: + --skip-version-check Skip the strict version check, by default a version must be a valid SemVer string +Use "tiup mirror [command] --help" for more information about a command. ``` -The basic usage of the `tiup mirrors` command is as follows: +The `tiup mirror clone` command is used to build a local mirror. The basic usage is as follows: {{< copyable "shell-regular" >}} ```bash -tiup mirrors [global-version] [flags] +tiup mirror clone [global-version] [flags] ``` - `target-dir`: used to specify the directory in which cloned data is stored. - `global-version`: used to quickly set a global version for all components. -The `tiup mirrors` command provides many optional flags (might provide more in the future). These flags can be divided into the following categories according to their intended usages: +The `tiup mirror clone` command provides many optional flags (might provide more in the future). These flags can be divided into the following categories according to their intended usages: -- Determines whether to overwrite local packages +- Determines whether to use prefix matching to match the version when cloning - The `--overwrite` flag determines whether to overwrite the local package with the package of the official mirror, if the specified `` directory contains the package you need to download. If you set this flag, the local package is overwritten. + If the `--prefix` flag is specified, the version number is matched by prefix for the clone. For example, if you specify `--prefix` as "v4.0.0", then "v4.0.0-rc.1", "v4.0.0-rc.2", and "v4.0.0" are matched. - Determines whether to use the full clone @@ -81,102 +64,28 @@ The `tiup mirrors` command provides many optional flags (might provide more in t > **Note:** > - > If `--full` and the other flags are not specified, only some meta information is cloned. + > If `--full`, `global-version` flags, and the component versions are not specified, only some meta information is cloned. - Determines whether to clone packages from the specific platform If you want to clone packages only for a specific platform, use `-os` and `-arch` to specify the platform. For example: - - Execute the `tiup mirros --os=linux` command to clone for linux. - - Execute the `tiup mirros --arch=amd64` command to clone for amd64. - - Execute the `tiup mirros --os=linux --arch=amd64` command to clone for linux/amd64. + - Execute the `tiup mirror clone [global-version] --os=linux` command to clone for linux. + - Execute the `tiup mirror clone [global-version] --arch=amd64` command to clone for amd64. + - Execute the `tiup mirror clone [global-version] --os=linux --arch=amd64` command to clone for linux/amd64. - Determines whether to clone a specific version of a package If you want to clone only one version (not all versions) of a component, use `--=` to specify this version. For example: - - Execute the `tiup mirrors --tidb v4` command to clone the v4 version of the TiDB component. - - Execute the `tiup mirros --tidb v4 --tikv all` command to clone the v4 version of the TiDB component and all versions of the TiKV component. - - Execute the `tiup mirrors v4.0.0-rc` command to clone the v4.0.0-rc version of all components in a cluster. + - Execute the `tiup mirror clone --tidb v4.0.0` command to clone the v4.0.0 version of the TiDB component. + - Execute the `tiup mirror clone --tidb v4.0.0 --tikv all` command to clone the v4.0.0 version of the TiDB component and all versions of the TiKV component. + - Execute the `tiup mirror clone v4.0.0` command to clone the v4.0.0 version of all components in a cluster. ## Usage examples -This section introduces the usage examples of `mirrors`, including offline installation of a TiDB cluster, and the creation of a private mirror. - -### Install a TiDB cluster offline using TiUP - -If you want to install a TiDB cluster of the v4.0.0-rc version in an isolated environment, take the following steps: - -1. Pull the required components on a machine connected to the external network: - - {{< copyable "shell-regular" >}} - - ```bash - tiup mirrors package --os=linux v4.0.0-rc - ``` - - Then a `package` directory is created in the current directory. This `package` directory contains necessary components packages to start a cluster. - -2. Use the `tar` command to pack the components package and send this package to the control machine that is in the isolated environment: - - {{< copyable "shell-regular" >}} - - ```bash - tar czvf package.tar.gz package - ``` - - Then `package.tar.gz` is an isolated, offline environment. - -3. After sending the package to the control machine of the target cluster, execute the following command to install TiUP: - - {{< copyable "shell-regular" >}} - - ```bash - tar xzvf package.tar.gz - cd package - sh local_install.sh - ``` - -4. Follow the instructions to finish the installation of TiUP, and then deploy the TiDB cluster: - - {{< copyable "shell-regular" >}} - - ```bash - export TIUP_MIRRORS=/path/to/mirror - tiup cluster deploy - tiup cluster start - ``` +This section introduces the usage examples of the `mirror` command. - `/path/to/mirror` refers to where `` (in `tiup mirrors `) is. If `/tmp/package` refers to where `` is, execute the following command instead: - - {{< copyable "shell-regular" >}} - - ```bash - export TIUP_MIRRORS=/tmp/package - ``` - -After you complete the deployment, refer to [Deploy and Maintain an Online TiDB Cluster Using TiUP](/tiup/tiup-cluster.md) for more details of the cluster operations. - -### Create a private mirror - -The process of creating a private mirror is similar to that of creating an offline installer. The only difference is that, to create a private mirror, you need to upload the content of the `package` directory to CDN or a file server. Execute the following command to create a private mirror: - -{{< copyable "shell-regular" >}} - -```bash -cd package -python -m SimpleHTTPServer 8000 -``` - -Now you have created a private mirror at . - -Then execute the following command to install TiUP using the private mirror: - -{{< copyable "shell-regular" >}} - -```bash -export TIUP_MIRRORS=http://127.0.0.1:8000 -curl $TIUP_MIRRORS/install.sh | sh -``` +### Deploy a TiDB Cluster Offline Using TiUP -After importing the `PATH` variable, you can start to use TiUP. Make sure that the `TIUP_MIRRORS` variable points to the private mirror. +Refer to [Deploy a TiDB Cluster Offline Using TiUP](/production-offline-deployment-using-tiup.md#manually-pack-an-offline-component-package-using-tiup-mirror-clone) to install the TiUP offline mirror, deploy a TiDB cluster, and start it. diff --git a/tiup/tiup-overview.md b/tiup/tiup-overview.md index 2f38d2e532c52..3178ce923e0b8 100644 --- a/tiup/tiup-overview.md +++ b/tiup/tiup-overview.md @@ -61,16 +61,11 @@ Available Commands: update Update tiup components to the latest version status List the status of instantiated components clean Clean the data of instantiated components + mirror Manage a repository mirror for TiUP components help Help about any command or component -Available Components: - playground Bootstrap a local TiDB cluster - client A simple mysql client to connect TiDB - package A toolbox to package tiup component - cluster Deploy a TiDB cluster for production - mirrors Build a local mirrors and download all selected components - bench Benchmark database with different workloads - doc Online document for TiDB +Components Manifest: + use "tiup list" to fetch the latest components manifest Flags: -B, --binary [:version] Print binary path of a specific version of a component [:version] @@ -79,7 +74,7 @@ Flags: -h, --help help for tiup --skip-version-check Skip the strict version check, by default a version must be a valid SemVer string -T, --tag string Specify a tag for component instance - --version version for tiup + -v, --version version for tiup Component instances with the same "tag" will share a data directory ($TIUP_HOME/data/$tag): $ tiup --tag mycluster playground @@ -108,11 +103,11 @@ The output is long but you can focus on only two parts: - update: used to update the component version - status: used to view the running history of components - clean: used to clear the running log of components + - mirror: used to clone a private mirror from the official mirror - help: used to print out help information - Available components - playground: used to start a TiDB cluster locally - client: used to connect to a TiDB cluster in a local machine - - mirrors: used to clone a private mirror from an official mirror - cluster: used to deploy a TiDB cluster for production environments - bench: used to stress test the database - doc: used to open online document From a2efceb024815130ce55aac8d15b3511e3145f9d Mon Sep 17 00:00:00 2001 From: yikeke Date: Sun, 28 Jun 2020 18:02:51 +0800 Subject: [PATCH 07/11] update aliases --- tiup/tiup-component-management.md | 2 +- tiup/tiup-mirror.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tiup/tiup-component-management.md b/tiup/tiup-component-management.md index c6b05d0d84c27..7b649a06619d8 100644 --- a/tiup/tiup-component-management.md +++ b/tiup/tiup-component-management.md @@ -2,7 +2,7 @@ title: Manage TiUP Components with TiUP Commands summary: Learn how to manage TiUP components using TiUP commands. category: tools -aliases: ['/tidb/dev/manage-tiup-component/','/docs/dev/tiup/manage-tiup-component/','/docs/dev/reference/tools/tiup/manage-component/'] +aliases: ['/tidb/dev/manage-tiup-component','/docs/dev/tiup/manage-tiup-component/','/docs/dev/reference/tools/tiup/manage-component/'] --- # Manage TiUP Components with TiUP Commands diff --git a/tiup/tiup-mirror.md b/tiup/tiup-mirror.md index 7e12d23f1cbda..273dfeb7b0997 100644 --- a/tiup/tiup-mirror.md +++ b/tiup/tiup-mirror.md @@ -2,7 +2,7 @@ title: Create a Private Mirror summary: Learn how to create a private mirror. category: tools -aliases: ['/docs/dev/tiup/tiup-mirrors/','/docs/dev/reference/tools/tiup/mirrors/'] +aliases: ['/tidb/dev/tiup-mirrors','/docs/dev/tiup/tiup-mirrors/','/docs/dev/reference/tools/tiup/mirrors/'] --- # Create a Private Mirror From 703e919181268ac358745aaf6604ac10f4e8240f Mon Sep 17 00:00:00 2001 From: Keke Yi <40977455+yikeke@users.noreply.github.com> Date: Wed, 1 Jul 2020 10:34:53 +0800 Subject: [PATCH 08/11] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- tiup/tiup-cluster.md | 2 +- tiup/tiup-component-management.md | 2 +- tiup/tiup-faq.md | 10 +++++----- tiup/tiup-mirror.md | 2 +- tiup/tiup-terminology-and-concepts.md | 10 +++++----- tiup/tiup-troubleshooting-guide.md | 16 ++++++++-------- 6 files changed, 21 insertions(+), 21 deletions(-) diff --git a/tiup/tiup-cluster.md b/tiup/tiup-cluster.md index 532f79198db41..ae6f61a38f994 100644 --- a/tiup/tiup-cluster.md +++ b/tiup/tiup-cluster.md @@ -67,7 +67,7 @@ To write a topology file, refer to [the example](https://github.com/pingcap/tiup > **Note:** > -> The deployment and scale topology file used by the TiUP cluster component is written using [yaml](https://yaml.org/spec/1.2/spec.html) syntax, so make sure that the indentation is correct. +> The topology file used by the TiUP cluster component for deployment and scaling is written using [yaml](https://yaml.org/spec/1.2/spec.html) syntax, so make sure that the indentation is correct. ```yaml --- diff --git a/tiup/tiup-component-management.md b/tiup/tiup-component-management.md index 7b649a06619d8..5505f823a0cfa 100644 --- a/tiup/tiup-component-management.md +++ b/tiup/tiup-component-management.md @@ -29,7 +29,7 @@ You can use the `tiup list` command to query the component list. This usage of t You can also use the following flags in the above commands: - `--installed`: checks which components or which version of a specific component has been installed locally. --`--all`: View all components, including the hidden ones +-`--all`: views all components, including the hidden ones -`--verbose`: View all columns (including installed versions and supported platforms) Example 1: View all currently installed components. diff --git a/tiup/tiup-faq.md b/tiup/tiup-faq.md index 1a3be923c9798..149e238bfb359 100644 --- a/tiup/tiup-faq.md +++ b/tiup/tiup-faq.md @@ -15,11 +15,11 @@ TiUP does not support third-party components for the time being, but the TiUP Te ## What is the difference between tiup-playground and tiup-cluster? -The TiUP playground component is mainly used to build a stand-alone development environment on Linux or Mac operating systems. It helps you get started quickly and run a specified version of the TiUP cluster easily. The TiUP cluster component is mainly used to deploy and maintain a production environment cluster, which is usually a large-scale cluster. +The TiUP playground component is mainly used to build a stand-alone development environment on Linux or macOS operating systems. It helps you get started quickly and run a specified version of the TiUP cluster easily. The TiUP cluster component is mainly used to deploy and maintain a production environment cluster, which is usually a large-scale cluster. -## How do I write the topology file for the tiup-cluster component? +## How do I write the topology file for the TiUP cluster component? -Refer to [these templates](https://github.com/pingcap/tiup/tree/master/examples) to write the topology file. The templates includes: +Refer to [these templates](https://github.com/pingcap/tiup/tree/master/examples) to write the topology file. The templates include: 1. Multi-DC deployment topology 2. Minimal deployment topology @@ -29,11 +29,11 @@ You can edit your topology file based on the templates and your needs. ## Can multiple instances be deployed on the same host? -You can use the TiUP cluster component to deploy multiple instances on the same host, but with different ports and directories configured, otherwise directory and port conflicts might occur. +You can use the TiUP cluster component to deploy multiple instances on the same host, but with different ports and directories configured; otherwise, directory and port conflicts might occur. ## Are port and directory conflicts detected within the same cluster? -Port and directory conflicts in the same cluster are detected during deployment and scaling. If there are any directory or port conflict, the deployment or scaling process is interrupted. +Port and directory conflicts in the same cluster are detected during deployment and scaling. If there is any directory or port conflict, the deployment or scaling process is interrupted. ## Are port and directory conflicts detected among different clusters? diff --git a/tiup/tiup-mirror.md b/tiup/tiup-mirror.md index 273dfeb7b0997..119c0bf33de5c 100644 --- a/tiup/tiup-mirror.md +++ b/tiup/tiup-mirror.md @@ -86,6 +86,6 @@ The `tiup mirror clone` command provides many optional flags (might provide more This section introduces the usage examples of the `mirror` command. -### Deploy a TiDB Cluster Offline Using TiUP +### Deploy a TiDB Cluster offline using TiUP Refer to [Deploy a TiDB Cluster Offline Using TiUP](/production-offline-deployment-using-tiup.md#manually-pack-an-offline-component-package-using-tiup-mirror-clone) to install the TiUP offline mirror, deploy a TiDB cluster, and start it. diff --git a/tiup/tiup-terminology-and-concepts.md b/tiup/tiup-terminology-and-concepts.md index 31e7179c1d3ca..620e73f817c88 100644 --- a/tiup/tiup-terminology-and-concepts.md +++ b/tiup/tiup-terminology-and-concepts.md @@ -13,13 +13,13 @@ The TiUP program contains only a few commands for downloading, updating, and uni By running the `tiup ` command, you can run a component supported by TiUP. The running logic is: -1. If you specify a version of a component through `tiup [:version]`: ++ If you specify a version of a component through `tiup [:version]`: - If the component does not have any version installed locally, TiUP downloads the latest stable version from the mirror server. - - If the component has one or more versions installed locally, but there is no version specified by you, TiUP downloads the version from the mirror server. + - If the component has one or more versions installed locally, but there is no version specified by you, TiUP downloads the specified version from the mirror server. - If the specified version of the component is installed locally, TiUP sets the environment variable to run the installed version. -2. If you run a component through `tiup ` and specify no version: ++ If you run a component through `tiup ` and specify no version: - If the component does not have any version installed locally, TiUP downloads the latest stable version from the mirror server. - If one or more versions have been installed locally, TiUP sets the environment variable to run the latest installed version. @@ -30,5 +30,5 @@ All components of TiUP are downloaded from the TiUP mirrors. TiUP mirrors contai TiUP mirrors can be a local file directory or an online HTTP server: -1. `TIUP_MIRRORS=/path/to/local tiup list` -2. `TIUP_MIRRORS=https://private-mirrors.example.com tiup list` ++ `TIUP_MIRRORS=/path/to/local tiup list` ++ `TIUP_MIRRORS=https://private-mirrors.example.com tiup list` diff --git a/tiup/tiup-troubleshooting-guide.md b/tiup/tiup-troubleshooting-guide.md index 6f1eefbbdede9..4cf372930a9b8 100644 --- a/tiup/tiup-troubleshooting-guide.md +++ b/tiup/tiup-troubleshooting-guide.md @@ -11,7 +11,7 @@ This document introduces some common issues when you use TiUP and the troublesho ### Can't see the latest component list using `tiup list` -TiUP does not update the latest component list from the mirror server every time. You can force refresh the component list by running `tiup list`. +TiUP does not update the latest component list from the mirror server every time. You can forcibly refresh the component list by running `tiup list`. ### Can't see the latest version information of a component using `tiup list ` @@ -19,23 +19,23 @@ Same as the previous issue, the component version information is only obtained f ### Component downloading process is interrupted -Unstable network might result in an interrupted component downloading process. You can try to download again. If you cannot download it after trying multiple times, it might be caused by the CDN server and you can report the issue [here](https://github.com/pingcap/tiup/issues). +Unstable network might result in an interrupted component downloading process. You can try to download the component again. If you cannot download it after trying multiple times, it might be caused by the CDN server and you can report the issue [here](https://github.com/pingcap/tiup/issues). ### A checksum error occurs during component downloading process -Because the CDN server has a short cache time, the new checksum file might not match the component package. Try to download again after 5 minutes. If it still does not match, report the issue [here](https://github.com/pingcap/tiup/issues). +Because the CDN server has a short cache time, the new checksum file might not match the component package. Try to download again after 5 minutes. If the new checksum file still does not match the component package, report the issue [here](https://github.com/pingcap/tiup/issues). ## Troubleshoot TiUP cluster component -### Prompt `unable to authenticate, attempted methods [none publickey]` during deployment +### `unable to authenticate, attempted methods [none publickey]` is prompted during deployment During deployment, component packages are uploaded to the remote host and the initialization is performed. This process requires connecting to the remote host. This error is caused by the failure to find the SSH private key to connect to the remote host. -To solve this issue, confirm whether you specify the private key by running `tiup cluster deploy -i identity_file`: +To solve this issue, confirm whether you have specified the private key by running `tiup cluster deploy -i identity_file`: 1. If the `-i` flag is not specified, it might be that TiUP does not automatically find the private key path. It is recommended to explicitly specify the private key path using `-i`. 2. If the `-i` flag is specified, it might be that TiUP cannot log in to the remote host using the specified private key. You can verify it by manually executing the `ssh -i identity_file user@remote` command. -3. If a password is used to log in to the remote host, make sure that you have specified the `-p` parameter and entered the correct login password. +3. If a password is used to log in to the remote host, make sure that you have specified the `-p` flag and entered the correct login password. ### The process of upgrading the cluster using the TiUP cluster component is interrupted @@ -45,7 +45,7 @@ The upgrade process can be divided into the following steps: 1. Back up the old version of components on all nodes 2. Distribute new components to remote -3. Rolling restart all components +3. Perform a rolling restart to all components If the upgrade is interrupted during a rolling restart, instead of repeating the `tiup cluster upgrade` operation, you can use `tiup cluster restart -N -N ` to restart the nodes that have not completed the restart. @@ -53,4 +53,4 @@ If the number of un-restarted nodes of the same component is relatively large, y ### During the upgrade, you find that `node_exporter-9100.service/blackbox_exporter-9115.service` does not exist -If you previously migrated your cluster from TiDB Ansible and the exporter was not deployed before in TiDB Ansible, this situation might happen. To solve it, you can manually copy the missing files from other nodes to the new node for the time being. The TiUP team will complete the missing components during the migration process. +If you previously migrated your cluster from TiDB Ansible and the exporter was not deployed in TiDB Ansible, this situation might happen. To solve it, you can manually copy the missing files from other nodes to the new node for the time being. The TiUP team will complete the missing components during the migration process. From 60caddf008aae2b309025484b93cddc78e33ca18 Mon Sep 17 00:00:00 2001 From: yikeke Date: Wed, 1 Jul 2020 14:54:46 +0800 Subject: [PATCH 09/11] add summary and update format --- tiup/tiup-documentation-guide.md | 21 +++++++++++---------- tiup/tiup-faq.md | 7 ++++--- tiup/tiup-terminology-and-concepts.md | 1 + tiup/tiup-troubleshooting-guide.md | 7 ++++--- 4 files changed, 20 insertions(+), 16 deletions(-) diff --git a/tiup/tiup-documentation-guide.md b/tiup/tiup-documentation-guide.md index 7ae6809495663..25e41e5c10f21 100644 --- a/tiup/tiup-documentation-guide.md +++ b/tiup/tiup-documentation-guide.md @@ -1,5 +1,6 @@ --- title: TiUP Documentation Guide +summary: Guide you through TiUP documentation with links and introductions. category: tools --- @@ -7,19 +8,19 @@ category: tools ## TiUP user guide -- [TiUP Overview](/tiup/tiup-overview.md): Give an overall introduction to TiUP, for example, how to install and use TiUP -- [TiUP Terminology and Concepts](/tiup/tiup-terminology-and-concepts.md): Explain the terms that you might bump into when using TiUP, and help you understand the key concepts of TiUP -- [TiUP Component Management](/tiup/tiup-component-management.md): Introduce all TiUP commands in detail, and how to use TiUP to download, update and delete components -- [TiUP FAQ](/tiup/tiup-faq.md): Introduce common issues when you use TiUP, including FAQs of the third-party components of TiUP -- [TiUP Troubleshooting Guide](/tiup/tiup-troubleshooting-guide.md): Introduce the troubleshooting methods and solutions if you encounter issues when using TiUP +- [TiUP Overview](/tiup/tiup-overview.md): Gives an overall introduction to TiUP, for example, how to install and use TiUP +- [TiUP Terminology and Concepts](/tiup/tiup-terminology-and-concepts.md): Explains the terms that you might bump into when using TiUP, and help you understand the key concepts of TiUP +- [TiUP Component Management](/tiup/tiup-component-management.md): Introduces all TiUP commands in detail, and how to use TiUP to download, update and delete components +- [TiUP FAQ](/tiup/tiup-faq.md): Introduces common issues when you use TiUP, including FAQs of the third-party components of TiUP +- [TiUP Troubleshooting Guide](/tiup/tiup-troubleshooting-guide.md): Introduces the troubleshooting methods and solutions if you encounter issues when using TiUP ## TiUP component user guide -- [tiup-playground](/tiup/tiup-playground.md): Introduce how to use the TiUP playground component to quickly build a local TiDB cluster for testing -- [tiup-cluster](/tiup/tiup-cluster.md): Introduce the usage and command-line flags of the TiUP cluster component, which is used to deploy and maintain a TiDB cluster for production -- [tiup-mirror](/tiup/tiup-mirror.md): Introduce how to use the TiUP mirror component to customize a local offline mirror -- [tiup-bench](/tiup/tiup-bench.md): Introduce how to use the TiUP bench component for common stress testings, such as TPCC/TPCH +- [tiup-playground](/tiup/tiup-playground.md): Introduces how to use the TiUP playground component to quickly build a local TiDB cluster for testing +- [tiup-cluster](/tiup/tiup-cluster.md): Introduces the usage and command-line flags of the TiUP cluster component, which is used to deploy and maintain a TiDB cluster for production +- [tiup-mirror](/tiup/tiup-mirror.md): Introduces how to use the TiUP mirror component to customize a local offline mirror +- [tiup-bench](/tiup/tiup-bench.md): Introduces how to use the TiUP bench component for common stress testings, such as TPCC/TPCH ## TiUP resources -- [TiUP Issues](https://github.com/pingcap/tiup/issues): TiUP Github issue list \ No newline at end of file +- [TiUP Issues](https://github.com/pingcap/tiup/issues): Lists TiUP Github issues \ No newline at end of file diff --git a/tiup/tiup-faq.md b/tiup/tiup-faq.md index 149e238bfb359..a0ca638cbc095 100644 --- a/tiup/tiup-faq.md +++ b/tiup/tiup-faq.md @@ -1,5 +1,6 @@ --- title: TiUP FAQ +summary: Provide answers to common questions asked by TiUP users. category: tools --- @@ -21,9 +22,9 @@ The TiUP playground component is mainly used to build a stand-alone development Refer to [these templates](https://github.com/pingcap/tiup/tree/master/examples) to write the topology file. The templates include: -1. Multi-DC deployment topology -2. Minimal deployment topology -3. Complete topology file +- Multi-DC deployment topology +- Minimal deployment topology +- Complete topology file You can edit your topology file based on the templates and your needs. diff --git a/tiup/tiup-terminology-and-concepts.md b/tiup/tiup-terminology-and-concepts.md index 620e73f817c88..efcb220993956 100644 --- a/tiup/tiup-terminology-and-concepts.md +++ b/tiup/tiup-terminology-and-concepts.md @@ -1,5 +1,6 @@ --- title: TiUP Terminology and Concepts +summary: Explain the terms and concepts of TiUP. category: tools --- diff --git a/tiup/tiup-troubleshooting-guide.md b/tiup/tiup-troubleshooting-guide.md index 4cf372930a9b8..334a435beaeb3 100644 --- a/tiup/tiup-troubleshooting-guide.md +++ b/tiup/tiup-troubleshooting-guide.md @@ -1,5 +1,6 @@ --- title: TiUP Troubleshooting Guide +summary: Introduce the troubleshooting methods and solutions if you encounter issues when using TiUP. category: tools --- @@ -33,9 +34,9 @@ During deployment, component packages are uploaded to the remote host and the in To solve this issue, confirm whether you have specified the private key by running `tiup cluster deploy -i identity_file`: -1. If the `-i` flag is not specified, it might be that TiUP does not automatically find the private key path. It is recommended to explicitly specify the private key path using `-i`. -2. If the `-i` flag is specified, it might be that TiUP cannot log in to the remote host using the specified private key. You can verify it by manually executing the `ssh -i identity_file user@remote` command. -3. If a password is used to log in to the remote host, make sure that you have specified the `-p` flag and entered the correct login password. +- If the `-i` flag is not specified, it might be that TiUP does not automatically find the private key path. It is recommended to explicitly specify the private key path using `-i`. +- If the `-i` flag is specified, it might be that TiUP cannot log in to the remote host using the specified private key. You can verify it by manually executing the `ssh -i identity_file user@remote` command. +- If a password is used to log in to the remote host, make sure that you have specified the `-p` flag and entered the correct login password. ### The process of upgrading the cluster using the TiUP cluster component is interrupted From e00559ab94ac4314e39bdffdbf53c97328729307 Mon Sep 17 00:00:00 2001 From: Keke Yi <40977455+yikeke@users.noreply.github.com> Date: Wed, 1 Jul 2020 14:55:44 +0800 Subject: [PATCH 10/11] Apply suggestions from code review Co-authored-by: TomShawn <41534398+TomShawn@users.noreply.github.com> --- tiup/tiup-faq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tiup/tiup-faq.md b/tiup/tiup-faq.md index a0ca638cbc095..233eec90a8f9a 100644 --- a/tiup/tiup-faq.md +++ b/tiup/tiup-faq.md @@ -14,7 +14,7 @@ TiUP supports specifying the mirror source through the `TIUP_MIRRORS` environmen TiUP does not support third-party components for the time being, but the TiUP Team has developed the TiUP component development specifications and is developing the tiup-publish component. After everything is ready, a contributor can publish their own components to TiUP's official mirrors by using the `tiup publish ` command. -## What is the difference between tiup-playground and tiup-cluster? +## What is the difference between the TiUP playground and TiUP cluster components? The TiUP playground component is mainly used to build a stand-alone development environment on Linux or macOS operating systems. It helps you get started quickly and run a specified version of the TiUP cluster easily. The TiUP cluster component is mainly used to deploy and maintain a production environment cluster, which is usually a large-scale cluster. From ae8d4e524c800808d8a032cb663445a4d41ad5c4 Mon Sep 17 00:00:00 2001 From: TomShawn <41534398+TomShawn@users.noreply.github.com> Date: Wed, 1 Jul 2020 16:13:45 +0800 Subject: [PATCH 11/11] Update tiup/tiup-component-management.md --- tiup/tiup-component-management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tiup/tiup-component-management.md b/tiup/tiup-component-management.md index 5505f823a0cfa..83511b68ee56b 100644 --- a/tiup/tiup-component-management.md +++ b/tiup/tiup-component-management.md @@ -30,7 +30,7 @@ You can also use the following flags in the above commands: - `--installed`: checks which components or which version of a specific component has been installed locally. -`--all`: views all components, including the hidden ones --`--verbose`: View all columns (including installed versions and supported platforms) +-`--verbose`: views all columns (including installed versions and supported platforms) Example 1: View all currently installed components.