stefankoelle/kctl-tui
1
0
Fork 0
mirror of https://github.com/skoelle/kctl-tui.git synced 2026-09-17 20:10:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

README.md

Browse Source
This commit is contained in:
stefankoelle
2026-08-14 23:52:41 +02:00
parent 4afb20c740
commit b9439e428a
2 changed files with 39 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.moonweb.yml
+6
View File
@@ -0,0 +1,6 @@
title: "kctl-tui"
emoji: "🐳"
category: code
subcategory: "Dev Tools"
status: active
stack: [Go, Bubbletea, Bubbles, Lipgloss, YAML]
README.md
+33 -33
View File
@@ -1,40 +1,40 @@
# kctl-tui # 🚀 kctl-tui
A small terminal entry point for everyday Kubernetes work: pick a context A small terminal entry point for everyday Kubernetes work: pick a context
and a namespace once, then drive rollout restarts and an AWS Secrets and a namespace once, then drive rollout restarts and an AWS Secrets
Manager <-> Kubernetes Secret diff/force-sync per environment from one Manager <-> Kubernetes Secret diff/force-sync per environment from one
place instead of retyping long `kubectl` commands. place instead of retyping long `kubectl` commands.
## Why ## ✨ Why
Working with several clusters, many namespaces per team, and paired Working with several clusters, many namespaces per team, and paired
environments (e.g. beta/prod) quickly turns into a lot of repeated typing environments (e.g. beta/prod) quickly turns into a lot of repeated typing
with plain `kubectl`/`k9s`. kctl-tui adds: with plain `kubectl`/`k9s`. kctl-tui adds:
- A guided **context -> team -> namespace** selection that starts - 🎯 A guided **context -> team -> namespace** selection that starts
directly at team selection (using a configured default context), with directly at team selection (using a configured default context), with
the context screen just one `Esc` away. the context screen just one `Esc` away.
- Namespace grouping by an arbitrary, configurable **label** instead of - 🏷️ Namespace grouping by an arbitrary, configurable **label** instead of
scrolling through every namespace in the cluster. scrolling through every namespace in the cluster.
- A **3-pane view** (via `tmux`): one control pane for actions, two status - 🖥️ A **3-pane view** (via `tmux`): one control pane for actions, two status
panes running `k9s` for the current namespace across your two panes running `k9s` for the current namespace across your two
configured environments (e.g. beta/prod), shown side by side. configured environments (e.g. beta/prod), shown side by side.
- A control-pane menu organized **by environment**: pick beta or prod, - 📋 A control-pane menu organized **by environment**: pick beta or prod,
then Secrets sync or Redeploy for that environment specifically. then Secrets sync or Redeploy for that environment specifically.
- AWS Secrets Manager secret IDs and Kubernetes context names/ARNs are - 🔐 AWS Secrets Manager secret IDs and Kubernetes context names/ARNs are
**computed from configurable templates** (namespace + environment), **computed from configurable templates** (namespace + environment),
instead of listing secrets or discovering contexts live from instead of listing secrets or discovering contexts live from
`kubectl`/`aws-cli`. `kubectl`/`aws-cli`.
- A guided **AWS Secrets Manager vs. Kubernetes Secret** comparison of - 🔄 A guided **AWS Secrets Manager vs. Kubernetes Secret** comparison of
every field at once, with a force-sync request for the whole secret if every field at once, with a force-sync request for the whole secret if
anything differs. anything differs.
- An **AWS auth check** before the secrets workflow, offering to run your - 🔑 An **AWS auth check** before the secrets workflow, offering to run your
configured SSO login command interactively if the session has expired. configured SSO login command interactively if the session has expired.
See [SPEC.md](SPEC.md) for the full requirements and design rationale, and See [SPEC.md](SPEC.md) for the full requirements and design rationale, and
[PLAN.md](PLAN.md) for the implementation roadmap and current status. [PLAN.md](PLAN.md) for the implementation roadmap and current status.
## How it works ## 🔧 How it works
``` ```
+--------------------------------------------------+ +--------------------------------------------------+
@@ -61,14 +61,14 @@ See [SPEC.md](SPEC.md) for the full requirements and design rationale, and
-> environment menu -> closes the whole tmux session, including both -> environment menu -> closes the whole tmux session, including both
`k9s` panes, and returns you to namespace selection). `k9s` panes, and returns you to namespace selection).
## Requirements ## 📋 Requirements
- `kubectl`, configured with access to your cluster(s) (the actual - 🐳 `kubectl`, configured with access to your cluster(s) (the actual
context names/ARNs are resolved from your `context_template`, see context names/ARNs are resolved from your `context_template`, see
Configuration below - they must already exist in your kubeconfig, e.g. Configuration below - they must already exist in your kubeconfig, e.g.
added via `aws eks update-kubeconfig`). added via `aws eks update-kubeconfig`).
- `k9s` (used for the two status panes). - 👀 `k9s` (used for the two status panes).
- `tmux` (used for the 3-pane layout). On **Linux/macOS**, install - 📺 `tmux` (used for the 3-pane layout). On **Linux/macOS**, install
`tmux` via your package manager. On **Windows**, install `tmux` via your package manager. On **Windows**, install
[psmux](https://github.com/marlocarlo/psmux) — a native, [psmux](https://github.com/marlocarlo/psmux) — a native,
tmux-compatible terminal multiplexer: tmux-compatible terminal multiplexer:
@@ -78,18 +78,18 @@ See [SPEC.md](SPEC.md) for the full requirements and design rationale, and
cargo install psmux cargo install psmux
``` ```
psmux provides a `tmux` command, so kctl-tui works without changes. psmux provides a `tmux` command, so kctl-tui works without changes.
- `aws` CLI, configured with credentials, only needed for the secrets - ☁️ `aws` CLI, configured with credentials, only needed for the secrets
workflow. workflow.
## Installation ## 📥 Installation
### Quick install (Linux/macOS/WSL) ### 🚀 Quick install (Linux/macOS/WSL)
```bash ```bash
curl -fsSL https://raw.githubusercontent.com/skoelle/kctl-tui/main/install.sh | bash curl -fsSL https://raw.githubusercontent.com/skoelle/kctl-tui/main/install.sh | bash
``` ```
### Quick install (Windows) ### 🪟 Quick install (Windows)
```powershell ```powershell
irm https://raw.githubusercontent.com/skoelle/kctl-tui/main/install.ps1 | iex irm https://raw.githubusercontent.com/skoelle/kctl-tui/main/install.ps1 | iex
@@ -98,7 +98,7 @@ irm https://raw.githubusercontent.com/skoelle/kctl-tui/main/install.ps1 | iex
This downloads the latest release binary for your OS/architecture from This downloads the latest release binary for your OS/architecture from
GitHub Releases and installs it to `/usr/local/bin/kctl-tui`. GitHub Releases and installs it to `/usr/local/bin/kctl-tui`.
### From source ### 🛠️ From source
```bash ```bash
git clone https://github.com/skoelle/kctl-tui.git git clone https://github.com/skoelle/kctl-tui.git
@@ -109,14 +109,14 @@ sudo mv kctl-tui /usr/local/bin/
Requires Go 1.22+. Requires Go 1.22+.
### Prebuilt binaries ### 📦 Prebuilt binaries
Every tagged release (`vX.Y.Z`) is built for `linux`, `darwin`, and Every tagged release (`vX.Y.Z`) is built for `linux`, `darwin`, and
`windows`, each for `amd64` and `arm64`, via the GitHub Actions workflow in `windows`, each for `amd64` and `arm64`, via the GitHub Actions workflow in
[.github/workflows/build.yml](.github/workflows/build.yml). Download the [.github/workflows/build.yml](.github/workflows/build.yml). Download the
matching asset from the [Releases page](https://github.com/skoelle/kctl-tui/releases). matching asset from the [Releases page](https://github.com/skoelle/kctl-tui/releases).
## Configuration ## ⚙️ Configuration
Copy [config.example.yaml](config.example.yaml) to `~/.kctl-tui/config.yaml` Copy [config.example.yaml](config.example.yaml) to `~/.kctl-tui/config.yaml`
and adjust it to your own setup: and adjust it to your own setup:
@@ -142,34 +142,34 @@ team_label_key: "example.org/team"
aws_sso_login_command: "aws sso login" aws_sso_login_command: "aws sso login"
``` ```
- `contexts` / `default_context`: the top-level grouping the tool starts - 🌐 `contexts` / `default_context`: the top-level grouping the tool starts
from (e.g. a network boundary such as internal/external-facing from (e.g. a network boundary such as internal/external-facing
clusters). This is the outermost navigation level, one `Esc` above team clusters). This is the outermost navigation level, one `Esc` above team
selection. selection.
- `envs`: the environments switchable from the control panel (e.g. - 🎛️ `envs`: the environments switchable from the control panel (e.g.
"beta"/"prod"). The **first two** entries are also used for the two k9s "beta"/"prod"). The **first two** entries are also used for the two k9s
status panes shown side by side. status panes shown side by side.
- `aws_region` / `aws_account_id`: used for AWS Secrets Manager calls and - 🌍 `aws_region` / `aws_account_id`: used for AWS Secrets Manager calls and
to fill the `{account_id}` placeholder in `context_template`. to fill the `{account_id}` placeholder in `context_template`.
`123456789012` is a placeholder, not a real account. `123456789012` is a placeholder, not a real account.
- `secret_name_template`: builds the AWS Secrets Manager secret ID from - 🔑 `secret_name_template`: builds the AWS Secrets Manager secret ID from
the chosen namespace and environment. Placeholders: `{namespace}`, the chosen namespace and environment. Placeholders: `{namespace}`,
`{env}`. `{env}`.
- `k8s_secret_name_template`: builds the Kubernetes secret name from the - 🏷️ `k8s_secret_name_template`: builds the Kubernetes secret name from the
chosen namespace. Kept separate from `secret_name_template` because the chosen namespace. Kept separate from `secret_name_template` because the
two sides commonly follow different naming conventions. Placeholders: two sides commonly follow different naming conventions. Placeholders:
`{namespace}`. `{namespace}`.
- `context_template`: builds the actual kubectl context name/ARN from - 🔗 `context_template`: builds the actual kubectl context name/ARN from
region, account ID, environment, and context. Placeholders: `{region}`, region, account ID, environment, and context. Placeholders: `{region}`,
`{account_id}`, `{env}`, `{context}`. Adjust the literal parts (`tf-`, `{account_id}`, `{env}`, `{context}`. Adjust the literal parts (`tf-`,
`-1`, cluster naming, ARN shape) to match how your own clusters/contexts `-1`, cluster naming, ARN shape) to match how your own clusters/contexts
are actually named — the resolved value must match an existing context are actually named — the resolved value must match an existing context
in your kubeconfig. in your kubeconfig.
- `team_label_key`: the Kubernetes namespace label used to group - 👥 `team_label_key`: the Kubernetes namespace label used to group
namespaces by team/ownership in the team-selection screen. This is namespaces by team/ownership in the team-selection screen. This is
entirely up to your organization's labeling convention; kctl-tui ships entirely up to your organization's labeling convention; kctl-tui ships
with no default team label of its own. with no default team label of its own.
- `aws_sso_login_command`: run interactively if `aws sts - 🔐 `aws_sso_login_command`: run interactively if `aws sts
get-caller-identity` fails before the secrets workflow (e.g. an expired get-caller-identity` fails before the secrets workflow (e.g. an expired
SSO session). Defaults to `aws sso login`. SSO session). Defaults to `aws sso login`.
@@ -177,7 +177,7 @@ aws_sso_login_command: "aws sso login"
that way — it typically contains your organization's internal account ID, that way — it typically contains your organization's internal account ID,
context naming, and label names. context naming, and label names.
## Windows notes ## 🪟 Windows notes
On native Windows (without WSL), install [psmux](https://github.com/marlocarlo/psmux) On native Windows (without WSL), install [psmux](https://github.com/marlocarlo/psmux)
for the 3-pane layout. psmux is a native Windows terminal multiplexer for the 3-pane layout. psmux is a native Windows terminal multiplexer
@@ -196,7 +196,7 @@ mkdir -p ~/.kube
ln -s /mnt/c/Users/<your-windows-username>/.kube/config ~/.kube/config ln -s /mnt/c/Users/<your-windows-username>/.kube/config ~/.kube/config
``` ```
## Usage ## 📖 Usage
```bash ```bash
kctl-tui # start the TUI (full navigation mode) kctl-tui # start the TUI (full navigation mode)
@@ -208,7 +208,7 @@ kctl-tui config check # validate ~/.kctl-tui/config.yaml
kctl-tui panel --context=... --ns=... --team=... # internal (called by tmux) kctl-tui panel --context=... --ns=... --team=... # internal (called by tmux)
``` ```
## Development ## 🛠️ Development
```bash ```bash
go test ./... go test ./...
@@ -222,6 +222,6 @@ unit tests. Code that shells out to `kubectl`/`aws`/`tmux` lives in
`internal/kubeexec` and in `cmd/kctl-tui` and is intentionally kept thin `internal/kubeexec` and in `cmd/kctl-tui` and is intentionally kept thin
and untested, since it has no meaningful behavior without a live cluster. and untested, since it has no meaningful behavior without a live cluster.
## License ## 📄 License
Licensed under the [MIT License](LICENSE) - Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de) Licensed under the [MIT License](LICENSE) - Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)