重要

現在表示されているページは、TiDBのアーカイブされたドキュメント (非更新) です。TiDBをご利用の場合、最新のLTS (Long Term Support) バージョンの使用を推奨します。

重要

このページは英語版のページを機械翻訳しています。原文はこちらからご覧ください。

TiUP を使用してオンライン TiDBクラスタをデプロイおよび管理する

このドキュメントでは、TiUP クラスターコンポーネントの使用方法に焦点を当てています。オンライン展開の完全な手順については、 TiUP を使用して TiDBクラスタをデプロイするを参照してください。

ローカルテスト展開に使用されるTiUP プレイグラウンドコンポーネントと同様に、TiUP クラスターコンポーネントは、TiDB を運用環境にすばやく展開します。プレイグラウンドと比較して、クラスターコンポーネントは、アップグレード、スケーリング、さらには操作と監査を含む、より強力な運用クラスター管理機能を提供します。

クラスターコンポーネントのヘルプ情報については、次のコマンドを実行します。

tiup cluster

Starting component `cluster`: /home/tidb/.tiup/components/cluster/v1.11.0/cluster
Deploy a TiDB cluster for production

Usage:
  tiup cluster [command]

Available Commands:
  check       Precheck a cluster
  deploy      Deploy a cluster for production
  start       Start a TiDB cluster
  stop        Stop a TiDB cluster
  restart     Restart a TiDB cluster
  scale-in    Scale in a TiDB cluster
  scale-out   Scale out a TiDB cluster
  destroy     Destroy a specified cluster
  clean       (Experimental) Clean up a specified cluster
  upgrade     Upgrade a specified TiDB cluster
  display     Display information of a TiDB cluster
  list        List all clusters
  audit       Show audit log of cluster operation
  import      Import an existing TiDB cluster from TiDB-Ansible
  edit-config Edit TiDB cluster config
  reload      Reload a TiDB cluster's config and restart if needed
  patch       Replace the remote package with a specified package and restart the service
  help        Help about any command

Flags:
  -c, --concurrency int     Maximum number of concurrent tasks allowed (defaults to `5`)
      --format string       (EXPERIMENTAL) The format of output, available values are [default, json] (default "default")
  -h, --help                help for tiup
      --ssh string          (Experimental) The executor type. Optional values are 'builtin', 'system', and 'none'.
      --ssh-timeout uint    Timeout in seconds to connect a host via SSH. Operations that don't need an SSH connection are ignored. (default 5)
  -v, --version            TiUP version
      --wait-timeout uint   Timeout in seconds to wait for an operation to complete. Inapplicable operations are ignored. (defaults to `120`)
  -y, --yes                 Skip all confirmations and assumes 'yes'

クラスターをデプロイする

クラスターをデプロイするには、 tiup cluster deployコマンドを実行します。コマンドの使用法は次のとおりです。

tiup cluster deploy <cluster-name> <version> <topology.yaml> [flags]

このコマンドでは、クラスター名、TiDB クラスターのバージョン、およびクラスターのトポロジーファイルを指定する必要があります。

トポロジー・ファイルを作成するには、例を参照してください。次のファイルは、最も単純なトポロジの例です。

ノート：
TiUP クラスターコンポーネントがデプロイとスケーリングに使用するトポロジファイルは、 yamlの構文を使用して記述されているため、インデントが正しいことを確認してください。

---

pd_servers:
  - host: 172.16.5.134
    name: pd-134
  - host: 172.16.5.139
    name: pd-139
  - host: 172.16.5.140
    name: pd-140

tidb_servers:
  - host: 172.16.5.134
  - host: 172.16.5.139
  - host: 172.16.5.140

tikv_servers:
  - host: 172.16.5.134
  - host: 172.16.5.139
  - host: 172.16.5.140

tiflash_servers:
  - host: 172.16.5.141
  - host: 172.16.5.142
  - host: 172.16.5.143

grafana_servers:
  - host: 172.16.5.134

monitoring_servers:
  - host: 172.16.5.134

デフォルトでは、TiUP は amd64アーキテクチャで実行されるバイナリファイルとしてデプロイされます。ターゲットマシンが arm64アーキテクチャの場合は、トポロジファイルで構成できます。

global:
  arch: "arm64"           # Configures all machines to use the binary files of the arm64 architecture by default

