update tiup document (non-5.0-feature) (pingcap#5540) (pingcap#5592)

ti-srebot · May 8, 2021 · cf2dea2 · cf2dea2
1 parent 88e198c
commit cf2dea2
Show file tree

Hide file tree

Showing 26 changed files with 377 additions and 81 deletions.
diff --git a/tiup/tiup-cluster-topology-reference.md b/tiup/tiup-cluster-topology-reference.md
@@ -647,6 +647,10 @@ tispark_workers:
 - `storage_retention`: The retention time of the Prometheus monitoring data. The default value is `"15d"`.
 
 - `rule_dir`: Specifies a local directory that should contain complete `*.rules.yml` files. These files are transferred to the target machine during the initialization phase of the cluster configuration as the rules for Prometheus.
+- `remote_config`: Supports writing Prometheus data to the remote, or reading data from the remote. This field has two configurations:
+    - `remote_write`: See the Prometheus document [`<remote_write>`](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_write).
+    - `remote_read`: See the Prometheus document [`<remote_read>`](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#remote_read).
+- `external_alertmanagers`: If the `external_alertmanagers` field is configured, Prometheus alerts the configuration behavior to the Alertmanager that is outside the cluster. This field is an array, each element of which is an external Alertmanager and consists of the `host` and `web_port` fields.
 
 - `os`: The operating system of the machine specified in `host`. If this field is not specified, the default value is the `os` value in `global`.
 
@@ -670,6 +674,21 @@ A `monitoring_servers` configuration example is as follows:
 monitoring_servers:
   - host: 10.0.1.11
     rule_dir: /local/rule/dir
+    remote_config:
+      remote_write:
+      - queue_config:
+          batch_send_deadline: 5m
+          capacity: 100000
+          max_samples_per_send: 10000
+          max_shards: 300
+        url: http://127.0.0.1:8003/write
+      remote_read:
+      - url: http://127.0.0.1:8003/read
+      external_alertmanagers:
+      - host: 10.1.1.1
+        web_port: 9093
+      - host: 10.1.1.2
+        web_port: 9094
 ```
 
 ### `grafana_servers`

diff --git a/tiup/tiup-command-status.md b/tiup/tiup-command-status.md
@@ -8,7 +8,7 @@ The `tiup status` command is used to view the operation information of the compo
 
 > **Note:**
 >
-> You can only query the information of the following components:
+> You can only check the information of the following components:
 >
 > - Components that are still in operation
 > - Components that run through the tag specified by `tiup -T/--tag`

diff --git a/tiup/tiup-component-cluster-check.md b/tiup/tiup-component-cluster-check.md
@@ -154,6 +154,26 @@ tiup cluster check <topology.yml | cluster-name> [flags]
 > 
 > If the `tiup cluster check <cluster-name>` command is used, you must add the `--cluster` option: `tiup cluster check <cluster-name> --cluster`.
 
+### -N, --node
+
+- Specifies the nodes to be checked. The value of this option is a comma-separated list of node IDs. You can get the node IDs from the first column of the cluster status table returned by the [`tiup cluster display`](/tiup/tiup-component-cluster-display.md) command.
+- Data type: `STRINGS`
+- If this option is not specified in the command, all nodes are checked by default.
+
+> **Note:**
+>
+> If the `-R, --role` option is specified at the same time, only the service nodes that match both the specifications of `-N, --node` and `-R, --role` are checked.
+
+### -R, --role
+
+- Specifies the roles to be checked. The value of this option is a comma-separated list of node roles. You can get the roles of nodes from the second column of the cluster status table returned by the [`tiup cluster display`](/tiup/tiup-component-cluster-display.md) command.
+- Data type: `STRINGS`
+- If this option is not specified in the command, all roles are checked by default.
+
+> **Note:**
+>
+> If the `-N, --node` option is specified at the same time, only the service nodes that match both the specifications of `-N, --node` and `-R, --role` are checked.
+
 ### --enable-cpu
 
 - Enables the check of CPU core number.

diff --git a/tiup/tiup-component-cluster-disable.md b/tiup/tiup-component-cluster-disable.md
@@ -4,37 +4,37 @@ title: tiup cluster disable
 
 # tiup cluster disable
 
-The `tiup cluster disable` command is used to disable the auto-enabling after restarting the machine where the cluster service is located. This command executes the `systemctl disable <service>` on the specified node to disable the auto-enabling of the service.
+After restarting the machine on which the cluster service is located, the cluster service will be automatically enabled. To disable the auto-enabling of cluster service, you can use the `tiup cluster disable` command. This command executes `systemctl disable <service>` on the specified node to disable the auto-enabling of the service.
 
 ## Syntax
 
 ```shell
 tiup cluster disable <cluster-name> [flags]
 ```
 
-`<cluster-name>`: the cluster whose auto-enabling service is to be disabled.
+`<cluster-name>`: the cluster whose service auto-enabling is to be disabled.
 
 ## Options
 
 ### -N, --node
 
-- Specifies the nodes whose auto-enabling service is to be disabled. The value of this option is a comma-separated list of node IDs. The node ID is the first column of the [cluster status](/tiup/tiup-component-cluster-display.md) table.
-- Data type: `strings`
-- Default: `[]`, which means no node is selected.
+- Specifies the nodes whose service auto-enabling is to be disabled. The value of this option is a comma-separated list of node IDs. You can get the node IDs from the first column of the cluster status table returned by the [`tiup cluster display`](/tiup/tiup-component-cluster-display.md) command.
+- Data type: `STRINGS`
+- If this option is not specified in the command, the auto-enabling of all nodes is disabled by default.
 
 > **Note:**
 >
-> If the `-R, --role` option is specified at the same time, the auto-enabling of services in their intersection is disabled.
+> If the `-R, --role` option is specified at the same time, the auto-enabling of services that match both the specifications of `-N, --node` and `-R, --role` is disabled.
 
 ### -R, --role
 
-- Data type: `strings`
-- Default: `[]`, which means no role is selected.
-- Specifies the roles whose auto-enabling service is to be disabled. The value of this option is a comma-separated list of node roles. The role is the second column of the [cluster status](/tiup/tiup-component-cluster-display.md) table.
+- Specifies the roles whose service auto-enabling is to be disabled. The value of this option is a comma-separated list of node roles. You can get the roles of nodes from the second column of the cluster status table returned by the [`tiup cluster display`](/tiup/tiup-component-cluster-display.md) command.
+- Data type: `STRINGS`
+- If this option is not specified in the command, the auto-enabling of all roles is disabled by default.
 
 > **Note:**
 >
-> If the `-N, --node` option is specified at the same time, the auto-enabling of services in their intersection is disabled.
+> If the `-N, --node` option is specified at the same time, the auto-enabling of services that match both the specifications of `-N, --node` and `-R, --role` is disabled.
 
 ### -h, --help
 

diff --git a/tiup/tiup-component-cluster-display.md b/tiup/tiup-component-cluster-display.md
@@ -24,23 +24,23 @@ tiup cluster display <cluster-name> [flags]
 
 ### -N, --node
 
-- Specifies the node to query. If not specified, all nodes are queried. The value of this option is a comma-separated list of node IDs. The node ID is the first column of the [cluster status](/tiup/tiup-component-cluster-display.md) table.
-- Data type: `strings`
-- Default: `[]`, which means all nodes.
+- Specifies the node to display. If this option is not specified, all nodes are displayed. The value of this option is a comma-separated list of node IDs. If you are not sure about the ID of a node, you can skip this option in the command to show the IDs and status of all nodes in the output.
+- Data type: `STRINGS`
+- If this option is not specified in the command, all nodes are checked by default.
 
 > **Note:**
 >
-> If the `-R, --role` option is specified at the same time, then the service status in their intersection is queried.
+> If the `-R, --role` option is specified at the same time, only the service nodes that match both the specifications of `-N, --node` and `-R, --role` are checked.
 
-### -R, --role strings
+### -R, --role
 
-- Specifies the role to query. If not specified, all roles are queried. The value of this option is a comma-separated list of node roles. The role is the second column of the [cluster status](/tiup/tiup-component-cluster-display.md) table.
-- Data type: `strings`
-- Default: `[]`, which means all roles.
+- Specifies the role to display. If it is not specified, all roles are displayed. The value of this option is a comma-separated list of node roles. If you are not sure about the role deployed on a node, you can skip this option in the command to show the roles and status of all nodes in the output.
+- Data type: `STRINGS`
+- If this option is not specified in the command, all roles are displayed by default.
 
 > **Note:**
 >
-> If the `-N, --node` option is specified at the same time, then the service status in their intersection is queried.
+> If the `-N, --node` option is specified at the same time, only the service nodes that match both the specifications of `-N, --node` and `-R, --role` are displayed.
 
 ### -h, --help
 

diff --git a/tiup/tiup-component-cluster-enable.md b/tiup/tiup-component-cluster-enable.md
@@ -4,7 +4,7 @@ title: tiup cluster enable
 
 # tiup cluster enable
 
-The `tiup cluster enable` command is used to set the self-enabling of the cluster service after a machine restarts. To enable the self-enabling of the service, this command executes `systemctl enable <service>` at the specified node.
+The `tiup cluster enable` command is used to set the auto-enabling of the cluster service after a machine is restarted. This command enables the auto-enabling of the service by executing `systemctl enable <service>` at the specified node.
 
 > **Note:**
 >
@@ -16,35 +16,35 @@ The `tiup cluster enable` command is used to set the self-enabling of the cluste
 tiup cluster enable <cluster-name> [flags]
 ```
 
-`<cluster-name>`: the cluster whose auto-enabling service is to be enabled.
+`<cluster-name>`: the cluster whose service auto-enabling is to be enabled.
 
 ## Options
 
 ### -N, --node
 
-- Specifies the nodes whose auto-enabling service is to be enabled. The value of this option is a comma-separated list of node IDs. The node ID is the first column of the [cluster status](/tiup/tiup-component-cluster-display.md) table.
-- Data type: `strings`
-- Default: `[]`, which means no node is selected.
+- Specifies the nodes whose service auto-enabling is to be enabled. The value of this option is a comma-separated list of node IDs. You can get the node IDs from the first column of the cluster status table returned by the [`tiup cluster display`](/tiup/tiup-component-cluster-display.md) command.
+- Data type: `STRINGS`
+- If this option is not specified in the command, the auto-enabling of all nodes is enabled by default.
 
 > **Note:**
 >
-> If the `-R, --role` option is specified at the same time, the auto-enabling of services in their intersection is enabled.
+> If the `-R, --role` option is specified at the same time, the auto-enabling of services that match both the specifications of `-N, --node` and `-R, --role` is enabled.
 
 ### -R, --role
 
-- Specifies the roles whose auto-enabling service is to be enabled. The value of this option is a comma-separated list of node roles. The role is the second column of the [cluster status](/tiup/tiup-component-cluster-display.md) table.
-- Data type: `strings`
-- Default: `[]`, which means no role is selected.
+- Specifies the roles whose service auto-enabling is to be enabled. The value of this option is a comma-separated list of node roles. You can get the roles of nodes from the second column of the cluster status table returned by the [`tiup cluster display`](/tiup/tiup-component-cluster-display.md) command.
+- Data type: `STRINGS`
+- If this option is not specified in the command, the auto-enabling of all roles is enabled by default.
 
 > **Note:**
 >
-> If the `-N, --node` option is specified at the same time, the auto-enabling of services in their intersection is enabled.
+> If the `-N, --node` option is specified at the same time, the auto-enabling of services that match both the specifications of `-N, --node` and `-R, --role` is enabled.
 
 ### -h, --help
 
 - Prints the help information.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value.
 
 ## Output
 

diff --git a/tiup/tiup-component-cluster-patch.md b/tiup/tiup-component-cluster-patch.md
@@ -72,9 +72,9 @@ You need to pack the binary package required for this command in advance accordi
 >
 > If the option `-N, --node` is specified at the same time, TiUP then replaces service nodes that match both the requirements of `-N, --node` and `-R, --role`.
 
-## --offline
+### --offline
 
-- Declares that the current cluster is not running. When the option is specified, TiUP does not migrate the service leader to another node or restart the service, but only replaces the binary files of cluster components.
+- Declares that the current cluster is not running. When the option is specified, TiUP does not evict the service leader to another node or restart the service, but only replaces the binary files of cluster components.
 - Data type: `BOOLEAN`
 - This option is disabled by default with the `false` value. To enable this option, add this option to the command, and either pass the `true` value or do not pass any value.
 

diff --git a/tiup/tiup-component-cluster-reload.md b/tiup/tiup-component-cluster-reload.md
@@ -25,7 +25,7 @@ tiup cluster reload <cluster-name> [flags]
 ### --transfer-timeout
 
 - When restarting PD or TiKV, the leader of the restarted node is migrated to other nodes first, and the migration process takes some time. You can set the maximum wait time (in seconds) by setting `-transfer-timeout`. After the timeout, the service can be restarted directly without waiting.
-- Data type: `uint`
+- Data type: `UINT`
 - Default: 300
 
 > **Note:**
@@ -40,24 +40,24 @@ tiup cluster reload <cluster-name> [flags]
 
 ### -N, --node
 
-- Specifies the nodes to be restarted. If not specified, all nodes are restarted. The value of this option is a comma-separated list of node IDs. The node ID is the first column of the [cluster status](/tiup/tiup-component-cluster-display.md) table.
-- Data type: `strings`
-- Default: `[]`, which means all nodes are selected.
+- Specifies the nodes to be restarted. If not specified, all nodes are restarted. The value of this option is a comma-separated list of node IDs. You can get the node IDs from the first column of the cluster status table returned by the [`tiup cluster display`](/tiup/tiup-component-cluster-display.md) command.
+- Data type: `STRINGS`
+- If this option is not specified in the command, all nodes are selected by default.
 
 > **Note:**
 >
-> + If the `-R, --role` option is specified at the same time, then the service status in their intersection is restarted.
+> + If the `-R, --role` option is specified at the same time, only the service nodes that match both the specifications of `-N, --node` and `-R, --role` are restarted.
 > + If the `--skip-restart` option is specified, the `-N, --node` option is invalid.
 
 ### -R, --role
 
 - Specifies the roles to be restarted. If not specified, all roles are restarted. The value of this option is a comma-separated list of node roles. The role is the second column of the [cluster status](/tiup/tiup-component-cluster-display.md) table.
-- Data type: `strings`
-- Default: `[]`, which means all roles are selected.
+- Data type: `STRINGS`
+- If this option is not specified in the command, all roles are selected by default.
 
 > **Note:**
 >
-> 1. If the `-N, --node` option is specified at the same time, the services in their intersection is restarted.
+> 1. If the `-N, --node` option is specified at the same time, only the service nodes that match both the specifications of `-N, --node` and `-R, --role` are restarted.
 > 2. If the `--skip-restart` option is specified, the `-R, --role` option is invalid.
 
 ### --skip-restart

diff --git a/tiup/tiup-component-cluster-replay.md b/tiup/tiup-component-cluster-replay.md
@@ -0,0 +1,25 @@
+---
+title: tiup cluster replay
+---
+
+# tiup cluster replay
+
+When you perform a cluster operation such as upgrade or restart, the operation might fail due to cluster environment issues. If you re-perform the operation, you need to perform all the steps from the very beginning. If the cluster is large, re-performing these steps will take a long time. In this case, you can use the `tiup cluster replay` command to retry the failed commands and skip the successfully performed steps.
+
+## Syntax
+
+```shell
+tiup cluster replay <audit-id> [flags]
+```
+
+- `<audit-id>`: the `audit-id` of the command to be retried. You can view the historical commands and their `audit-id`s using the [`tiup cluster audit`](/tiup/tiup-component-cluster-audit.md) command.
+
+## Option
+
+### -h, --help
+
+Prints the help information.
+
+## Output
+
+The output of the command corresponding to `<audit-id>`.
diff --git a/tiup/tiup-component-cluster-start.md b/tiup/tiup-component-cluster-start.md
@@ -19,18 +19,18 @@ tiup cluster start <cluster-name> [flags]
 ### -N, --node
 
 - Specifies the nodes to be started. The value of this option is a comma-separated list of node IDs. You can get the node IDs from the first column of the [cluster status table](/tiup/tiup-component-cluster-display.md) returned by the `tiup cluster display` command.
-- Data type: `STRING`
-- Default: `[]`. If this option is not specified in the command, all nodes are started.
+- Data type: `STRINGS`
+- If this option is not specified in the command, all nodes are started by default.
 
 > **Note:**
 >
 > If the `-R, --role` option is specified at the same time, only the service nodes that match both the specifications of `-N, --node` and `-R, --role` are started.
 
 ### -R, --role
 
-- Specified the roles of nodes to be started. The value of this option is a comma-separated list of the roles of the nodes. You can get the roles of the nodes from the second column of the [cluster status table](/tiup/tiup-component-cluster-display.md) returned by the `tiup cluster display` command.
-- Data type: `STRING`
-- Default: `[]`.  If this option is not specified in the command, all roles are started.
+- Specifies the roles of nodes to be started. The value of this option is a comma-separated list of the roles of the nodes. You can get the roles of the nodes from the second column of the [cluster status table](/tiup/tiup-component-cluster-display.md) returned by the `tiup cluster display` command.
+- Data type: `STRINGS`
+- If this option is not specified in the command, all roles are started by default.
 
 > **Note:**
 >

diff --git a/tiup/tiup-component-cluster-stop.md b/tiup/tiup-component-cluster-stop.md
@@ -23,8 +23,8 @@ tiup cluster stop <cluster-name> [flags]
 ### -N, --node
 
 - Specifies the nodes to be stopped. The value of this option is a comma-separated list of node IDs. You can get the node IDs from the first column of the [cluster status table](/tiup/tiup-component-cluster-display.md) returned by the `tiup cluster display` command.
-- Data type: `STRING`
-- Default: []. If this option is not specified in the command, the command stops all the nodes.
+- Data type: `STRINGS`
+- If this option is not specified in the command, the command stops all the nodes by default.
 
 > **Note:**
 > 
@@ -33,8 +33,8 @@ tiup cluster stop <cluster-name> [flags]
 ### -R, --role
 
 - Specifies the roles of nodes to be stopped. The value of this option is a comma-separated list of the roles of the nodes. You can get the roles of the nodes from the second column of the [cluster status table](/tiup/tiup-component-cluster-display.md) returned by the `tiup cluster display` command.
-- Data type: `STRING`
-- Default: []. If this option is not specified in the command, the command stops all the roles.
+- Data type: `STRINGS`
+- If this option is not specified in the command, the command stops all the roles by default.
 
 > **Note:**
 >