tiup: add 3 docs mirror-init/mirror-rotate/cluster-patch (#5310) (#5341)

tiup/tiup-command-mirror-init.md

@@ -0,0 +1,44 @@
+---
+title: tiup mirror init
+---
+
+# tiup mirror init
+
+The command `tiup mirror init` is used to initialize an empty mirror. The initialized mirror does not contain any components or component owners. The command only generates the following files for the initialized mirror:
+
+```
++ <mirror-dir>                                  # Mirror's root directory
+|-- root.json                                   # Mirror's root certificate
+|-- 1.index.json                                # Component/user index
+|-- snapshot.json                               # Mirror's latest snapshot
+|-- timestamp.json                              # Mirror's latest timestamp
+|--+ keys                                       # Mirror's private key (can be moved to other locations)
+   |-- {hash1..hashN}-root.json                 # Private key of the root certificate
+   |-- {hash}-index.json                        # Private key of the indexes
+   |-- {hash}-snapshot.json                     # Private key of the snapshots
+   |-- {hash}-timestamp.json                    # Private key of the timestamps
+```
+
+For the specific usage and content format of the above files, refer to [TiUP Mirror Reference Guide](/tiup/tiup-mirror-reference.md).
+
+## Syntax
+
+```shell
+tiup mirror init <path> [flags]
+```
+
+`<path>` is used to specify a local directory where TiUP generates and stores mirror files. The local directory can be a relative path. If the specified directory already exists, it must be empty; if it does not exist, TiUP creates it automatically.
+
+## Options
+
+### -k, --key-dir
+
+- Specifies the directory where TiUP generates private key files. If the specified directory does not exist, TiUP automatically creates it.
+- Data type: `STRING`
+- If this option is not specified in the command, TiUP generates private key files in `{path}/keys` by default.
+
+### Outputs
+
+- If the command is executed successfully, there is no output.
+- If the specified `<path>` is not empty, TiUP reports the error `Error: the target path '%s' is not an empty directory`.
+- If the specified `<path>` is not a directory, TiUP reports the error `Error: fdopendir: not a directory`.

tiup/tiup-command-mirror-rotate.md

@@ -0,0 +1,60 @@
+---
+title: tiup mirror rotate
+---
+
+# tiup mirror rotate
+
+`root.json` is an important file in a TiUP mirror. It stores the public keys needed for the entire system and is the basis of the chain of trust in TiUP. It mainly contains the following parts:
+
+- Signatures of mirror administrators. For the official mirror, there are five signatures. For an initialized mirror, there are three signatures by default.
+- The public keys used to verify the following files:
+    - root.json
+    - index.json
+    - snapshot.json
+    - timestamp.json
+- Expiration date of `root.json`. For the official mirror, the expiration date is one year later than the creation date of `root.json`.
+
+For detailed description of TiUP mirror, see [TiUP Mirror Reference](/tiup/tiup-mirror-reference.md).
+
+You need to update `root.json` in the following cases:
+
+- Replace the key of the mirror.
+- Update the expiration date of certificate files.
+
+After the content of `root.json` is updated, the file must be re-signed by all administrators; otherwise, the client rejects the file. The update process is as follows:
+
+1. The user (client) updates the content of `root.json`.
+2. All administrators sign the new `root.json` file.
+3. tiup-server updates `snapshot.json` to record the version of the new `root.json` file.
+4. tiup-server signs the new `snapshot.json` file.
+5. tiup-server updates `timestamp.json` to record the hash value of the new `snapshot.json` file.
+6. tiup-server signs the new `timestamp.json` file.
+
+TiUP uses the command `tiup mirror rotate` to automate the above process.
+
+> **Note:**
+>
+> + For TiUP versions earlier than v1.3.0, running this command does not returns a correct new `root.json` file. See [#983](https://github.com/pingcap/tiup/issues/983).
+> + Before using this command, make sure that all TiUP clients are upgraded to v1.3.0 or a later version.
+
+## Syntax
+
+```shell
+tiup mirror rotate [flags]
+```
+
+After executing this command, TiUP starts an editor for the user to modify the file content to the target value, such as changing the value of the `expires` field to a later date. Then, TiUP changes the `version` field from `N` to `N+1` and saves the file. After the file is saved, TiUP starts a temporary HTTP server and waits for all mirror administrators to sign the file.
+
+For how mirror administrators sign files, refer to the `sign` command<!-- (/tiup/tiup-command-mirror-sign.md) -->.
+
+## Options
+
+### --addr
+
+- Specifies the listening address of the temporary server. You need to make sure that the address is accessible to other mirror administrators so that they can use the `sign` command<!-- (/tiup/tiup-command-mirror-sign.md) --> to sign the file.
+- Data type: `STRING`
+- If this option is not specified in the command, TiUP listens on `0.0.0.0:8080` by default.
+
+## Outputs
+
+The current signature status of each mirror administrator.

tiup/tiup-component-cluster-patch.md

@@ -0,0 +1,89 @@
+---
+title: tiup cluster patch
+---
+
+# tiup cluster patch
+
+If you need to dynamically replace the binaries of a service while the cluster is running (namely, keep the cluster available during the replacement process), you can use the `tiup cluster patch` command. After the command is executed, TiUP does the following things:
+
+- Uploads the binary package for replacement to the target machine.
+- If the target service is a storage service such as TiKV, TiFlash, or TiDB Binlog, TiUP first takes the related nodes offline via the API.
+- Stops the target service.
+- Unpacks the binary package and replace the service.
+- Starts the target service.
+
+## Syntax
+
+```shell
+tiup cluster patch <cluster-name> <package-path> [flags]
+```
+
+- `<cluster-name>`: The name of the cluster to be operated.
+- `<package-path>`: The path to the binary package used for replacement.
+
+### Preparation
+
+You need to pack the binary package required for this command in advance according to the following steps:
+
+- Determine the name `${component}` of the component to be replaced (tidb, tikv, pd...), the `${version}` of the component (v4.0.0, v4.0.1 ...), and the operating system `${os}` (`linux`) and platform `${arch}` on which the component runs.
+- Download the current component package using the command `wget https://tiup-mirrors.pingcap.com/${component}-${version}-${os}-${arch}.tar.gz -O /tmp/${component}-${version}-${os}-${arch}.tar.gz`.
+- Run `mkdir -p /tmp/package && cd /tmp/package` to create a temporary directory to pack files.
+- Run `tar xf /tmp/${component}-${version}-${os}-${arch}.tar.gz` to unpack the original binary package.
+- Run `find .` to view the file structure in the temporary package directory.
+- Copy the binary files or configuration files to the corresponding locations in the temporary directory.
+- Run `tar czf /tmp/${component}-hotfix-${os}-${arch}.tar.gz *` to pack the files in the temporary directory.
+- Finally, you can use `/tmp/${component}-hotfix-${os}-${arch}.tar.gz` as the `<package-path>` in the `tiup cluster patch` command.
+
+## Options
+
+### --overwrite
+
+- After you patch a certain component (such as TiDB or TiKV), when the tiup cluster scales out the component, TiUP uses the original component version by default. To use the version that you patch when the cluster scales out in the future, you need to specified the option `--overwrite` in the command.
+- 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.
+
+### --transfer-timeout
+
+- When restarting the PD or TiKV service, TiKV/PD first transfers the leader of the node to be restarted to another node. Because the transfer process takes some time, you can use the option `--transfer-timeout` to set the maximum waiting time (in seconds). After the timeout, TiUP directly restarts the service.
+- Data type: `UINT`
+- If this option is not specified, TiUP directly restarts the service after waiting for `300` seconds.
+
+> **Note:**
+>
+> If TiUP directly restarts the service after the timeout, the service performance might jitter.
+
+### -N, --node
+
+- Specifies nodes to be replaced. The value of this option is a comma-separated list of node IDs. You can get the node ID from the first 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, TiUP does not select any nodes to replace by default.
+
+> **Note:**
+>
+> If the option `-R, --role` is specified at the same time, TiUP then replaces service nodes that match both the requirements of `-N, --node` and `-R, --role`.
+
+### -R, --role
+
+- Specifies the roles to be replaced. The value of this option is a comma-separated list of the roles of the nodes. You can get the role deployed on a node 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, TiUP does not select any roles to replace by default.
+
+> **Note:**
+>
+> 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
+
+- 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.
+- 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.
+
+### -h, --help
+
+- Prints help information.
+- 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.
+
+## Outputs
+
+The execution log of the tiup-cluster.