From d9ad24a5dc3f17f373c237a16fb67bc802b3f771 Mon Sep 17 00:00:00 2001 From: Tao Date: Fri, 8 Dec 2023 13:45:40 +0100 Subject: [PATCH] add and enhance documentation --- README.md | 102 +++++-------------------- docs/README.md | 24 +++--- docs/development/README.md | 90 ---------------------- docs/development/add_new_subcommand.md | 33 ++++++++ docs/development/install.md | 46 +++++++++++ docs/development/usage.md | 84 ++++++++++++++++++++ 6 files changed, 191 insertions(+), 188 deletions(-) delete mode 100644 docs/development/README.md create mode 100644 docs/development/add_new_subcommand.md create mode 100644 docs/development/install.md create mode 100644 docs/development/usage.md diff --git a/README.md b/README.md index d3f3359..963873a 100644 --- a/README.md +++ b/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). -
- -## 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 +IronCore Logo -```shell -make install -``` - -For more details about developing refer to documentation folder [docs](/docs/development/README.md) -
- -## 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 -``` -
+# 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 //.[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 -
+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. diff --git a/docs/README.md b/docs/README.md index a704692..eb57186 100644 --- a/docs/README.md +++ b/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/) \ No newline at end of file +## Development +* [Generate command-line tree](./development/add_new_subcommand.md) +* [Add new subcommands](./development/add_new_subcommand.md) diff --git a/docs/development/README.md b/docs/development/README.md deleted file mode 100644 index a4a90fc..0000000 --- a/docs/development/README.md +++ /dev/null @@ -1,90 +0,0 @@ -# dpservice-cli development guide - -This page is intended as a general overview for all development-oriented topics. -[Cobra](https://github.com/spf13/cobra) framework is used for generating and handling commands in this project. -
- - -## 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 - -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 -``` -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 \** flag: -```bash -./bin/dpservice-cli --address [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 //.[json|yaml] -``` -Filename, directory, or URL can be used. -One file can contain multiple objects of any kind. -
- - -## Adding new type - -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 \Kind variable -- Create new [create|get|list|delete]\.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 \ 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 \ to DefaultScheme in [/dpdk/api/register.go](/dpdk/api/register.go) -- Add new \Key structs and methods in [/dpdk/client/dynamic/dynamic.go](/dpdk/client/dynamic/dynamic.go) and add new \ 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 \ as table in [/renderer/renderer.go](/renderer/renderer.go) - - add new \ to ConvertToTable method - - implement function to show new \ -
- - -## gRPC - -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@[|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/). \ No newline at end of file diff --git a/docs/development/add_new_subcommand.md b/docs/development/add_new_subcommand.md new file mode 100644 index 0000000..3f7a276 --- /dev/null +++ b/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 \Kind variable +- Create new [create|get|list|delete]\.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 \ 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 \ to DefaultScheme in [/dpdk/api/register.go](/dpdk/api/register.go) +- Add new \Key structs and methods in [/dpdk/client/dynamic/dynamic.go](/dpdk/client/dynamic/dynamic.go) and add new \ 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 \ as table in [/renderer/renderer.go](/renderer/renderer.go) + - add new \ to ConvertToTable method + - implement function to show new \ diff --git a/docs/development/install.md b/docs/development/install.md new file mode 100644 index 0000000..a178899 --- /dev/null +++ b/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@[|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/). diff --git a/docs/development/usage.md b/docs/development/usage.md new file mode 100644 index 0000000..263cf80 --- /dev/null +++ b/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 \** flag: +```bash +./bin/dpservice-cli --address [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 //.[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 //.[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).