diff --git a/README.md b/README.md index 8108f6d..162121f 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,13 @@ [![asciicast](https://asciinema.org/a/625808.svg)](https://asciinema.org/a/625808) +## Motivation + +I created `buoy` because I do a lot of work on Kubernetes controllers. When I am making changes, I often find myself typing out a bunch of the same `kubectl ...` commands and switching between them. +Some of those commands are blocking (i.e `kubectl get logs -f ...`) and to keep them running while running other commands required opening a new terminal window and more typing. +Since I was running pretty repetitive commands I thought there had to be a better solution. I looked through existing CLI tooling around this space, but none had a simple interface that followed the pattern of +"define what you want to see and I'll show it to you". Thus `buoy` was created to fill this gap (and save me some time while delaying the inevitable arthritis). + ## Quickstart - Clone the repository: diff --git a/docs/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..dcd6e3d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,69 @@ +# buoy + +`buoy` is a declarative TUI dashboard for Kubernetes. You define your dashboard in a JSON file and it will fetch the information from your Kubernetes cluster and build a dashboard for viewing the requested content right in your terminal window. + +!> This project is in the extremely early stages of development and is a hobby project. Use at your own risk + +[![asciicast](https://asciinema.org/a/625808.svg)](https://asciinema.org/a/625808) + +## Motivation + +I created `buoy` because I do a lot of work on Kubernetes controllers. When I am making changes, I often find myself typing out a bunch of the same `kubectl ...` commands and switching between them. +Some of those commands are blocking (i.e `kubectl get logs -f ...`) and to keep them running while running other commands required opening a new terminal window and more typing. +Since I was running pretty repetitive commands I thought there had to be a better solution. I looked through existing CLI tooling around this space, but none had a simple interface that followed the pattern of +"define what you want to see and I'll show it to you". Thus `buoy` was created to fill this gap (and save me some time while delaying the inevitable arthritis). + +## Quickstart + +- Clone the repository: +``` +git clone https://github.com/everettraven/buoy.git +``` + +- `cd` into the cloned repository: +``` +cd buoy +``` + +- Build the `buoy` binary: +``` +make build +``` + +_OR_ + +``` +go build -o buoy main.go +``` + +- Create a KinD cluster: +``` +kind create cluster +``` + +- Run `buoy` using the `test.json` file: +``` +./buoy test.json +``` + +The `test.json` file contains samples for each of the different panel types that `buoy` currently supports. As this is a hobby project very early in the development cycle there are some limitations and things are bound to not work as expected. + +`test.yaml` results in the exact same dashboard as `test.json` and exists to show YAML support. + +`buoy` uses https://github.com/tidwall/gjson for the path evaluation and extracting of values from resources. Please consult their documentation for valid path syntax. + +You can also specify a remote reference to a dashboard configuration file. It must be a valid URL and the response must be the raw YAML or JSON contents of the file. + +## Controls +- `ctrl+c`, `q`, `esc` will quit the program and exit the tui +- `tab` will switch the active tab to the one to the right of the currently active tab +- `shift+tab` will switch the active tab to the one to the left of the currently active tab +- up and down arrow keys and mouse scroll will move up and down in the active tab +- For tables you can use the left and right arrows to scroll horizontally + + +## Contributing + +While this is a hobby project and in the early development stages, I'm more than happy to accept contributions. If you use `buoy` and find some problems or have some ideas for features/improvements, file an issue. If you want to contribute code, feel free to pick up any unassigned issues and create a pull request. + +Since this is a hobby project responses to issues and/or pull requests are likely to be slow. diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 0000000..595246d --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,6 @@ + + +- [Introduction](/) +- Panels + - [Table](panels/table.md) + diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..cb5d2c4 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,33 @@ + + + + + + Document + + + + + + + +
+ + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/panels/item.md b/docs/panels/item.md new file mode 100644 index 0000000..a04ad3e --- /dev/null +++ b/docs/panels/item.md @@ -0,0 +1,50 @@ +# Item + +The `item` panel is useful when you want to view the full YAML output of a particular resource. Typically this is useful when you want +to watch for any changes to this specific object. + +## Example + +For this example, we want to keep an eye on a `Deployment` named `foo` in the `default` namespace + + + +#### **JSON** +```json +{ + "panels": [ + { + "name": "Foo Deployment", + "group": "apps", + "version": "v1", + "kind": "Deployment", + "type": "item", + "key": { + "namespace": "default", + "name": "foo" + } + } + ] +} +``` + +#### **YAML** +```yaml +panels: + - name: Foo Deployment + group: apps + version: v1 + kind: Deployment + type: item + key: + namespace: default + name: foo +``` + + + +## Controls + +- Up and down arrow keys for navigating the viewport +- Page Up and Page Down for jumping up and down in the viewport +- `v` to toggle viewing the full YAML of the selected resource \ No newline at end of file diff --git a/docs/panels/logs.md b/docs/panels/logs.md new file mode 100644 index 0000000..b2dd03a --- /dev/null +++ b/docs/panels/logs.md @@ -0,0 +1 @@ +# Logs \ No newline at end of file diff --git a/docs/panels/table.md b/docs/panels/table.md new file mode 100644 index 0000000..6e26936 --- /dev/null +++ b/docs/panels/table.md @@ -0,0 +1,76 @@ +# Table + +The `table` panel is useful when you want to view a set of data in a structured format. For example, a good use case would be if +you wanted to view all the `Pod`s in a namespace. + +## Example + +For brevity, we will show an example of viewing all the `Pod`s in the `default` namespace. In this example, the information we want to know is: +- Name +- Labels +- Phase +- Containers + + + +#### **JSON** +```json +{ + "panels": [ + { + "name": "All Pods", + "group": "", + "version": "v1", + "kind": "Pod", + "type": "table", + "namespace": "default", + "columns": [ + { + "header": "Name", + "path": "metadata.name" + }, + { + "header": "Labels", + "path": "metadata.labels" + }, + { + "header": "Phase", + "path": "status.phase" + }, + { + "header": "Containers", + "path": "spec.containers.#.name" + } + ] + } + ] +} +``` + +#### **YAML** +```yaml +panels: + - name: All Pods + group: "" + version: v1 + kind: Pod + type: table + namespace: default + columns: + - header: Name + path: metadata.name + - header: Labels + path: metadata.labels + - header: Phase + path: status.phase + - header: Containers + path: spec.containers.#.name +``` + + + +## Controls + +- Up and down arrow keys for selecting rows +- Left and right arrow keys for scrolling rows horizontally +- `v` to toggle viewing the full YAML of the selected resource \ No newline at end of file