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 <[email protected]> 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:
