[incubator-celeborn-website] 01/01: [CELEBORN-361] Add celeborn ratis-shell doc

[an...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

angerszhuuuu pushed a commit to branch CELEBORN-361
in repository https://gitbox.apache.org/repos/asf/incubator-celeborn-website.git

commit d0da419535f731aea6288e5853949ffb77e14ca9
Author: Angerszhuuuu <an...@gmail.com>
AuthorDate: Fri Mar 3 11:56:53 2023 +0800

    [CELEBORN-361] Add celeborn ratis-shell doc
---
 docs/user_guide/celeborn_ratis_shell.md | 154 ++++++++++++++++++++++++++++++++
 mkdocs.yml                              |   1 +
 2 files changed, 155 insertions(+)

diff --git a/docs/user_guide/celeborn_ratis_shell.md b/docs/user_guide/celeborn_ratis_shell.md
new file mode 100644
index 0000000..1339c9a
--- /dev/null
+++ b/docs/user_guide/celeborn_ratis_shell.md
@@ -0,0 +1,154 @@
+---
+license: |
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+---
+
+
+# Celeborn Ratis-shell
+
+[Ratis-shell](https://github.com/apache/ratis/blob/master/ratis-docs/src/site/markdown/cli.md) is the command line interface of Ratis.
+Since Celeborn uses Ratis to implement the HA function of the master, Celeborn directly introduces ratis-shell package into the project
+then it's convenient for Celeborn Admin to operate the master ratis service.
+
+> **Note**:
+> Ratis-shell is currently only **experimental**.
+> The compatibility story is not considered for the time being.
+
+## Availability
+|  Version  | Available in src tarball? | Available in bin tarball? |
+|:---------:| :-----------------------: |:-------------------------:|
+|  < 0.3.0  | No                        |            No             |
+| \>= 0.3.0 | Yes                       |            Yes            |
+
+## Setting up the Celeborn ratis-shell
+
+Since Celeborn directly introduce the ratis-shell into the project, users don't need to set up ratis-shell env from ratis repo.
+Usr can directly download the Celeborn source tarball from [Download](https://celeborn.apache.org/download/#security) and
+build the Celeborn accoriding to [build_and_test](https://celeborn.apache.org/community/contributor_guide/build_and_test/)
+or just down load the bin tarball from [Download](https://celeborn.apache.org/download/#security) to get the binary package `apache-celeborn-<VERSION>-bin.tgz`.
+
+After get the binary package `apache-celeborn-<VERSION>-bin.tgz`:
+```
+$ tar -C <DST_DIR> -zxvf apache-celeborn-<VERSION>-bin.tgz
+$ mv <DST_DIR>/apache-celeborn-<VERSION>-bin <DST_DIR>/celeborn
+```
+
+Export the `CELEBORN_HOME`, `CELEBORN_CONF_DIR` and `CELEBORN_LOG_DIR` environment variable and add the bin directory to the `$PATH`.
+```
+$ export CELEBORN_HOME=<DST_DIR>/celeborn
+$ export CELEBORN_CONF_DIR=$CELEBORN_HOME/conf
+$ export CELEBORN_LOG_DIR=$CELEBORN_HOME/logs
+$ export PATH=${CELEBORN_HOME}/bin:$PATH
+```
+
+The following command can be invoked in order to get the basic usage:
+
+```shell
+$ celeborn-ratis sh
+Usage: celeborn-ratis sh [generic options]
+         [election [transfer] [stepDown] [pause] [resume]]
+         [group [info] [list]]
+         [peer [add] [remove] [setPriority]]
+         [snapshot [create]]
+```
+
+## generic options
+The `generic options` pass values for a given ratis-shell property.
+It support the following content:
+`-D*`, `-X*`, `-agentlib*`, `-javaagent*`
+
+```
+$ celeborn-ratis sh -D<property=value> ...
+```
+
+## election
+The `election` command manages leader election.
+It has the following subcommands:
+`transfer`, `stepDown`, `pause`, `resume`
+
+### election transfer
+Transfer a group leader to the specified server.
+```
+$ celeborn-ratis sh election transfer -peers <P0_HOST:P0_PORT,P1_HOST:P1_PORT,P2_HOST:P2_PORT> -address <HOSTNAME:PORT> [-groupid <RAFT_GROUP_ID>]
+```
+
+### election stepDown
+Make a group leader of the given group step down its leadership.
+```
+$ celeborn-ratis sh election stepDown -peers <P0_HOST:P0_PORT,P1_HOST:P1_PORT,P2_HOST:P2_PORT> [-groupid <RAFT_GROUP_ID>]
+```
+
+### election pause
+Pause leader election at the specified server.
+Then, the specified server would not start a leader election.
+```
+$ celeborn-ratis sh election pause -peers <P0_HOST:P0_PORT,P1_HOST:P1_PORT,P2_HOST:P2_PORT> -address <HOSTNAME:PORT> [-groupid <RAFT_GROUP_ID>]
+```
+
+### election resume
+Resume leader election at the specified server.
+```
+$ celeborn-ratis sh election resume -peers <P0_HOST:P0_PORT,P1_HOST:P1_PORT,P2_HOST:P2_PORT> -address <HOSTNAME:PORT> [-groupid <RAFT_GROUP_ID>]
+```
+
+## group
+The `group` command manages ratis groups.
+It has the following subcommands:
+`info`, `list`
+
+### group info
+Display the information of a specific raft group.
+```
+$ celeborn-ratis sh group info -peers <P0_HOST:P0_PORT,P1_HOST:P1_PORT,P2_HOST:P2_PORT> [-groupid <RAFT_GROUP_ID>]
+```
+
+### group list
+Display the group information of a specific raft server
+```
+$ celeborn-ratis sh group list -peers <P0_HOST:P0_PORT,P1_HOST:P1_PORT,P2_HOST:P2_PORT> [-groupid <RAFT_GROUP_ID>]  <[-serverAddress <P0_HOST:P0_PORT>]|[-peerId <peerId0>]>
+```
+
+## peer
+The `peer` command manages ratis cluster peers.
+It has the following subcommands:
+`add`, `remove`, `setPriority`
+
+### peer add
+Add peers to a ratis group.
+```
+$ celeborn-ratis sh peer add -peers <P0_HOST:P0_PORT,P1_HOST:P1_PORT,P2_HOST:P2_PORT> [-groupid <RAFT_GROUP_ID>] -address <P4_HOST:P4_PORT,...,PN_HOST:PN_PORT>
+```
+
+### peer remove
+Remove peers to from a ratis group.
+```
+$ celeborn-ratis sh peer remove -peers <P0_HOST:P0_PORT,P1_HOST:P1_PORT,P2_HOST:P2_PORT> [-groupid <RAFT_GROUP_ID>] -address <P0_HOST:P0_PORT,...>
+```
+
+### peer setPriority
+Set priority to ratis peers.
+The priority of ratis peer can affect the leader election, the server with the highest priority will eventually become the leader of the cluster.
+```
+$ celeborn-ratis sh peer setPriority -peers <P0_HOST:P0_PORT,P1_HOST:P1_PORT,P2_HOST:P2_PORT> [-groupid <RAFT_GROUP_ID>] -addressPriority <P0_HOST:P0_PORT|PRIORITY>
+```
+## snapshot
+The `snapshot` command manages ratis snapshot.
+It has the following subcommands:
+`create`
+
+### snapshot create
+Trigger the specified server take snapshot.
+```
+$ celeborn-ratis sh snapshot create -peers <P0_HOST:P0_PORT,P1_HOST:P1_PORT,P2_HOST:P2_PORT> -peerId <peerId0> [-groupid <RAFT_GROUP_ID>]
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index ab1051f..83dd163 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -78,6 +78,7 @@ nav:
   - Download: download.md
   - User Guide:
       - Upgrade: user_guide/upgrade.md
+      - Ratis Shell: user_guide/celeborn_ratis_shell.md
   - Configuration:
       - configuration/index.md
   - Community: