diff --git a/.moonweb.yml b/.moonweb.yml new file mode 100644 index 0000000..fcf70c2 --- /dev/null +++ b/.moonweb.yml @@ -0,0 +1,6 @@ +title: "kctl-tui" +emoji: "🐳" +category: code +subcategory: "Dev Tools" +status: active +stack: [Go, Bubbletea, Bubbles, Lipgloss, YAML] diff --git a/README.md b/README.md index 67e1586..206e0b2 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,40 @@ -# kctl-tui +# 🚀 kctl-tui A small terminal entry point for everyday Kubernetes work: pick a context and a namespace once, then drive rollout restarts and an AWS Secrets Manager <-> Kubernetes Secret diff/force-sync per environment from one place instead of retyping long `kubectl` commands. -## Why +## ✨ Why Working with several clusters, many namespaces per team, and paired environments (e.g. beta/prod) quickly turns into a lot of repeated typing 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 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. -- 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 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. -- 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), instead of listing secrets or discovering contexts live from `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 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. See [SPEC.md](SPEC.md) for the full requirements and design rationale, and [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 `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 Configuration below - they must already exist in your kubeconfig, e.g. added via `aws eks update-kubeconfig`). -- `k9s` (used for the two status panes). -- `tmux` (used for the 3-pane layout). On **Linux/macOS**, install +- 👀 `k9s` (used for the two status panes). +- 📺 `tmux` (used for the 3-pane layout). On **Linux/macOS**, install `tmux` via your package manager. On **Windows**, install [psmux](https://github.com/marlocarlo/psmux) — a native, tmux-compatible terminal multiplexer: @@ -78,18 +78,18 @@ See [SPEC.md](SPEC.md) for the full requirements and design rationale, and cargo install psmux ``` 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. -## Installation +## 📥 Installation -### Quick install (Linux/macOS/WSL) +### 🚀 Quick install (Linux/macOS/WSL) ```bash curl -fsSL https://raw.githubusercontent.com/skoelle/kctl-tui/main/install.sh | bash ``` -### Quick install (Windows) +### 🪟 Quick install (Windows) ```powershell 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 GitHub Releases and installs it to `/usr/local/bin/kctl-tui`. -### From source +### 🛠️ From source ```bash git clone https://github.com/skoelle/kctl-tui.git @@ -109,14 +109,14 @@ sudo mv kctl-tui /usr/local/bin/ Requires Go 1.22+. -### Prebuilt binaries +### 📦 Prebuilt binaries Every tagged release (`vX.Y.Z`) is built for `linux`, `darwin`, and `windows`, each for `amd64` and `arm64`, via the GitHub Actions workflow in [.github/workflows/build.yml](.github/workflows/build.yml). Download the 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` and adjust it to your own setup: @@ -142,34 +142,34 @@ team_label_key: "example.org/team" 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 clusters). This is the outermost navigation level, one `Esc` above team 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 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`. `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}`, `{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 two sides commonly follow different naming conventions. Placeholders: `{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}`, `{account_id}`, `{env}`, `{context}`. Adjust the literal parts (`tf-`, `-1`, cluster naming, ARN shape) to match how your own clusters/contexts are actually named — the resolved value must match an existing context 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 entirely up to your organization's labeling convention; kctl-tui ships 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 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, context naming, and label names. -## Windows notes +## 🪟 Windows notes On native Windows (without WSL), install [psmux](https://github.com/marlocarlo/psmux) for the 3-pane layout. psmux is a native Windows terminal multiplexer @@ -196,7 +196,7 @@ mkdir -p ~/.kube ln -s /mnt/c/Users//.kube/config ~/.kube/config ``` -## Usage +## 📖 Usage ```bash 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) ``` -## Development +## 🛠️ Development ```bash 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 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)