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](/tiup/tiup-cluster-topology-reference.md#component_versions): Component version, used when component not use cluster version。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`: Default listen host。If it is empty, each instance will automatically set it to `::` or `0.0.0.0` by judging whether its own `Host` field contains `:`.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,36 @@ server_configs:
 
 The above configuration specifies the global configuration of TiDB and TiKV.
 
+### `component_versions`
+
+> **Note:**
+>
+> For components such as TiDB, TiKV, PD, TiCDC that share the same version number, there is no complete test to ensure that they can work properly in a cross-version mixing scenario. Therefore, it is recommended to only use such scenarios for testing purposes or operate under the help of support.
+
+`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 this field is configured, the corresponding component will use the specified version, and this version will be used in subsequent cluster expansion and upgrade operations. Users should only configure this when they need to fix the version number of a component. The main fields 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
+
+Example configuration for `component_versions`:
+
+```yaml
+component_versions:
+  kvcdc: "v1.1.1"
+```
+
+The above 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: Link the binary of the component to the executable directory (`$TIUP_HOME/bin/`).
+- unlink: Delete 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 Component
+
+TiUP v1.13.0 added 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 users to call the 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. Therefore, it's 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 `tiup link cluster` command will output the following:
+
+```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 itself
+
+Before v1.13.0, TiUP itself was installed in `~/.tiup/bin/` and could not coexist with multiple versions. Starting from v1.13.0, TiUP can be installed and linked like all 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,27 @@ 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 Component Version during Upgrade
+
+Starting from tiup-cluster v1.14.0, it supports specifying certain components to a specific version during the cluster upgrade. The specified components will be fixed to the specified version and their version number will not change again in the next upgrade unless you specify a new version.
+
+{{< copyable "shell-regular" >}}
+
+```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 pv 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.