tidb_servers:
  - host: 172.16.5.134
    arch: "amd64"         # Configures this machine to use the binary files of the amd64 architecture
  - host: 172.16.5.139
    arch: "arm64"         # Configures this machine to use the binary files of the arm64 architecture
  - host: 172.16.5.140    # Machines that are not configured with the arch field use the default value in the global field, which is arm64 in this case.

...

ファイルを/tmp/topology.yamlとして保存します。 TiDB v6.3.0 を使用する場合で、クラスター名がprod-clusterの場合は、次のコマンドを実行します。

tiup cluster deploy -p prod-cluster v6.3.0 /tmp/topology.yaml

実行中、TiUP はトポロジを再度確認するように求め、ターゲットマシンの root パスワードを要求します ( -pフラグはパスワードの入力を意味します)。

Please confirm your topology:
TiDB Cluster: prod-cluster
TiDB Version: v6.3.0
Type        Host          Ports                            OS/Arch       Directories
----        ----          -----                            -------       -----------
pd          172.16.5.134  2379/2380                        linux/x86_64  deploy/pd-2379,data/pd-2379
pd          172.16.5.139  2379/2380                        linux/x86_64  deploy/pd-2379,data/pd-2379
pd          172.16.5.140  2379/2380                        linux/x86_64  deploy/pd-2379,data/pd-2379
tikv        172.16.5.134  20160/20180                      linux/x86_64  deploy/tikv-20160,data/tikv-20160
tikv        172.16.5.139  20160/20180                      linux/x86_64  deploy/tikv-20160,data/tikv-20160
tikv        172.16.5.140  20160/20180                      linux/x86_64  deploy/tikv-20160,data/tikv-20160
tidb        172.16.5.134  4000/10080                       linux/x86_64  deploy/tidb-4000
tidb        172.16.5.139  4000/10080                       linux/x86_64  deploy/tidb-4000
tidb        172.16.5.140  4000/10080                       linux/x86_64  deploy/tidb-4000
tiflash     172.16.5.141  9000/8123/3930/20170/20292/8234  linux/x86_64  deploy/tiflash-9000,data/tiflash-9000
tiflash     172.16.5.142  9000/8123/3930/20170/20292/8234  linux/x86_64  deploy/tiflash-9000,data/tiflash-9000
tiflash     172.16.5.143  9000/8123/3930/20170/20292/8234  linux/x86_64  deploy/tiflash-9000,data/tiflash-9000
prometheus  172.16.5.134  9090         deploy/prometheus-9090,data/prometheus-9090
grafana     172.16.5.134  3000         deploy/grafana-3000
Attention:
    1. If the topology is not what you expected, check your yaml file.
    2. Please confirm there is no port/directory conflicts in same host.
Do you want to continue? [y/N]:

パスワードを入力すると、TiUP クラスターは必要なコンポーネントをダウンロードし、対応するマシンに展開します。次のメッセージが表示されたら、デプロイは成功です。

Deployed cluster `prod-cluster` successfully

クラスタリストをビューする

クラスターが正常にデプロイされたら、次のコマンドを実行してクラスターリストを表示します。

tiup cluster list

Starting /root/.tiup/components/cluster/v1.11.0/cluster list
Name          User  Version    Path                                               PrivateKey
----          ----  -------    ----                                               ----------
prod-cluster  tidb  v6.3.0    /root/.tiup/storage/cluster/clusters/prod-cluster  /root/.tiup/storage/cluster/clusters/prod-cluster/ssh/id_rsa

クラスターを開始する

クラスターが正常にデプロイされたら、次のコマンドを実行してクラスターを開始します。

tiup cluster start prod-cluster

クラスターの名前を忘れた場合は、 tiup cluster listを実行してクラスターリストを表示します。

TiUP はsystemdを使用してデーモンプロセスを開始します。プロセスが予期せず終了した場合、15 秒後にプルアップされます。

クラスターの状態を確認する

TiUP は、クラスター内の各コンポーネントのステータスを表示するためのtiup cluster displayのコマンドを提供します。このコマンドを使用すると、コンポーネントのステータスを確認するために各マシンにログインする必要がなくなります。コマンドの使用法は次のとおりです。

tiup cluster display prod-cluster

