feat: Update default cli output configuration (#1184)

Adapt default cli configuration for the resources output. Add some
documentation on how this can be used.

Author: gtema

.github/workflows/mdbook.yml

@@ -29,7 +29,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     env:
-      MDBOOK_VERSION: 0.4.40
+      MDBOOK_VERSION: 0.4.48
     steps:
       - name: Harden Runner
         uses: step-security/harden-runner@0634a2670c59f64b4a01f0f96f84700a4088b9f0 # v2.12.0

README.md

@@ -25,6 +25,60 @@ Current focus of the project is at introducing Rust as a programming language
 into the ecosystem of OpenStack user facing tooling and provides SDK as well as
 CLI and TUI.
 
+## Components
+
+- `openstack_sdk` - SDK
+- `openstack_cli` - The new and shiny CLI for OpenStack
+- `openstack_tui` - Text (Terminal) User Interface
+- `openstack_types` - Type definitions for the API responses.
+- `doc` - Project documentation
+
+## OpenStackClient (NG)
+
+New approach for having a CLI for OpenStack using complied language offering
+blazing fast UX (it is the cloud to blame for being slow from now on, not the
+client).
+
+- Advanced authentication caching built-in and enabled by default
+
+- Status based resource coloring (resource list table rows are colored by the
+  resource state)
+
+- Output configuration (using `$XDG_CONFIG_DIR/osc/config.yaml` it is possible
+  to configure which fields should be returned when listing resources to enable
+  customization).
+
+- Strict microversion binding for resource modification requests (instead of
+  `openstack server create ...` which will not work with all microversions you
+  use `osc compute server create290` which will only work if server supports it.
+  It is similar to `openstack --os-compute-api-version X.Y`). It behaves the same
+  on every cloud independent of which microversion this cloud supports (as long
+  as it supports required microversion).
+
+- Can be wonderfully combined with jq for ultimate control of the necessary
+  data (`osc server list -o json | jq -r ".[].flavor.original_name"`)
+
+- Output everything what cloud sent (`osc compute server list -o json` to
+  return fields that we never even knew about, but the cloud sent us).
+
+- `osc api` command as an API wrapper allowing user to perform any direct API
+call specifying service type, url, method and payload. This can be used for
+example when certain resource is not currently implemented natively.
+
+
+## Terminal User Interface (TUI)
+
+Exploring the cloud resources using CLI is not something very comfortable. A
+terminal user interface imroves user experience when a quick look at currently
+present resources is required.
+
+openstack_tui (`ostui` as a binary name) is such TUI built upon
+[Ratatui](https://ratatui.rs) and inspired in functionality by
+[k9s](https://k9scli.io) that provides TUI for Kubernetes.
+
+![](doc/src/images/tui/ostui.gif)
+
+
 ## Design principles
 
 After long time maintaining OpenStack client facing tools it became clear that
@@ -74,16 +128,6 @@ normalization.
 - User is in full control of input and output. Microversion X.Y has a concrete
 body schema and with no faulty merges between different versions.
 
-## Components
-
-- `openstack_sdk` - SDK
-- `openstack_cli` - The new and shiny CLI for OpenStack
-- `openstack_tui` - Text (Terminal) User Interface
-- `structable_derive` - Helper crate for having Output in some way similar to
-  old OpenStackClient
-- `xtask` - Workflow helper
-- `doc` - Project documentation
-
 ## Trying out
 
 Any software is created to be used.
@@ -104,7 +148,6 @@ TUI can be installed similarly:
 curl --proto '=https' --tlsv1.2 -LsSf https://github.com/gtema/openstack/releases/latest/download/openstack_tui-installer.sh | sh
 ```
 
-
 ### Build locally
 Alternatively it is possible to compile project from sources. Since the project
 is a pure `Rust` it requires having a Rust compile suite.
@@ -160,18 +203,6 @@ and token caching enabled. Benchmarking is performed using
 API response. High amount of long API requests causes smaller performance
 difference.
 
-## Terminal User Interface (TUI)
-
-Exploring the cloud resources using CLI is not something very comfortable. A
-terminal user interface imroves user experience when a quick look at currently
-present resources is required.
-
-openstack_tui (`ostui` as a binary name) is such TUI built upon
-[Ratatui](https://ratatui.rs) and inspired in functionality by
-[k9s](https://k9scli.io) that provides TUI for Kubernetes.
-
-![](doc/src/images/tui/ostui.gif)
-
 ## Software security
 
 Security is being taken seriously. Every step of the development and release

doc/book.toml

@@ -5,13 +5,16 @@ multilingual = false
 src = "src"
 title = "OpenStack Client Tools"
 
+[rust]
+edition = "2024" 
+
 [build]
 build-dir = "html"
 create-missing = false
 
 [output.html.fold]
 enable = true
-level = 1
+level = 2
 
 [preprocessor.osc-cli]
 command = "cargo run -p xtask --bin osc-cli-md"

doc/src/SUMMARY.md

@@ -10,8 +10,16 @@
 # Components
 
 - [Rust SDK](./sdk.md)
+
+---
+
 - [OpenStackClient (OSC)](./cli.md)
-- [Text User Interface (TUI)](./tui.md)
+  - [Interface](cli/interface.md)
+  - [Configuration](cli/config.md)
+
+---
+
+- [Text User Interface (TUI)](tui.md)
   - [Connection](./tui/cloud-connect.md)
   - [Resource Selection](./tui/resource-select.md)
   - [Header](./tui/header.md)

doc/src/cli.md

@@ -1,5 +1 @@
 {{#include ../../openstack_cli/README.md}}
-
-# Command interface
-
-{{#cmd osc}}

doc/src/cli/config.md

@@ -0,0 +1,28 @@
+# CLI configuration
+
+It is possible to configure different aspects of the OpenStackClient (not the
+clouds connection credentials) using the configuration file
+(`$XDG_CONFIG_DIR/osc/config.yaml`). This enables user to configurate which
+columns should be returned when no corresponding run time arguments on a
+resource base.
+
+```yaml
+views:
+  compute.server:
+    # Listing compute servers will only return ID, NAME and IMAGE columns unless `-o wide` or
+    `-f XXX` parameters are being passed
+    fields: [id, name, image]
+  dns.zone/recordset:
+    # DNS zone recordsets are listed in the wide mode by default.
+    wide: true
+```
+
+The key of the `views` map is a resource key shared among all
+`openstack_rust`tools and is built in the following form:
+`<SERVICE-TYPE>.<RESOURCE_NAME>[/<SUBRESOURCE_NAME>]` where
+`<RESOURCE_NAME>[/<SUBRESOURCE_NAME>` is a url based naming (for designate
+`/zone/<ID>/recordset/<RS_ID>` would be names as zone.recordset and
+`/volumes/{volume_id}/metadata`would become volume.metadata. Please consult
+[Codegenerator
+metadata](https://opendev.org/openstack/codegenerator/src/branch/master/metadata)
+for known resource keys.

doc/src/cli/interface.md

@@ -0,0 +1,3 @@
+# Command interface
+
+{{#cmd osc}}