Skip to content

Commit c338bf3

Browse files
VijayanBVijayanB
committed
Add RFC for odfe-cli
Created rfc for cli.
1 parent 77c1c94 commit c338bf3

File tree

5 files changed

+196
-3
lines changed

5 files changed

+196
-3
lines changed

‎CONTRIBUTING.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ reported the issue. Please try to include as much information as you can. Detail
2323
## Contributing via Pull Requests
2424
Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
2525

26-
1. You are working against the latest source on the *master* branch.
26+
1. You are working against the latest source on the *main* branch.
2727
2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
2828
3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
2929

‎NOTICE

+2-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
1+
Open Distro for Elasticsearch Command Line Interface
2+
Copyright 2019-2020 Amazon.com, Inc. or its affiliates. All Rights Reserved.

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
## My Project
1+
## ODFE Command Line Interface
22

33
TODO: Fill this README out!
44

‎docs/dev/images/design.png

52.5 KB
Loading

‎docs/dev/odfe-cli-rfc.md

+192
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# RFC: ODFE Command Line Interface
2+
3+
4+
5+
## 1. Overview
6+
7+
The ODFE Command Line Interface `(odfe-cli)` is an open source tool that enables
8+
users to manage their odfe clusters using through CLI or command-line-shell.
9+
Additionally, command line interface will allow users to configure and manage
10+
odfe plugins configurations like anomaly detections, alerting, sql, and
11+
access Elasticsearch features from command line with prominence on
12+
automation.
13+
14+
This cli enables users to start running commands that implement
15+
Kibana-equivalent functionality from the command prompt in their favorite
16+
terminal programs with a minimal configuration. As a programmer or an admin,
17+
users constantly want to perform ad-hoc operations that Kibana may not support.
18+
odfe-cli is better suited when the user wants to quickly combine a couple of commands
19+
to perform a task. These commands are powerful and concise. Since shell
20+
commands can be combined into script files, one can build sequence of commands to automate
21+
operations that they do often. This also provides direct access to the odfe cluster.
22+
The user can engage with different plugins using odfe-cli, and develop shell
23+
scripts to manage their cluster.
24+
25+
## 2. Tenets
26+
27+
1. Unified CLI for Open Distro for Elasticsearch.
28+
2. Available for installation on all platforms (Mac , Windows and Linux).
29+
3. odfe-cli will be distributed as Docker image just like any other image to enable possibilities for automation CI / CD.
30+
4. Provide profiles to handle multiple clusters with different user preferences such as Configure security credentials,
31+
default input/output file format at once and apply across multiple plugins / cluster.
32+
5. Flexibility to work with multiple odfe clusters.
33+
6. Scaling your workflow allows you to automate and replicate and make life .
34+
7. It also supports Elasticsearch core rest apis from [here](https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html)
35+
as commands eg: cat nodes, index create, cluster health, etc...
36+
8. Provide extra functions which are hard to implement on Kibana, like batch action, long running tasks, etc.
37+
38+
39+
40+
## 3. Design and Architecture
41+
42+
![](images/design.png)
43+
44+
### 3.1 Commands
45+
46+
Command is the central point of the application. Every interaction that cli
47+
supports will be represented as command. A command can have sub-commands,
48+
arguments and flags . Usually command represent an action, arguments are the
49+
things and flags are ways to modify the behavior of the commands.
50+
51+
odfe-cli will be the root command and it contains three type of sub-commands
52+
53+
* es core commands as index get, index create, cluster health, etc ...
54+
* plugins as commands like ad, monitor, sql, etc...
55+
* connections, which helps set-up profiles that will be used to interact with
56+
clusters.
57+
58+
### 3.2 Input Handler
59+
60+
Command supports input from both command line and as file. The file could be
61+
either json or yaml. Input handler is responsible to understand this input
62+
and convert it into an entity which can be passed to controller. This can be
63+
extended by supporting more file types like csv or text in the future.
64+
65+
### 3.3 Controller
66+
67+
Controller implements actual business logic for a command. Every plugin should
68+
have at least one controller. and command should depend only on its controller.
69+
A controller can depend on another controller and gateway.
70+
Also, Plugin controller will implement method for every command.
71+
For ex: AnomalyDetection Plugin will have a controller
72+
**AnomalyDetectorController** which implements methods like Create, Start,
73+
Stop, Delete, Update and so on. Also, AD Controller needs profile information
74+
like connection url, user name and password, hence, will depend on **ProfileController**
75+
which implements methods like Get, Create, Delete, etc...
76+
77+
### 3.4 Gateway
78+
79+
Gateway acts like an interface between application and cluster.
80+
Every plugin will have a gateway which implements the REST api provided by
81+
corresponding plugin. This Gateway is independent of commands and controller.
82+
Gateway requires implementing REST APIs provided by a plugin and return
83+
response as it is. Also, Gateway doesn't know about the type of cluster. It only uses
84+
Rest client with security details to communicate via REST protocol.
85+
86+
### 3.5 Model (Entities)
87+
88+
Model or Entities represents the request and response structure required to
89+
pass data to and from clusters and from commands to controller.
90+
91+
### 3.6 Output Handler
92+
93+
Every plugin has different styles to display output, for example, sql-cli
94+
might want to display output in different way than monitor plugin. Hence,
95+
individual commands can customize the output based on output handler
96+
before displaying it on the output peripheral.
97+
98+
### 3.8 Rest Client
99+
100+
This client provides a HTTP client interface with automatic retries and
101+
exponential backoff on top of net/http package. Since elasticsearch exposes
102+
REST API, every gateway uses this client to communicate to cluster.
103+
104+
105+
106+
## 4. Install & Set-up
107+
108+
ODFE Command line interface can be installed in following ways
109+
110+
1. Install `odfe-cli` Using Docker Image
111+
2. Install `odfe-cli` on Linux
112+
3. Install `odfe-cli` on macOS
113+
4. Install `odfe-cli` on Windows
114+
115+
## Synopsis
116+
117+
```
118+
odfe-cli [options] <command> <sub-command> [parameters]
119+
```
120+
121+
## options
122+
123+
*`--profile` [profile name]*
124+
Overrides commands default profile with given profile. Default profile name
125+
is `default` or, `$ODFE_PROFILE`
126+
127+
`--debug`
128+
displays more messages about CLI operations, especially for debugging
129+
purposes. If you like to report a github issue, share output generated
130+
with `--debug` when submitting it.
131+
132+
`--verbose`
133+
displays useful information about operations performed by commands.
134+
135+
`--input-format` (string)
136+
Overrides default formatting style for file input/output with given format.
137+
The available file formats are:
138+
139+
* json (default)
140+
* yaml
141+
142+
``--version`` (string)
143+
Display the version of this tool.
144+
145+
## Usage
146+
147+
```
148+
# Start detector job from Anomaly Detection
149+
$>odfe-cli ad start-detectors --id MuIjkjLEFWhuelQmmN-
150+
151+
# Sync monitors from remote to local from Alerting
152+
$>odfe-cli monitor sync
153+
154+
# Returns information about one or more indices
155+
$>odfe-cli es index get my-index-000001
156+
```
157+
158+
You can get help on the command line to see the supported plugins
159+
160+
```
161+
$>odfe-cli help
162+
```
163+
164+
the operations for plugins
165+
166+
```
167+
$>odfe-cli ad help
168+
```
169+
170+
the parameters for a plugins operation
171+
172+
```
173+
$>odfe-cli es cat help
174+
```
175+
176+
177+
178+
## Request for Comments:
179+
180+
We would like comments and feedback on the proposal for building ODFE CLI
181+
tool [here](https://github.com/opendistro-for-elasticsearch/es-cli/issues/2).
182+
Some specific questions we’re seeking feedback include
183+
184+
185+
* Do you prefer odfe-cli as root command name?
186+
* What function you want for the CLI tool? What’s your use case?
187+
* Would you like to see every feature available in kibana to be available in
188+
CLI or would you prefer only features which are difficult and impossible to
189+
do in UI to be available.
190+
* Do you prefer new release whenever a new odfe version releases, or an
191+
independent release based on cli features?
192+

0 commit comments

Comments
 (0)