Starting /root/.tiup/components/cluster/v1.11.0/cluster display prod-cluster
TiDB Cluster: prod-cluster
TiDB Version: v6.3.0
ID                  Role        Host          Ports                            OS/Arch       Status  Data Dir              Deploy Dir
--                  ----        ----          -----                            -------       ------  --------              ----------
172.16.5.134:3000   grafana     172.16.5.134  3000                             linux/x86_64  Up      -                     deploy/grafana-3000
172.16.5.134:2379   pd          172.16.5.134  2379/2380                        linux/x86_64  Up|L    data/pd-2379          deploy/pd-2379
172.16.5.139:2379   pd          172.16.5.139  2379/2380                        linux/x86_64  Up|UI   data/pd-2379          deploy/pd-2379
172.16.5.140:2379   pd          172.16.5.140  2379/2380                        linux/x86_64  Up      data/pd-2379          deploy/pd-2379
172.16.5.134:9090   prometheus  172.16.5.134  9090                             linux/x86_64  Up      data/prometheus-9090  deploy/prometheus-9090
172.16.5.134:4000   tidb        172.16.5.134  4000/10080                       linux/x86_64  Up      -                     deploy/tidb-4000
172.16.5.139:4000   tidb        172.16.5.139  4000/10080                       linux/x86_64  Up      -                     deploy/tidb-4000
172.16.5.140:4000   tidb        172.16.5.140  4000/10080                       linux/x86_64  Up      -                     deploy/tidb-4000
172.16.5.141:9000   tiflash     172.16.5.141  9000/8123/3930/20170/20292/8234  linux/x86_64  Up      data/tiflash-9000     deploy/tiflash-9000
172.16.5.142:9000   tiflash     172.16.5.142  9000/8123/3930/20170/20292/8234  linux/x86_64  Up      data/tiflash-9000     deploy/tiflash-9000
172.16.5.143:9000   tiflash     172.16.5.143  9000/8123/3930/20170/20292/8234  linux/x86_64  Up      data/tiflash-9000     deploy/tiflash-9000
172.16.5.134:20160  tikv        172.16.5.134  20160/20180                      linux/x86_64  Up      data/tikv-20160       deploy/tikv-20160
172.16.5.139:20160  tikv        172.16.5.139  20160/20180                      linux/x86_64  Up      data/tikv-20160       deploy/tikv-20160
172.16.5.140:20160  tikv        172.16.5.140  20160/20180                      linux/x86_64  Up      data/tikv-20160       deploy/tikv-20160

Status列は、サービスが正常に実行されているかどうかを示すためにUpまたはDownを使用します。

PD コンポーネントの場合、 |Lまたは|UIがUpまたはDownに追加される場合があります。 |Lは PD ノードがリーダーであることを示し、 |UIはTiDB ダッシュボードが PD ノードで実行されていることを示します。

クラスターでのスケーリング

ノート：
このセクションでは、scale-in コマンドの構文のみを説明します。オンラインスケーリングの詳細な手順については、 TiUP を使用して TiDBクラスタをスケーリングするを参照してください。

クラスターでのスケーリングとは、一部のノードをオフラインにすることを意味します。この操作は、クラスターから特定のノードを削除し、残りのファイルを削除します。

TiKV、TiFlash、および TiDB Binlogコンポーネントのオフラインプロセスは非同期であり (API を使用してノードを削除する必要があります)、プロセスに時間がかかるため (ノードが正常にオフラインにされたかどうかを継続的に監視する必要があります)、特別な処理が行われます。 TiKV、TiFlash、および TiDB Binlogコンポーネントに与えられます。

TiKV、TiFlash、 Binlogの場合:
- TiUP クラスターは、API を介してノードをオフラインにし、プロセスの完了を待たずに直接終了します。
- その後、クラスタ操作に関するコマンドが実行されると、TiUP クラスタは、オフラインになった TiKV、TiFlash、またはBinlogノードがあるかどうかを調べます。そうでない場合、TiUP クラスターは指定された操作を続行します。存在する場合、TiUP クラスターは次の手順を実行します。
  1. オフラインになったノードのサービスを停止します。
  2. ノードに関連するデータファイルをクリーンアップします。
  3. クラスタトポロジからノードを削除します。
その他のコンポーネントの場合:
- PD コンポーネントをダウンさせると、TiUP クラスターは、API を介して指定されたノードをクラスターから迅速に削除し、指定された PD ノードのサービスを停止し、関連するデータファイルを削除します。
- 他のコンポーネントを停止すると、TiUP クラスターはノードサービスを直接停止し、関連するデータファイルを削除します。

スケールインコマンドの基本的な使用法:

