Add and enhance documentation

README.md

@@ -1,91 +1,27 @@
-# dpservice-cli
-
-Command-line tool for debugging over gRPC for [dpservice](https://github.com/ironcore-dev/dpservice).
-
-This tool connects directly to a running dp-service and communicates with it (orchestrates it).
-<br />
-
-## Installation and developing
-
-To build the CLI binary, run
-
-```shell
-make build
-```
-
-This will build the binary at `bin/dpservice-cli`.
-
-To install it on a system where `GOBIN` is part of the `PATH`,
-run
+<img src="https://github.com/ironcore-dev/ironcore/blob/main/docs/assets/logo.svg" alt="IronCore Logo" width="200" />
 
-```shell
-make install
-```
-
-For more details about developing refer to documentation folder [docs](/docs/development/README.md)
-<br />
-
-## Autocompletion
-
-To generate autocompletion use:
-
-```shell
-dpservice-cli completion [bash|zsh|fish|powershell]
-```
-
-Or use -h to get more info and examples for specific shell:
-
-```shell
-dpservice-cli completion -h
-```
-<br />
+# dpservice-cli
 
-## Usage
+[![REUSE status](https://api.reuse.software/badge/github.com/ironcore-dev/dpservice-cli)](https://api.reuse.software/info/github.com/ironcore-dev/dpservice-cli)
+[![Go Report Card](https://goreportcard.com/badge/github.com/ironcore-dev/dpservice-cli)](https://goreportcard.com/report/github.com/ironcore-dev/dpservice-cli)
+[![GitHub License](https://img.shields.io/static/v1?label=License&message=Apache-2.0&color=blue)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://makeapullrequest.com)
 
-Each command or subcommand has help that can be viewed with -h or --help flag.
-```shell
-dpservice-cli --help
-```
-```bash
-Usage:
-  dpservice-cli [flags]
-  dpservice-cli [command]
 
-Available Commands:
-  add         Creates one of [interface prefix route virtualip loadbalancer lbprefix lbtarget nat neighbornat firewallrule]
-  completion  Generate completion script
-  delete      Deletes one of [interface prefix route virtualip loadbalancer lbprefix lbtarget nat neighbornat firewallrule]
-  get         Gets one of [interface virtualip loadbalancer lbtarget nat natinfo firewallrule]
-  help        Help about any command
-  init        Initial set up of the DPDK app
-  initialized Indicates if the DPDK app has been initialized already
-  list        Lists one of [firewallrules interfaces prefixes lbprefixes routes]
+dpservice-cli is the command-line tool that interacts with [dpservice](https://github.com/ironcore-dev/dpservice) via the gRPC interfaces. This tool connects directly to a running dp-service and communicates with it (orchestrates it).
 
-Flags:
-      --address string             dpservice address. (default "localhost:1337")
-      --connect-timeout duration   Timeout to connect to the dpservice. (default 4s)
-  -h, --help                       help for dpservice-cli
-  -o, --output string              Output format. [json|yaml|table|name]
-      --pretty                     Whether to render pretty output.
-  -w, --wide                       Whether to render more info in table output.
+## Use and develop dpservice-cli
+Please see the documentation in the [`/docs`](./docs) folder for more details.
 
-Use "dpservice-cli [command] --help" for more information about a command.
-```
----
-Add and Delete commands also support file input with **-f, --filename** flag:
-```bash
-dpservice-cli [add|delete] -f /<path>/<filename>.[json|yaml]
-```
-Filename, directory, or URL can be used.
-One file can contain multiple objects of any kind, example file:
-```bash
-{"kind":"VirtualIP","metadata":{"interfaceID":"vm1"},"spec":{"ip":"20.20.20.20"}}
-{"kind":"VirtualIP","metadata":{"interfaceID":"vm2"},"spec":{"ip":"20.20.20.21"}}
-{"kind":"Prefix","metadata":{"interfaceID":"vm3"},"spec":{"prefix":"20.20.20.0/24"}}
-{"kind":"LoadBalancer","metadata":{"id":"4"},"spec":{"vni":100,"lbVipIP":"10.20.30.40","lbports":[{"protocol":6,"port":443},{"protocol":17,"port":53}]}}
-{"kind":"LoadBalancerPrefix","metadata":{"interfaceID":"vm1"},"spec":{"prefix":"10.10.10.0/24"}}
-```
+## License
+Licensed 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
 
-All commands can be found in [docs](/docs/commands/dpservice-cli.md)
+    http://www.apache.org/licenses/LICENSE-2.0
 
-<br />
+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.

docs/README.md

@@ -1,17 +1,11 @@
-# Documentation - dpservice-cli
+# dpservice-cli documentation
 
-## All available commands can be found [here](/docs/commands/README.md).
+## Usage
+* [Compile and install](./development/install.md)
+* [Prerequisite](./development/usage.md)
+* [Start and command-line overview](./development/usage.md)
+* [Command-line guidance](./commands/)
 
-To generate current command tree add this at the start of main.go:
-```
-	err := doc.GenMarkdownTree(cmd.Command(), "/tmp/")
-	if err != nil {
-		log.Fatal(err)
-	}
-```
-run the program once and then remove this code.
-This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "/tmp/").
-
-Cobra command Markdown [docs](https://github.com/spf13/cobra/blob/main/doc/md_docs.md)
-
-## Development details can be found [here](/docs/development/)
+## Development
+* [Generate command-line tree](./development/add_new_subcommand.md)
+* [Add new subcommands](./development/add_new_subcommand.md)

docs/development/add_new_subcommand.md

@@ -0,0 +1,33 @@
+[Cobra](https://github.com/spf13/cobra) framework is used for generating and handling commands in this project.
+
+# Generate current command-line tree
+To generate current command tree add this at the start of main.go:
+```
+	err := doc.GenMarkdownTree(cmd.Command(), "/tmp/")
+	if err != nil {
+		log.Fatal(err)
+	}
+```
+run the program once and then remove this code.
+This will generate a whole series of files, one for each command in the tree, in the directory specified (in this case "/tmp/").
+
+**Note** Cobra command Markdown [docs](https://github.com/spf13/cobra/blob/main/doc/md_docs.md)
+
+
+# Steps to add a new subcommand
+Basic steps when implementing new type (similar to Interface, Route, LoadBalancer, ...):
+- Create new type in [/dpdk/api/types.go](/dpdk/api/types.go):
+    - create structs and methods
+	- at the bottom add new \<type\>Kind variable
+- Create new [create|get|list|delete]\<type\>.go file in /cmd/ folder and implement the logic
+- Add new command function to subcommands of matching parent command in /cmd/[create|get|list|delete].go
+- If needed add aliases for \<type\> at the bottom of [/cmd/common.go](/cmd/common.go)
+- Add new function to [/dpdk/api/client.go](/dpdk/api/client.go):
+    - add function to Client interface
+    - implement the function
+- Add new \<type\> to DefaultScheme in [/dpdk/api/register.go](/dpdk/api/register.go)
+- Add new \<type\>Key structs and methods in [/dpdk/client/dynamic/dynamic.go](/dpdk/client/dynamic/dynamic.go) and add new \<type\> to switch in Create and Delete methods
+- If needed create new conversion function(s) between dpdk struct and local struct in [/dpdk/api/conversion.go](/dpdk/api/conversion.go)
+- Add new function to show \<type\> as table in [/renderer/renderer.go](/renderer/renderer.go)
+    - add new \<type\> to ConvertToTable method
+    - implement function to show new \<type\>

docs/development/install.md

@@ -0,0 +1,46 @@
+# Compile and install
+
+Go version 1.18 or newer is needed. \"make\" tool is also needed to utilize the Makefile.  
+To run the dpservice-cli client build the binary first and then use it with commands and flags:
+```bash
+make build
+./bin/dpservice-cli -h
+```
+
+This will build the binary at `bin/dpservice-cli`.
+To install it on a system where `GOBIN` is part of the `PATH`,
+run
+
+```shell
+make install
+```
+
+# Autocompletion
+
+To generate autocompletion use:
+
+```shell
+dpservice-cli completion [bash|zsh|fish|powershell]
+```
+
+Or use -h to get more info and examples for specific shell:
+
+```shell
+dpservice-cli completion -h
+```
+
+# Dependency
+This client uses golang bindings from repo [dpservice-go](https://github.com/ironcore-dev/dpservice-go).
+
+Definition go files in [proto](https://github.com/ironcore-dev/dpservice-go/tree/main/proto) folder are auto-generated from [dpdk.proto](https://github.com/ironcore-dev/dpservice/blob/osc/main/proto/dpdk.proto) file in [dpservice](https://github.com/ironcore-dev/dpservice/) repo.
+
+In case of upgrade of dpservice-go, it is needed to pull the latest version:
+```
+go get github.com/ironcore-dev/dpservice-go@[<version>|latest]
+```
+In order to pull from private repository set the **GOPRIVATE** variable:
+```
+export GOPRIVATE=github.com/ironcore-dev/*
+```
+
+More info about gRPC can be found [here](https://grpc.io/docs/what-is-grpc/introduction/).

docs/development/usage.md

@@ -0,0 +1,84 @@
+# Prerequisite: running dpservice
+
+Before using dpservice-cli client, you need to have dpservice instance running.
+
+Please refer to this guide [dpservice](https://github.com/ironcore-dev/dpservice/blob/osc/grpc_docs/docs/development/building.md) on how to build dpservice from source.
+
+You can then run python script **/test/dp_service.py** that will start the dpservice with preloaded config.
+```bash
+sudo ./test/dp_service.py
+```
+If there is error about number of hugepages run this as root:
+```bash
+echo 2048 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages 
+```
+
+
+# Running dpservice-cli
+When you are running dpservice on the same VM you don't need to specify the address and defaults are used (localhost:1337).  
+If dpservice is running on different machine or you changed the default settings, use **--address \<string\>** flag:
+```bash
+./bin/dpservice-cli --address <IP:port> [command] [flags]
+```
+To change the output format of commands you can use **-o, --output** flag with one of **json | yaml | table | name**
+
+  -  **json**   - shows output in json (you can use **--pretty** flag to show formatted json)
+  -  **yaml**   - shows output in yaml
+  -  **table**  - shows output in predefined table format (you can use **-w, --wide** for more information)
+  -  **name**   - shows only short output with type/name
+
+Add and Delete commands also support file input with **-f, --filename** flag:
+```bash
+./bin/dpservice-cli [add|delete] -f /<path>/<filename>.[json|yaml]
+```
+Filename, directory, or URL can be used.
+One file can contain multiple objects of any kind.
+
+# Command-line guidance
+
+Each command or subcommand has help that can be viewed with -h or --help flag.
+```shell
+dpservice-cli --help
+```
+```bash
+Usage:
+  dpservice-cli [flags]
+  dpservice-cli [command]
+
+Available Commands:
+  add         Creates one of [interface prefix route virtualip loadbalancer lbprefix lbtarget nat neighbornat firewallrule]
+  completion  Generate completion script
+  delete      Deletes one of [interface prefix route virtualip loadbalancer lbprefix lbtarget nat neighbornat firewallrule]
+  get         Gets one of [interface virtualip loadbalancer lbtarget nat natinfo firewallrule]
+  help        Help about any command
+  init        Initial set up of the DPDK app
+  initialized Indicates if the DPDK app has been initialized already
+  list        Lists one of [firewallrules interfaces prefixes lbprefixes routes]
+
+Flags:
+      --address string             dpservice address. (default "localhost:1337")
+      --connect-timeout duration   Timeout to connect to the dpservice. (default 4s)
+  -h, --help                       help for dpservice-cli
+  -o, --output string              Output format. [json|yaml|table|name]
+      --pretty                     Whether to render pretty output.
+  -w, --wide                       Whether to render more info in table output.
+
+Use "dpservice-cli [command] --help" for more information about a command.
+```
+---
+Add and Delete commands also support file input with **-f, --filename** flag:
+```bash
+dpservice-cli [add|delete] -f /<path>/<filename>.[json|yaml]
+```
+Filename, directory, or URL can be used.
+One file can contain multiple objects of any kind, example file:
+```bash
+{"kind":"VirtualIP","metadata":{"interfaceID":"vm1"},"spec":{"ip":"20.20.20.20"}}
+{"kind":"VirtualIP","metadata":{"interfaceID":"vm2"},"spec":{"ip":"20.20.20.21"}}
+{"kind":"Prefix","metadata":{"interfaceID":"vm3"},"spec":{"prefix":"20.20.20.0/24"}}
+{"kind":"LoadBalancer","metadata":{"id":"4"},"spec":{"vni":100,"lbVipIP":"10.20.30.40","lbports":[{"protocol":6,"port":443},{"protocol":17,"port":53}]}}
+{"kind":"LoadBalancerPrefix","metadata":{"interfaceID":"vm1"},"spec":{"prefix":"10.10.10.0/24"}}
+```
+
+**Note**
+All available commands can be found [here](/docs/commands/README.md).