diff --git a/tiup/tiup-cluster-topology-reference.md b/tiup/tiup-cluster-topology-reference.md index dd9a493c8da02..62aecac97d245 100644 --- a/tiup/tiup-cluster-topology-reference.md +++ b/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 listening IP address. If it is empty, each instance automatically sets it to `::` or `0.0.0.0` based on whether its `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 components that share a version number, such as TiDB, TiKV, PD, and TiCDC, there are no complete tests to ensure that they work properly in a mixed-version deployment scenario. Ensure that you use this section only in test environments, 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. + +`component_versions` contains the following fields: + +- `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: diff --git a/tiup/tiup-component-management.md b/tiup/tiup-component-management.md index 3a9136dba566f..386aae8fe72f5 100644 --- a/tiup/tiup-component-management.md +++ b/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 enables you to call a component without going through TiUP each time, while preserving the ability to switch between different versions. However, this method lacks the process of automatic update checking and setting certain environment variables and some components (such as ctl) cannot 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 cannot 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 +``` diff --git a/upgrade-tidb-using-tiup.md b/upgrade-tidb-using-tiup.md index 3f3fda8b386bf..f8fd2c4898b0c 100644 --- a/upgrade-tidb-using-tiup.md +++ b/upgrade-tidb-using-tiup.md @@ -204,6 +204,29 @@ tiup cluster upgrade 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 cluster upgrade. These components will remain at their fixed version in the subsequent upgrade unless you specify a different version. + +> **Note:** +> +> For components that share a version number, such as TiDB, TiKV, PD, and TiCDC, there are no complete tests to ensure that they work properly in a mixed-version deployment scenario. Ensure that you use this section only in test environments, 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.