tiup cluster scale-in <cluster-name> -N <node-id>

このコマンドを使用するには、クラスター名とノード ID の少なくとも 2 つのフラグを指定する必要があります。ノード ID は、前のセクションのtiup cluster displayコマンドを使用して取得できます。

たとえば、 172.16.5.140の TiKV ノードをオフラインにするには、次のコマンドを実行します。

tiup cluster scale-in prod-cluster -N 172.16.5.140:20160

tiup cluster displayを実行すると、TiKV ノードがOfflineとマークされていることがわかります。

tiup cluster display prod-cluster

Starting /root/.tiup/components/cluster/v1.11.0/cluster display prod-cluster
TiDB Cluster: prod-cluster
TiDB Version: v6.3.0
ID                  Role        Host          Ports                            OS/Arch       Status   Data Dir              Deploy Dir
--                  ----        ----          -----                            -------       ------   --------              ----------
172.16.5.134:3000   grafana     172.16.5.134  3000                             linux/x86_64  Up       -                     deploy/grafana-3000
172.16.5.134:2379   pd          172.16.5.134  2379/2380                        linux/x86_64  Up|L     data/pd-2379          deploy/pd-2379
172.16.5.139:2379   pd          172.16.5.139  2379/2380                        linux/x86_64  Up|UI    data/pd-2379          deploy/pd-2379
172.16.5.140:2379   pd          172.16.5.140  2379/2380                        linux/x86_64  Up       data/pd-2379          deploy/pd-2379
172.16.5.134:9090   prometheus  172.16.5.134  9090                             linux/x86_64  Up       data/prometheus-9090  deploy/prometheus-9090
172.16.5.134:4000   tidb        172.16.5.134  4000/10080                       linux/x86_64  Up       -                     deploy/tidb-4000
172.16.5.139:4000   tidb        172.16.5.139  4000/10080                       linux/x86_64  Up       -                     deploy/tidb-4000
172.16.5.140:4000   tidb        172.16.5.140  4000/10080                       linux/x86_64  Up       -                     deploy/tidb-4000
172.16.5.141:9000   tiflash     172.16.5.141  9000/8123/3930/20170/20292/8234  linux/x86_64  Up       data/tiflash-9000     deploy/tiflash-9000
172.16.5.142:9000   tiflash     172.16.5.142  9000/8123/3930/20170/20292/8234  linux/x86_64  Up       data/tiflash-9000     deploy/tiflash-9000
172.16.5.143:9000   tiflash     172.16.5.143  9000/8123/3930/20170/20292/8234  linux/x86_64  Up       data/tiflash-9000     deploy/tiflash-9000
172.16.5.134:20160  tikv        172.16.5.134  20160/20180                      linux/x86_64  Up       data/tikv-20160       deploy/tikv-20160
172.16.5.139:20160  tikv        172.16.5.139  20160/20180                      linux/x86_64  Up       data/tikv-20160       deploy/tikv-20160
172.16.5.140:20160  tikv        172.16.5.140  20160/20180                      linux/x86_64  Offline  data/tikv-20160       deploy/tikv-20160

PD がノード上のデータを他の TiKV ノードにスケジュールした後、このノードは自動的に削除されます。

クラスターをスケールアウトする

ノート：
このセクションでは、スケールアウトコマンドの構文のみを説明します。オンラインスケーリングの詳細な手順については、 TiUP を使用して TiDBクラスタをスケーリングするを参照してください。

スケールアウト操作には、デプロイと同様の内部ロジックがあります。TiUP クラスターコンポーネントは、最初にノードの SSH 接続を確認し、ターゲットノードに必要なディレクトリを作成してから、デプロイ操作を実行し、ノードサービスを開始します。

PD をスケールアウトすると、ノードがjoinずつクラスターに追加され、PD に関連付けられているサービスの構成が更新されます。他のサービスをスケールアウトすると、サービスが直接開始され、クラスターに追加されます。

すべてのサービスは、スケールアウト時に正当性の検証を行います。検証結果は、スケールアウトが成功したかどうかを示します。

tidb-testクラスターに TiKV ノードと PD ノードを追加するには、次の手順を実行します。

