https://github.com/sarub0b0/kubetui
An intuitive Terminal User Interface (TUI) tool for real-time monitoring and exploration of Kubernetes resources
https://github.com/sarub0b0/kubetui
kubernetes kubetui monitor ratatui rust terminal tui tui-rs
Last synced: 8 months ago
JSON representation
An intuitive Terminal User Interface (TUI) tool for real-time monitoring and exploration of Kubernetes resources
- Host: GitHub
- URL: https://github.com/sarub0b0/kubetui
- Owner: sarub0b0
- License: mit
- Created: 2021-02-17T00:58:11.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2025-10-19T04:54:05.000Z (8 months ago)
- Last Synced: 2025-10-19T11:47:36.876Z (8 months ago)
- Topics: kubernetes, kubetui, monitor, ratatui, rust, terminal, tui, tui-rs
- Language: Rust
- Homepage:
- Size: 30.3 MB
- Stars: 309
- Watchers: 2
- Forks: 8
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-cli-apps - kubetui - A TUI tool designed for monitoring Kubernetes resources. (<a name="devops"></a>DevOps)
- awesome-tuis - kubetui
- awesome-cli-apps-in-a-csv - kubetui - A TUI tool designed for monitoring Kubernetes resources. (<a name="devops"></a>DevOps)
- awesome-ratatui - kubetui - TUI for real-time monitoring of Kubernetes resources. (💻 Apps / 👨💻 System Administration)
README
# kubetui
[]()
[](https://github.com/sarub0b0/kubetui/actions/workflows/test.yml)
Kubetui is a terminal user interface (TUI) tool designed for monitoring Kubernetes resources.
It provides an easy-to-use interface for developers and operators to access important information about their applications and infrastructure.
Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Homebrew on macOS and Linux](#homebrew-on-macos-and-linux)
- [Pacman on Arch Linux](#pacman-on-arch-linux)
- [Scoop on Windows](#scoop-on-windows)
- [WinGet on Windows](#winget-on-windows)
- [Chocolatey on Windows](#chocolatey-on-windows)
- [openSUSE Tumbleweed](#opensuse-tumbleweed)
- [Using `cargo install`](#using-cargo-install)
- [Downloading the binary](#downloading-the-binary)
- [Usage](#usage)
- [Pod Column Customization](#pod-column-customization)
- [Define presets in config.yaml](#define-presets-in-configyaml)
- [Example config](#example-config)
- [Shell Completion](#shell-completion)
- [Custom Configuration](#custom-configuration)
- [Log Query](#log-query)
- [Usage Example](#usage-example)
- [Supported Queries](#supported-queries)
- [Query String Escaping](#query-string-escaping)
- [Key Bindings](#key-bindings)
- [General](#general)
- [Key Map](#key-map)
- [View Control](#view-control)
- [Text View](#text-view)
- [Search Mode](#search-mode)
- [Table View](#table-view)
- [Dialog](#dialog)
- [Input Form](#input-form)
- [Container Logs View](#container-logs-view)
- [Contributing](#contributing)
- [License](#license)
Demo slow version
## Features
Kubetui offers the following features to help you monitor and manage your Kubernetes resources:
- **Pods List and Container Logs**:
- View a list of pods and their container logs.
- JSON logs display mode switching: toggle between pretty print and single-line display using the f or p keys.
- **Customizable pod columns (via CLI flags or config presets)**: Use `--pod-columns` or `--pod-columns-preset` to control which columns appear in the pod list view. Also supports dynamic selection at runtime.
- **Dynamic column selection**: You can now customize pod columns at runtime using a column selection dialog. Press t while the pod table is focused to open the dialog. Selected columns are immediately applied.
- **ConfigMap and Secret Watching**: Monitor ConfigMaps and secrets, and decode their data.
- **Network-related Resources**: Explore a list of network-related resources and their descriptions.
- **Events Watching**: Stay updated with a real-time view of Kubernetes events.
- **Specific Resources Watching (List / YAML)**: View specific resources in list or YAML format.
- **Namespace Multiple Selections**: Select and view multiple namespaces simultaneously.
- **Context Selection**: Change the Kubernetes context you want to operate on.
- **Clipboard Support (Text Copy)**: Copy text conveniently using mouse actions.
- **Mouse Event Support**: Leverage mouse events for a smoother user experience.
- **Search Functionality**: Easily search for specific keywords within the interface.
- **Item Filtering**: Filter items based on multiple keywords separated by spaces.
- **(beta) Customizable UI Appearance**: Modify the appearance of the UI, including border styles, colors, and text attributes.
Overall, kubetui is a powerful tool designed to provide a safe and efficient way to access and monitor your Kubernetes resources. With its user-friendly interface and comprehensive features, it simplifies the process of managing your applications and infrastructure.
## Installation
[](https://repology.org/project/kubetui/versions)
To install kubetui, you can use the following methods:
### [Homebrew](https://brew.sh/) on macOS and Linux
Kubetui is available on homebrew, the package manager for macOS and Linux. Install it by running the following command:
```shell
brew install kubetui
```
### [Pacman](https://wiki.archlinux.org/title/pacman) on Arch Linux
Kubetui is available in the [official repositories](https://archlinux.org/packages/extra/x86_64/kubetui/). Install it by running the following command:
```shell
pacman -S kubetui
```
### [Scoop](https://scoop.sh/) on Windows
If you are using Windows with scoop, you can add the necessary buckets and install kubetui with the following commands:
```shell
# Add the 'extras' bucket for vcredist2022
scoop bucket add extras
scoop bucket add https://github.com/sarub0b0/scoop-bucket
scoop install /kubetui
```
### [WinGet](https://github.com/microsoft/winget-cli) on Windows
If you prefer using winget, the Windows package manager, you can install kubetui with the following command:
```shell
winget install kubetui
```
### [Chocolatey](https://community.chocolatey.org/packages/kubetui/) on Windows
Kubetui is available on Chocolatey, the package manager for Windows. Install it by running the following command:
```shell
choco install kubetui
```
### openSUSE Tumbleweed
For openSUSE Tumbleweed, you can install kubetui using the `zypper` package manager. Run the following command to install:
```shell
zypper install kubetui
```
### Using `cargo install`
Kubetui is available on [crates.io](https://crates.io/crates/kubetui), the official Rust package registry. Install it by running the following command:
```shell
cargo install kubetui
```
Make sure you have [Rust](https://www.rust-lang.org/tools/install) and [Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) installed before running the command.
### Downloading the binary
Alternatively, you can download the precompiled binary from the [GitHub Release page](https://github.com/sarub0b0/kubetui/releases) that matches your operating system. Once downloaded, you can run the binary directly without any additional installation steps.
Choose the method that suits your needs and preferences.
## Usage
```sh
kubetui
```
```sh
$ kubetui -h
An intuitive Terminal User Interface (TUI) tool for real-time monitoring and exploration of Kubernetes resources.
Usage: kubetui [OPTIONS] [COMMAND]
Commands:
completion Generate completion script
Options:
-h, --help Print help
-V, --version Print version
-A, --all-namespaces[=] Select all namespaces [default: false]
-c, --context Context
-C, --kubeconfig kubeconfig path
--config-file Config file path
-l, --logging Logging
-n, --namespaces Namespaces (e.g. -n val1,val2,val3 | -n val1 -n val2 -n val3)
--pod-columns Comma-separated list of columns to show in pod table (e.g. name,status,ip). Use "full" to show all available columns
--pod-columns-preset Preset name for pod columns (e.g. "default", "full"). If both are specified, `--pod-columns` overrides this
-s, --split-direction Window split direction [default: v]
```
### Pod Column Customization
Use `--pod-columns` to customize the columns displayed in the pod table.
- Specify columns using a comma-separated list:
`--pod-columns=ready,status,age`
- Use `full` to show all available columns:
`--pod-columns=full`
Notes:
- The `Name` column is always included even if not specified.
- The `full` keyword cannot be combined with other columns.
You can also customize columns dynamically at runtime:
- Press t in the pod view to open the column selection dialog.
- Use Space/Enter to toggle visibility and J/K to reorder columns.
- Required columns like `NAME` are always enabled and fixed.
#### Define presets in config.yaml
You can define reusable column presets under `pod.column_presets` in your config file, and set a default preset with `pod.default_preset`.
#### Example config
```yaml
theme:
pod:
# Name of the default preset to use at startup (optional)
default_preset: minimal
# Define named presets of pod columns
column_presets:
default:
- name
- status
- age
- ip
- node
minimal:
- name
- status
- age
```
To use a preset defined in your config file at runtime:
```sh
kubetui --pod-columns-preset=default
```
This will apply the preset named "default" defined in your configuration file.
If both `--pod-columns` and `--pod-columns-preset` are specified, `--pod-columns` takes precedence.
If neither is specified, the preset defined in `pod.default_preset` (if any) is used.
### Shell Completion
Kubetui supports shell completion for Bash and Zsh. You can enable the completion by adding the following to your shell configuration file:
For Bash (add to `~/.bashrc` or `~/.bash_profile`):
```bash
source <(kubetui completion bash)
```
For Zsh (add to `~/.zshrc`):
```bash
source <(kubetui completion zsh)
```
### Custom Configuration
You can customize the UI appearance by specifying a configuration file using the `--config-file` flag:
```sh
kubetui --config-file /path/to/your/config.yaml
```
The configuration file can also be located at `~/.config/kubetui/config.yaml` or `$XDG_CONFIG_FILE/kubetui/config.yaml`.
The configuration file allows you to modify various aspects of the UI, including:
- **Border Styles**: Customize the border styles of different UI components.
- **Colors**: Change the colors of text, backgrounds, and borders.
- **Text Attributes**: Modify text attributes such as bold, italic, and underline.
A sample configuration file is available at `examples/config.yaml` to help you get started with customizing the UI.
## Log Query
The Log Query feature empowers you to retrieve logs from multiple Pods and their containers. Using regular expressions, selectors, and specified resources, you can precisely define the log retrieval targets. This functionality also allows you to filter logs using regular expressions, providing a powerful and flexible log querying experience.
### Usage Example
```
pod:app container:nginx log:401
```
```
pod:api log:error jq:.message
```
```
pod:api log:error jmespath:message
```
When entering `?` or `help` in the log query form, the help dialog will be displayed.
### Supported Queries
| Query | Alias | Description |
| ------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------- |
| pod:\ | pods, po, p | Include Pods that match the regular expression in log retrieval target. |
| !pod:\ | !pods, !po, !p | Exclude Pods that match the regular expression from log retrieval target. Can be defined multiple times. |
| container:\ | containers, co, c | Include containers that match the regular expression in log retrieval target. |
| !container:\ | !containers, !co, !c | Exclude containers that match the regular expression from log retrieval target. Can be defined multiple times. |
| log:\ | logs, lo, l | Retrieve logs that match the regular expression. Can be defined multiple times. |
| !log:\ | !logs, !lo, !l | Exclude logs that match the regular expression. Can be defined multiple times. |
| label:\ | labels | Include Pods with labels matching the selector in log retrieval target. Cannot be specified with resource. |
| field:\ | fields | Include Pods with fields matching the selector in log retrieval target. |
| jq:\ | | Apply jq filter to JSON logs. Extract fields or restructure output (e.g., `jq:.message`, `jq:{ts:.time}`). |
| jmespath:\ | jmes, jm | Apply JMESPath filter to JSON logs. Simpler syntax for common queries (e.g., `jmespath:message`, `jm:data.id`). |
| \/\ | | Include Pods belonging to the specified resource in log retrieval target. Cannot be specified with label. |
Supported resources:
| Resource | Alias |
| ----------- | ------------------- |
| pod | po, pods |
| replicaset | rs, replicasets |
| deployment | deploy, deployments |
| statefulset | sts, statefulsets |
| daemonset | ds, daemonsets |
| job | jobs |
| service | svc, services |
### Query String Escaping
When including spaces in queries such as `` or ``, enclose the string with `"` or `'`. For example:
```
pod:"a b"
label:"environment in (production, qa)"
```
If you use `"`, `'`, or `\` within the quoted string, escape them with `\`. For example:
```
pod:"a\\b"
```
Query Syntax
```
**Lexer and Parser**
LOG_QUERIES = QUERY ( " "+ QUERY )*
QUERY = POD
| EXCLUDE_POD
| CONTAINER
| EXCLUDE_CONTAINER
| LOG
| EXCLUDE_LOG
| LABEL
| FIELD
| JQ
| JMESPATH
| SPECIFIED_RESOURCE
POD = ( "pods" | "pod" | "po" | "p" ) ":" REGEX
EXCLUDE_POD = "!" POD
CONTAINER = ( "containers" | "container" | "co" | "c" ) ":" REGEX
EXCLUDE_CONTAINER = "!" CONTAINER
LOG = ( "logs" | "log" | "lo" | "l" ) ":" REGEX
EXCLUDE_LOG = "!" LOG
REGEX = QUOTED_STRING | UNQUOTED_STRING
LABEL = ( "labels" | "label" ) ":" SELECTOR
FIELD = ( "fields" | "field" ) ":" SELECTOR
SELECTOR = QUOTED_STRING | UNQUOTED_STRING
JQ = "jq" ":" EXPR
JMESPATH = ( "jmespath" | "jmes" | "jm" ) ":" EXPR
EXPR = QUOTED_STRING | UNQUOTED_STRING
SPECIFIED_RESOURCE = RESOURCE "/" NAME
RESOURCE = ( "pods" | "pod" | "po" )
| ( "replicasets" | "replicaset" | "rs" )
| ( "deployments" | "deployment" | "deploy" )
| ( "statefulsets" | "statefulset" | "sts" )
| ( "daemonsets" | "daemonset" | "ds" )
| ( "services" | "service" | "svc" )
| ( "jobs" | "job" )
NAME = ALPHANUMERIC ( ALPHANUMERIC | "-" | "." )* ALPHANUMERIC
UNQUOTED_STRING = ~['" \t\r\n] ( ~[ \t\r\n] )* // without spaces
QUOTED_STRING = "\"" ESCAPED_STRING "\"" | "'" ESCAPED_STRING "'"
ESCAPED_STRING = ( ESCAPED_CHAR | ~[\"'] )\*
ESCAPED_CHAR = "\\" | "\"" | "\'"
```
## Key Bindings
### General
| Key | Description |
| ------------------------------------ | ------------------------------------------------------------------- |
| h, ? | Open the dialog for help |
| Enter | Select an item and trigger an event |
| n | Open the dialog for selecting the namespace |
| N | Open the dialog for selecting multiple namespaces |
| c | Open the dialog for selecting the context |
| y | Open the dialog for yaml |
| Tab, Shift+Tab | Change the focus of the view within the active tab |
| number | Switch to the tab (number: 1~6) |
| ESC | Close the window or terminate the app (when the dialog is not open) |
| q | Terminate the app |
| f | Open the dialog for selecting multiple API resources |
| Shift+s | Toggle the split direction between vertical and horizontal |
### Key Map
| Source | Destination |
| --------------------------------------- | ----------------- |
| Ctrl+p | Up |
| Ctrl+n | Down |
| Ctrl+f | Right |
| Ctrl+b | Left |
| Ctrl+u | PgUp |
| Ctrl+d | PgDn |
| Ctrl+h, Backspace | Delete |
| Ctrl+a | Home |
| Ctrl+e | End |
| Ctrl+[ | Esc |
### View Control
| Key | Description |
| -------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| j, k, Down, Up, PgDn, PgUp | Change the selected item / Scroll the view |
| Left, Right | Scroll horizontally in the view |
| g | Go to the first item / Go to the top of the view |
| G | Go to the last item / Go to the bottom of the view |
### Text View
| Key | Description |
| ---------------------------- | ------------------------------------------------------------------------------ |
| / | Activate search mode and open the search form |
| Enter | Confirm the input |
| q, Esc | Disable search mode and close the search form (**when search mode is active**) |
### Search Mode
| Key | Description |
| ---------------------------- | ------------------------------- |
| n, N | Go to the next / previous match |
| q, Esc | Disable search mode |
### Table View
| Key | Description |
| -------------------------------- | --------------------- |
| / | Open the filter form |
| Enter, ESC | Close the filter form |
### Dialog
| Key | Description |
| ---------------------------------------------------------------- | ------------------------------------------------------------------- |
| Down, Up, PgDn, PgUp | Change the selected item / Scroll the view |
| Tab, Shift+Tab | Change the focus of the view within the active tab |
| Enter | Select an item and trigger an event |
| ESC | Close the window or terminate the app (when the dialog is not open) |
#### Context Dialog
| Key | Description |
| --------------------- | -------------------------------------------------------------- |
| Enter | Switch context and use previously cached namespaces |
| Ctrl+Space | Switch context and preserve current namespaces (if available) |
### Input Form
| Key | Description |
| --------------------------------- | ------------------------------------------------ |
| Home | Move the cursor to the beginning |
| End | Move the cursor to the end |
| Ctrl+w | Delete text from the cursor to the beginning |
| Ctrl+k | Delete text from the cursor to the end |
| Left, Right | Move the cursor to the previous / next character |
### Container Logs View
| Key | Description |
| ---------------------------- | ------------------------------------------------------------------ |
| f, p | Toggle between pretty print and single-line display for JSON logs. |
| Enter | Insert a blank line. |
## Contributing
Bug reports and pull requests are welcome.
## License
This software is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).