bcb43183af
### What changes were proposed in this pull request? Fix the broken link. ### Why are the changes needed? Followup for https://github.com/apache/celeborn/pull/2779. The RESTful api docs was renamed from webapi.md to restapi.md in https://github.com/apache/celeborn/pull/2775. And due these two PRs were merged in sequence nearly, so I did not aware this change. ### Does this PR introduce _any_ user-facing change? No. ### How was this patch tested? <img width="1255" alt="image" src="https://github.com/user-attachments/assets/a09aecf8-6e7e-458b-871d-f8dd5a0ac6b2"> <img width="937" alt="image" src="https://github.com/user-attachments/assets/bcefeecf-7a24-4616-9f5e-f2a11f464769"> Closes #2828 from turboFei/ratis_docs_link. Authored-by: Wang, Fei <fwang12@ebay.com> Signed-off-by: mingji <fengmingxiao.fmx@alibaba-inc.com>
173 lines
6.9 KiB
Markdown
173 lines
6.9 KiB
Markdown
---
|
|
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
|
|
|
|
https://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.
|
|
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.
|
|
|
|
Since 0.6.0, the ratis [RESTful API](restapi.md) is supported, which is more convenient to operate the ratis service, see details in the swagger: `http://<CELEBORN_HOST>:<CELEBORN_PORT>/swagger/#/Ratis`.
|
|
|
|
> **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
|
|
|
|
Celeborn directly introduces the ratis-shell into the project, users don't need to set up ratis-shell env from ratis repo.
|
|
User can directly download the Celeborn source tarball from [Download](https://celeborn.apache.org/download) and
|
|
build the Celeborn according to [build_and_test](https://celeborn.apache.org/community/contributor_guide/build_and_test/)
|
|
or just download the pre-built binary tarball from [Download](https://celeborn.apache.org/download)
|
|
to get the binary package `apache-celeborn-<VERSION>-bin.tgz`.
|
|
|
|
After getting the binary package `apache-celeborn-<VERSION>-bin.tgz`:
|
|
```
|
|
$ tar -C <DST_DIR> -zxvf apache-celeborn-<VERSION>-bin.tgz
|
|
$ ln -s <DST_DIR>/apache-celeborn-<VERSION>-bin <DST_DIR>/celeborn
|
|
```
|
|
|
|
Export the following environment variable and add the bin directory to the `$PATH`.
|
|
```
|
|
$ export CELEBORN_HOME=<DST_DIR>/celeborn
|
|
$ 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]]
|
|
[local [raftMetaConf]]
|
|
```
|
|
|
|
## generic options
|
|
The `generic options` pass values for a given ratis-shell property.
|
|
It supports the following content:
|
|
`-D*`, `-X*`, `-agentlib*`, `-javaagent*`
|
|
|
|
```
|
|
$ celeborn-ratis sh -D<property=value> ...
|
|
```
|
|
|
|
**Note:**
|
|
|
|
Celeborn HA uses `NETTY` as the default RPC type, for details please refer to configuration `celeborn.master.ha.ratis.raft.rpc.type`. But Ratis uses `GRPC` as the default RPC type. So if the user wants to use Ratis shell to access Ratis cluster which uses `NETTY` RPC type, the generic option `-Draft.rpc.type=NETTY` should be set to change the RPC type of Ratis shell to Netty.
|
|
|
|
## 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>]
|
|
```
|
|
|
|
## local
|
|
The `local` command is used to process local operation, which no need to connect to ratis server.
|
|
It has the following subcommands:
|
|
`raftMetaConf`
|
|
|
|
### local raftMetaConf
|
|
Generate a new raft-meta.conf file based on original raft-meta.conf and new peers, which is used to move a raft node to a new node.
|
|
```
|
|
$ celeborn-ratis sh local raftMetaConf -peers <[P0_ID|]P0_HOST:P0_PORT,[P1_ID|]P1_HOST:P1_PORT,[P2_ID|]P2_HOST:P2_PORT> -path <PARENT_PATH_OF_RAFT_META_CONF>
|
|
```
|