scale.yamlのファイルを作成し、新しい TiKV ノードと PD ノードの IP を追加します。
ノート：
既存のノードではなく、新しいノードの説明のみを含むトポロジファイルを作成する必要があります。
```
---

pd_servers:
  - host: 172.16.5.140

tikv_servers:
  - host: 172.16.5.140
```
スケールアウト操作を実行します。 TiUP クラスタは、 scale.yamlで説明したポート、ディレクトリ、およびその他の情報に従って、対応するノードをクラスタに追加します。
```
tiup cluster scale-out tidb-test scale.yaml
```
コマンドの実行後、 tiup cluster display tidb-testを実行すると、スケールアウトされたクラスターの状態を確認できます。

ローリングアップグレード

ノート：
このセクションでは、upgrade コマンドの構文についてのみ説明します。オンラインアップグレードの詳細な手順については、 TiUP を使用して TiDB をアップグレードするを参照してください。

ローリングアップグレード機能は、TiDB の分散機能を活用します。アップグレードプロセスは、アプリケーションに対して可能な限り透過的に行われ、ビジネスには影響しません。

アップグレードの前に、TiUP クラスターは、各コンポーネントの構成ファイルが合理的であるかどうかをチェックします。その場合、コンポーネントはノードごとにアップグレードされます。そうでない場合、TiUP はエラーを報告して終了します。操作はノードによって異なります。

異なるノードの操作

PD ノードをアップグレードする
- まず、非リーダーノードをアップグレードします。
- すべての非リーダーノードがアップグレードされたら、リーダーノードをアップグレードします。
  - アップグレードツールは、リーダーをアップグレード済みのノードに移行するコマンドを PD に送信します。
  - リーダーの役割が別のノードに切り替えられたら、以前のリーダーノードをアップグレードします。
- アップグレード中に異常なノードが検出された場合、ツールはこのアップグレード操作を停止して終了します。原因を手動で分析し、問題を修正して、アップグレードを再度実行する必要があります。
TiKV ノードをアップグレードする
- まず、この TiKV ノードのリージョンリーダーを移行するスケジュール操作を PD に追加します。これにより、アップグレードプロセスがビジネスに影響を与えないようにします。
- リーダーが移行されたら、この TiKV ノードをアップグレードします。
- バージョンアップした TiKV が正常に起動したら、Leader のスケジューリングを解除します。
その他のサービスをアップグレードする
- サービスを正常に停止し、ノードを更新します。

アップグレードコマンド

upgrade コマンドのフラグは次のとおりです。

Usage:
  cluster upgrade <cluster-name> <version> [flags]

Flags:
      --force                  Force upgrade won't transfer leader
  -h, --help                   help for upgrade
      --transfer-timeout int   Timeout in seconds when transferring PD and TiKV store leaders (default 300)

Global Flags:
      --ssh string          (Experimental) The executor type. Optional values are 'builtin', 'system', and 'none'.
      --wait-timeout int  Timeout of waiting the operation
      --ssh-timeout int   Timeout in seconds to connect host via SSH, ignored for operations that don't need an SSH connection. (default 5)
  -y, --yes               Skip all confirmations and assumes 'yes'

たとえば、次のコマンドはクラスターを v6.3.0 にアップグレードします。

tiup cluster upgrade tidb-test v6.3.0

構成の更新

コンポーネント構成を動的に更新する場合、TiUP クラスターコンポーネントは各クラスターの現在の構成を保存します。この構成を編集するには、 tiup cluster edit-config <cluster-name>コマンドを実行します。例えば：

tiup cluster edit-config prod-cluster

TiUP クラスターは、vi エディターで構成ファイルを開きます。他のエディターを使用する場合は、 EDITOR環境変数を使用して、 export EDITOR=nanoなどのエディターをカスタマイズします。

ファイルを編集したら、変更を保存します。新しい構成をクラスターに適用するには、次のコマンドを実行します。

tiup cluster reload prod-cluster

このコマンドは、構成をターゲットマシンに送信し、クラスターを再起動して構成を有効にします。

ノート：
コンポーネントを監視する場合は、 tiup cluster edit-configコマンドを実行して構成をカスタマイズし、対応するインスタンスにカスタム構成パスを追加します。例えば：

---

grafana_servers:
  - host: 172.16.5.134
    dashboard_dir: /path/to/local/dashboards/dir

monitoring_servers:
  - host: 172.16.5.134
    rule_dir: /path/to/local/rules/dir

alertmanager_servers:
  - host: 172.16.5.134
    config_file: /path/to/local/alertmanager.yml

指定されたパスの下にあるファイルの内容と形式の要件は次のとおりです。

grafana_serversのdashboard_dirフィールドで指定されたフォルダーには、完全な*.jsonのファイルが含まれている必要があります。
monitoring_serversのrule_dirフィールドで指定されたフォルダーには、完全な*.rules.ymlのファイルが含まれている必要があります。
alertmanager_serversのconfig_file欄で指定するファイルの形式については、 Alertmanager 構成テンプレートを参照してください。

tiup reloadを実行すると、TiUP は最初にターゲットマシン内のすべての古い構成ファイルを削除してから、対応する構成を制御マシンからターゲットマシンの対応する構成ディレクトリにアップロードします。したがって、特定の構成ファイルを変更する場合は、すべての構成ファイル (未変更のものを含む) が同じディレクトリにあることを確認してください。たとえば、Grafana のtidb.jsonファイルを変更するには、最初に*.jsonのファイルすべてを Grafana のdashboardsディレクトリからローカルディレクトリにコピーする必要があります。そうしないと、他の JSON ファイルがターゲットマシンから失われます。

ノート：
grafana_serversのdashboard_dirフィールドを構成した場合、 tiup cluster renameコマンドを実行してクラスターの名前を変更した後、次の操作を完了する必要があります。
ローカルdashboardsディレクトリで、クラスター名を新しいクラスター名に変更します。
ローカルのdashboardsディレクトリで、 datasourceを新しいクラスター名に変更します。これは、 datasourceがクラスター名にちなんで命名されているためです。
tiup cluster reload -R grafanaコマンドを実行します。

コンポーネントの更新

通常のアップグレードでは、 upgradeコマンドを使用できます。ただし、デバッグなどの一部のシナリオでは、現在実行中のコンポーネントを一時パッケージに置き換える必要がある場合があります。これを実現するには、 patchコマンドを使用します。

tiup cluster patch --help

Replace the remote package with a specified package and restart the service

Usage:
  cluster patch <cluster-name> <package-path> [flags]

Flags:
  -h, --help                   help for patch
  -N, --node strings           Specify the nodes
      --overwrite              Use this package in the future scale-out operations
  -R, --role strings           Specify the role
      --transfer-timeout int   Timeout in seconds when transferring PD and TiKV store leaders (default 300)

Global Flags:
      --ssh string          (Experimental) The executor type. Optional values are 'builtin', 'system', and 'none'.
      --wait-timeout int  Timeout of waiting the operation
      --ssh-timeout int   Timeout in seconds to connect host via SSH, ignored for operations that don't need an SSH connection. (default 5)
  -y, --yes               Skip all confirmations and assumes 'yes'

TiDB ホットフィックスパッケージが/tmp/tidb-hotfix.tar.gzにあり、クラスター内のすべての TiDB パッケージを置き換えたい場合は、次のコマンドを実行します。

tiup cluster patch test-cluster /tmp/tidb-hotfix.tar.gz -R tidb

クラスター内の 1 つの TiDB パッケージのみを置き換えることもできます。

tiup cluster patch test-cluster /tmp/tidb-hotfix.tar.gz -N 172.16.4.5:4000

TiDB Ansible クラスターのインポート

ノート：
現在、TiSpark に対する TiUP クラスターのサポートはまだ実験的段階です。 TiSpark が有効になっている TiDB クラスターのインポートはサポートされていません。

TiUP がリリースされる前は、TiDB Ansible を使用して TiDB クラスターをデプロイすることがよくありました。 TiDB Ansible によってデプロイされたクラスターを TiUP が引き継ぐことができるようにするには、 importコマンドを使用します。

importコマンドの使用法は次のとおりです。

tiup cluster import --help

Import an exist TiDB cluster from TiDB-Ansible

Usage:
  cluster import [flags]

Flags:
  -d, --dir string         The path to TiDB-Ansible directory
  -h, --help               help for import
      --inventory string   The name of inventory file (default "inventory.ini")
      --no-backup          Don't backup ansible dir, useful when there're multiple inventory files
  -r, --rename NAME        Rename the imported cluster to NAME

Global Flags:
      --ssh string        (Experimental) The executor type. Optional values are 'builtin', 'system', and 'none'.
      --wait-timeout int  Timeout of waiting the operation
      --ssh-timeout int   Timeout in seconds to connect host via SSH, ignored for operations that don't need an SSH connection. (default 5)
  -y, --yes               Skip all confirmations and assumes 'yes'

