diff --git a/TOC.md b/TOC.md index a7c5c7d2a7a3a..5f5698e860abc 100644 --- a/TOC.md +++ b/TOC.md @@ -411,12 +411,16 @@ + [Overview](/tiflash/tiflash-overview.md) + [Use TiFlash](/tiflash/use-tiflash.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) - + [tiup-mirror](/tiup/tiup-mirrors.md) + + [tiup-mirror](/tiup/tiup-mirror.md) + [tiup-bench](/tiup/tiup-bench.md) + [Telemetry](/telemetry.md) + [Errors Codes](/error-codes.md) diff --git a/production-offline-deployment-using-tiup.md b/production-offline-deployment-using-tiup.md index d8f9cbc5779f3..ec6b0f7882c28 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 eff3b531d18fd..ae6f61a38f994 100644 --- a/tiup/tiup-cluster.md +++ b/tiup/tiup-cluster.md @@ -63,7 +63,11 @@ 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:** +> +> 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/manage-tiup-component.md b/tiup/tiup-component-management.md similarity index 95% rename from tiup/manage-tiup-component.md rename to tiup/tiup-component-management.md index eb880a912e542..83511b68ee56b 100644 --- a/tiup/manage-tiup-component.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 @@ -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`: views all components, including the hidden ones +-`--verbose`: views all columns (including installed versions and supported platforms) Example 1: View all currently installed components. diff --git a/tiup/tiup-documentation-guide.md b/tiup/tiup-documentation-guide.md new file mode 100644 index 0000000000000..25e41e5c10f21 --- /dev/null +++ b/tiup/tiup-documentation-guide.md @@ -0,0 +1,26 @@ +--- +title: TiUP Documentation Guide +summary: Guide you through TiUP documentation with links and introductions. +category: tools +--- + +# TiUP Documentation Guide + +## TiUP user guide + +- [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): 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): Lists TiUP Github issues \ No newline at end of file diff --git a/tiup/tiup-faq.md b/tiup/tiup-faq.md new file mode 100644 index 0000000000000..233eec90a8f9a --- /dev/null +++ b/tiup/tiup-faq.md @@ -0,0 +1,56 @@ +--- +title: TiUP FAQ +summary: Provide answers to common questions asked by TiUP users. +category: tools +--- + +# TiUP FAQ + +## Can TiUP not use the official mirror source? + +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. + +## How do I put my own component into the TiUP mirrors? + +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 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. + +## 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 include: + +- Multi-DC deployment topology +- Minimal deployment topology +- 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? + +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 is any directory or port conflict, the deployment or scaling process is interrupted. + +## Are port and directory conflicts detected among different clusters? + +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. + +## 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 + +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-mirror.md b/tiup/tiup-mirror.md new file mode 100644 index 0000000000000..119c0bf33de5c --- /dev/null +++ b/tiup/tiup-mirror.md @@ -0,0 +1,91 @@ +--- +title: Create a Private Mirror +summary: Learn how to create a private mirror. +category: tools +aliases: ['/tidb/dev/tiup-mirrors','/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 `mirror` command. You can also use the `mirror` command for offline deployment. + +## TiUP `mirror` overview + +Execute the following command to get the help information of the `mirror` command: + +{{< copyable "shell-regular" >}} + +```bash +tiup mirror --help +``` + +```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 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: + -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 `tiup mirror clone` command is used to build a local mirror. The basic usage is as follows: + +{{< copyable "shell-regular" >}} + +```bash +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 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 use prefix matching to match the version when cloning + + 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 + + If you specify the `--full` flag, you can clone the official mirror fully. + + > **Note:** + > + > 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 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 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 the `mirror` command. + +### 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-mirrors.md b/tiup/tiup-mirrors.md deleted file mode 100644 index 17025124a3429..0000000000000 --- a/tiup/tiup-mirrors.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -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/'] ---- - -# 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. - -## TiUP `mirrors` overview - -Execute the following command to get the help information of the `mirrors` component: - -{{< copyable "shell-regular" >}} - -```bash -tiup mirrors --help -``` - -``` -Starting component `mirrors`: /Users/joshua/.tiup/components/mirrors/v0.0.1/mirrors -Build a local mirrors and download all selected components -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 -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 -``` - -The basic usage of the `tiup mirrors` command is as follows: - -{{< copyable "shell-regular" >}} - -```bash -tiup mirrors [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: - -- Determines whether to overwrite local packages - - 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. - -- Determines whether to use the full clone - - If you specify the `--full` flag, you can clone the official mirror fully. - - > **Note:** - > - > If `--full` and the other flags 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. - -- 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. - -## 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 - ``` - - `/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 -``` - -After importing the `PATH` variable, you can start to use TiUP. Make sure that the `TIUP_MIRRORS` variable points to the private mirror. diff --git a/tiup/tiup-overview.md b/tiup/tiup-overview.md index e0cb46f72178c..6462b23026831 100644 --- a/tiup/tiup-overview.md +++ b/tiup/tiup-overview.md @@ -65,16 +65,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] @@ -83,7 +78,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 @@ -112,11 +107,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 @@ -129,10 +124,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 new file mode 100644 index 0000000000000..efcb220993956 --- /dev/null +++ b/tiup/tiup-terminology-and-concepts.md @@ -0,0 +1,35 @@ +--- +title: TiUP Terminology and Concepts +summary: Explain the terms and concepts of TiUP. +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: + ++ 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 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. + ++ 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: + ++ `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 new file mode 100644 index 0000000000000..334a435beaeb3 --- /dev/null +++ b/tiup/tiup-troubleshooting-guide.md @@ -0,0 +1,57 @@ +--- +title: TiUP Troubleshooting Guide +summary: Introduce the troubleshooting methods and solutions if you encounter issues when using TiUP. +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 forcibly 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 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 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 + +### `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 have specified the private key by running `tiup cluster deploy -i identity_file`: + +- 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 + +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. 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. + +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 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.