update tiup doc

tiup/tiup-cluster-topology-reference.md

@@ -15,6 +15,7 @@ A topology configuration file for TiDB deployment using TiUP might contain the f
 - [global](#global): The cluster's global configuration. Some of the configuration items use the default values and you can configure them separately in each instance.
 - [monitored](#monitored): Configuration for monitoring services, namely, the blackbox_exporter and the `node_exporter`. On each machine, a `node_exporter` and a `blackbox_exporter` are deployed.
 - [server_configs](#server_configs): Components' global configuration. You can configure each component separately. If an instance has a configuration item with the same name, the instance's configuration item will take effect.
+- [component_versions](#component_versions): Component version. You can configure it when a component does not use the cluster version. This section is introduced in tiup-cluster v1.14.0.
 - [pd_servers](#pd_servers): The configuration of the PD instance. This configuration specifies the machines to which the PD component is deployed.
 - [tidb_servers](#tidb_servers): The configuration of the TiDB instance. This configuration specifies the machines to which the TiDB component is deployed.
 - [tikv_servers](#tikv_servers): The configuration of the TiKV instance. This configuration specifies the machines to which the TiKV component is deployed.
@@ -40,6 +41,8 @@ The `global` section corresponds to the cluster's global configuration and has t
 
 - `enable_tls`: Specifies whether to enable TLS for the cluster. After TLS is enabled, the generated TLS certificate must be used for connections between components or between the client and the component. The default value is `false`.
 
+- `listen_host`: Specifies the default listen IP address. If it is empty, each instance will automatically set it to `::` or `0.0.0.0` by judging whether its own `host` field contains `:`. This field is introduced in tiup-cluster v1.14.0. 
+
 - `deploy_dir`: The deployment directory of each component. The default value is `"deployed"`. Its application rules are as follows:
 
     - If the absolute path of `deploy_dir` is configured at the instance level, the actual deployment directory is `deploy_dir` configured for the instance.
@@ -153,6 +156,43 @@ server_configs:
 
 The above configuration specifies the global configuration of TiDB and TiKV.
 
+### `component_versions`
+
+> **Note:**
+>
+> For TiDB, TiKV, PD, TiCDC, and other components that share their own version numbers, there are no complete tests to ensure that they work properly in a mixed-version scenario. Ensure that you use this section only for testing scenarios, or with the help of [technical support](/support.md).
+
+`component_versions` is used to specify the version number of a certain component. 
+
+- When `component_versions` is not configured, each component either uses the same version number as the TiDB cluster (such as PD and TiKV), or uses the latest version (such as Alertmanager). 
+- When `component_versions` is configured, the corresponding component will use the specified version, and this version will be used in subsequent cluster scaling and upgrade operations. 
+
+Make sure you only configure it when you need to use a specific version of a component. 
+
+The main fields of `component_versions` include:
+
+- `tikv`: The version of the TiKV component
+- `tiflash`: The version of the TiFlash component
+- `pd`: The version of the PD component
+- `tidb_dashboard`: The version of the standalone TiDB Dashboard component
+- `pump`: The version of the Pump component
+- `drainer`: The version of the Drainer component
+- `cdc`: The version of the CDC component
+- `kvcdc`: The version of the TiKV-CDC component
+- `tiproxy`: The version of the TiProxy component
+- `prometheus`: The version of the Prometheus component
+- `grafana`: The version of the Grafana component
+- `alertmanager`: The version of the Alertmanager component
+
+The following is an example configuration for `component_versions`:
+
+```yaml
+component_versions:
+  kvcdc: "v1.1.1"
+```
+
+The preceding configuration specifies the version number of TiKV-CDC to be `v1.1.1`.
+
 ### `pd_servers`
 
 `pd_servers` specifies the machines to which PD services are deployed. It also specifies the service configuration on each machine. `pd_servers` is an array, and each element of the array contains the following fields:

tiup/tiup-component-management.md

@@ -15,6 +15,8 @@ You can use the following TiUP commands to manage components in the TiUP ecosyst
 - status: Checks the status of a running component.
 - clean: Cleans up the instance on which a component is deployed.
 - help: Prints the help information. If you append another TiUP command to this command, the usage of the appended command is printed.
+- link: Links the binary of the component to the executable directory (`$TIUP_HOME/bin/`).
+- unlink: Deletes the soft link generated by the `tiup link` command.
 
 This document introduces the common component management operations and the corresponding TiUP commands.
 
@@ -242,3 +244,43 @@ Example 3: Uninstall all installed components.
 ```shell
 tiup uninstall --all
 ```
+
+### Link components
+
+TiUP v1.13.0 adds the experimental `link` and `unlink` commands to link the binary of a component to the executable directory (`$TIUP_HOME/bin/`) and remove the link. This feature allows you to call a component without going through TiUP each time, while preserving the ability to switch between multiple versions. However, this method lacks the process of automatic update checking and setting certain environment variables and some components (for example, ctl) can not be used. Therefore, it is recommended to use it only when necessary.
+
+Example 1: Install and link the latest version of the cluster component
+
+```shell
+tiup install cluster
+tiup link cluster
+```
+
+Example 2: Switch the cluster component to version v1.13.0
+
+```shell
+tiup link cluster:v1.13.0
+```
+
+The following is the output of the `tiup link cluster` command:
+
+```shell
+package cluster provides these executables: tiup-cluster
+```
+
+This indicates that the binary name of the cluster component is `tiup-cluster`. After the link command is completed, you can use the cluster component by directly typing `tiup-cluster` into the command line.
+
+Example 3: Cancel the link of the cluster component
+
+```shell
+tiup unlink cluster
+```
+
+Example 4: Manage the version of TiUP
+
+Before v1.13.0, TiUP is installed in `~/.tiup/bin/` and different versions can not coexist. Starting from v1.13.0, you can install and link TiUP like any other components.
+
+```shell
+tiup update --self # update tiup itself to a version that supports link
+tiup link tiup:v1.13.0
+```

upgrade-tidb-using-tiup.md

@@ -204,6 +204,29 @@ tiup cluster upgrade <cluster-name> v7.4.0
 >
 > + Try to avoid creating a new clustered index table when you apply rolling updates to the clusters using TiDB Binlog.
 
+#### Specify the component version during upgrade
+
+Starting from tiup-cluster v1.14.0, you can specify certain components to a specific version during the cluster upgrade. The specified components will use the specified versions and their version numbers will remain unchanged in the next upgrade unless you specify a new version.
+
+> **Note: **
+>
+> For TiDB, TiKV, PD, TiCDC, and other components that share their own version numbers, there are no complete tests to ensure that they work properly in a mixed-version scenario. Ensure that you use this section only for testing scenarios, or with the help of [technical support](/support.md).
+
+```shell
+tiup cluster upgrade -h | grep "version string"
+      --alertmanager-version string        Fix the version of alertmanager and no longer follows the cluster version.
+      --blackbox-exporter-version string   Fix the version of blackbox-exporter and no longer follows the cluster version.
+      --cdc-version string                 Fix the version of cdc and no longer follows the cluster version.
+      --ignore-version-check               Ignore checking if target version is bigger than current version.
+      --node-exporter-version string       Fix the version of node-exporter and no longer follows the cluster version.
+      --pd-version string                  Fix the version of pd and no longer follows the cluster version.
+      --tidb-dashboard-version string      Fix the version of tidb-dashboard and no longer follows the cluster version.
+      --tiflash-version string             Fix the version of tiflash and no longer follows the cluster version.
+      --tikv-cdc-version string            Fix the version of tikv-cdc and no longer follows the cluster version.
+      --tikv-version string                Fix the version of tikv and no longer follows the cluster version.
+      --tiproxy-version string             Fix the version of tiproxy and no longer follows the cluster version.
+```
+
 #### Offline upgrade
 
 1. Before the offline upgrade, you first need to stop the entire cluster.