次のコマンドのいずれかを使用して、TiDB Ansible クラスターをインポートできます。

cd tidb-ansible
tiup cluster import

tiup cluster import --dir=/path/to/tidb-ansible

操作ログをビュー

操作ログを表示するには、 auditコマンドを使用します。 auditコマンドの使用法は次のとおりです。

Usage:
  tiup cluster audit [audit-id] [flags]

Flags:
  -h, --help   help for audit

[audit-id]フラグが指定されていない場合、コマンドは実行されたコマンドのリストを表示します。例えば：

tiup cluster audit

Starting component `cluster`: /home/tidb/.tiup/components/cluster/v1.11.0/cluster audit
ID      Time                       Command
--      ----                       -------
4BLhr0  2022-09-30T13:25:09+08:00  /home/tidb/.tiup/components/cluster/v1.11.0/cluster deploy test v6.3.0 /tmp/topology.yaml
4BKWjF  2022-09-28T23:36:57+08:00  /home/tidb/.tiup/components/cluster/v1.11.0/cluster deploy test v6.3.0 /tmp/topology.yaml
4BKVwH  2022-09-28T23:02:08+08:00  /home/tidb/.tiup/components/cluster/v1.11.0/cluster deploy test v6.3.0 /tmp/topology.yaml
4BKKH1  2022-09-28T16:39:04+08:00  /home/tidb/.tiup/components/cluster/v1.11.0/cluster destroy test
4BKKDx  2022-09-28T16:36:57+08:00  /home/tidb/.tiup/components/cluster/v1.11.0/cluster deploy test v6.3.0 /tmp/topology.yaml

最初の列はaudit-idです。特定のコマンドの実行ログを表示するには、次のようにコマンドのaudit-idをフラグとして渡します。

tiup cluster audit 4BLhr0

TiDB クラスター内のホストでコマンドを実行する

TiDB クラスター内のホストでコマンドを実行するには、 execコマンドを使用します。 execコマンドの使用法は次のとおりです。

Usage:
  cluster exec <cluster-name> [flags]

Flags:
      --command string   the command run on cluster host (default "ls")
  -h, --help             help for exec
  -N, --node strings     Only exec on host with specified nodes
  -R, --role strings     Only exec on host with specified roles
      --sudo             use root permissions (default false)

Global Flags:
      --ssh-timeout int   Timeout in seconds to connect host via SSH, ignored for operations that don't need an SSH connection. (default 5)
  -y, --yes               Skip all confirmations and assumes 'yes'

たとえば、すべての TiDB ノードでls /tmpを実行するには、次のコマンドを実行します。

tiup cluster exec test-cluster --command='ls /tmp'

クラスタコントローラ

TiUP がリリースされる前は、 tidb-ctl 、 tikv-ctl 、 pd-ctl 、およびその他のツールを使用してクラスターを制御できます。ツールを簡単にダウンロードして使用できるようにするために、TiUP はツールをオールインワンコンポーネントctlに統合しています。

Usage:
  tiup ctl {tidb/pd/tikv/binlog/etcd} [flags]

Flags:
  -h, --help   help for tiup

このコマンドは、以前のツールのコマンドと対応する関係があります。

tidb-ctl [args] = tiup ctl tidb [args]
pd-ctl [args] = tiup ctl pd [args]
tikv-ctl [args] = tiup ctl tikv [args]
binlogctl [args] = tiup ctl bindlog [args]
etcdctl [args] = tiup ctl etcd [args]

たとえば、以前にpd-ctl -u http://127.0.0.1:2379 storeを実行してストアを表示した場合、TiUP で次のコマンドを実行できるようになりました。

tiup ctl pd -u http://127.0.0.1:2379 store

ターゲットマシンの環境チェック

checkコマンドで対象マシンの環境を一連のチェックを行い、チェック結果を出力することができます。 checkコマンドを実行することで、一般的な不合理な構成やサポートされていない状況を見つけることができます。コマンドフラグのリストは次のとおりです。

Usage:
  tiup cluster check <topology.yml | cluster-name> [flags]
Flags:
      --apply                  Try to fix failed checks
      --cluster                Check existing cluster, the input is a cluster name.
      --enable-cpu             Enable CPU thread count check
      --enable-disk            Enable disk IO (fio) check
      --enable-mem             Enable memory size check
  -h, --help                   help for check
  -i, --identity_file string   The path of the SSH identity file. If specified, public key authentication will be used.
  -p, --password               Use password of target hosts. If specified, password authentication will be used.
      --user string            The user name to login via SSH. The user must has root (or sudo) privilege.

デフォルトでは、このコマンドはデプロイ前に環境をチェックするために使用されます。 --clusterフラグを指定してモードを切り替えることで、既存のクラスターのターゲットマシンを確認することもできます。次に例を示します。

# check deployed servers before deployment
tiup cluster check topology.yml --user tidb -p
# check deployed servers of an existing cluster
tiup cluster check <cluster-name> --cluster

CPU スレッドカウントチェック、メモリサイズチェック、およびディスクパフォーマンスチェックは、デフォルトで無効になっています。本番環境では、最高のパフォーマンスを得るために、3 つのチェックを有効にし、合格することを確認することをお勧めします。

CPU: スレッド数が 16 以上の場合、チェックに合格します。
メモリ: 物理メモリの合計サイズが 32 GB 以上の場合、チェックに合格します。
ディスク: data_dirのパーティションでfioのテストを実行し、結果を記録します。

チェックの実行時に--applyフラグが指定されている場合、プログラムは失敗した項目を自動的に修復します。自動修復は、構成またはシステムパラメータを変更することによって調整できる一部の項目に限定されます。その他の未修理のアイテムは、実際の状況に応じて手動で処理する必要があります。

クラスターをデプロイする場合、環境チェックは必要ありません。本番環境では、デプロイ前に環境チェックを実行し、すべてのチェック項目に合格することをお勧めします。すべてのチェック項目に合格しない場合、クラスタは正常にデプロイおよび実行されますが、最高のパフォーマンスが得られない可能性があります。

システムのネイティブ SSH クライアントを使用してクラスターに接続する

クラスタマシンで実行される上記のすべての操作は、TiUP に組み込まれている SSH クライアントを使用してクラスタに接続し、コマンドを実行します。ただし、シナリオによっては、制御マシンシステムにネイティブな SSH クライアントを使用して、このようなクラスター操作を実行する必要がある場合もあります。例えば：

認証に SSH プラグインを使用するには
カスタマイズされた SSH クライアントを使用するには

次に、 --ssh=systemコマンドラインフラグを使用して、システムネイティブのコマンドラインツールを有効にできます。

クラスターをデプロイする: tiup cluster deploy <cluster-name> <version> <topo> --ssh=system
クラスターを開始する: tiup cluster start <cluster-name> --ssh=system
クラスターのアップグレード: tiup cluster upgrade ... --ssh=system

上記のすべてのクラスター操作コマンドに--ssh=systemを追加して、システムのネイティブ SSH クライアントを使用できます。

すべてのコマンドでこのようなフラグを追加することを避けるために、 TIUP_NATIVE_SSHシステム変数を使用して、ローカル SSH クライアントを使用するかどうかを指定できます。

export TIUP_NATIVE_SSH=true
# or
export TIUP_NATIVE_SSH=1
# or
export TIUP_NATIVE_SSH=enable

この環境変数と--sshを同時に指定すると、 --sshが優先されます。

ノート：
クラスター展開のプロセス中に、接続にパスワードを使用する必要がある場合 ( -p ) またはpassphraseがキーファイルに構成されている場合は、制御マシンにsshpassがインストールされていることを確認する必要があります。それ以外の場合、タイムアウトエラーが報告されます。

制御マシンの移行と TiUP データのバックアップ

TiUP データは、ユーザーのホームディレクトリの.tiupディレクトリに格納されます。コントロールマシンを移行するには、次の手順を実行して、 .tiupディレクトリを対応するターゲットマシンにコピーします。

元のマシンのホームディレクトリでtar czvf tiup.tar.gz .tiupを実行します。
tiup.tar.gzをターゲットマシンのホームディレクトリにコピーします。
ターゲットマシンのホームディレクトリでtar xzvf tiup.tar.gzを実行します。
.tiupディレクトリをPATH環境変数に追加します。
bashを使用し、 tidbのユーザーの場合は、 ~/.bashrcでexport PATH=/home/tidb/.tiup/bin:$PATHを追加してsource ~/.bashrcを実行できます。次に、使用するシェルとユーザーに応じて、対応する調整を行います。

ノート：
制御マシンのディスク破損などの異常による TiUP データの消失を防ぐため、 .tiupディレクトリを定期的にバックアップすることをお勧めします。