From d37f1b6fa7d98d7b7d92486e666b70d9144da1a2 Mon Sep 17 00:00:00 2001 From: Mircea-Pavel ANTON Date: Sat, 8 Mar 2025 00:42:36 +0200 Subject: [PATCH] docs: Update readme --- README.md | 147 ++++++++++++++++++++++++++---------------------------- 1 file changed, 72 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 160922c..9c2e8a3 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,20 @@ # kubectl-switch -A simple tool to manage and switch between multiple Kubernetes configuration files. This tool allows you to dump all your kubeconfig files in a single directory and easily switch between them as well as configure the current namespace. +`kubectl-switch` is a command-line tool for managing and switching between multiple Kubernetes configuration files located in the same directory. It simplifies the process of selecting a Kubernetes context from multiple kubeconfig files and updating the active configuration or namespace. + +Just dump all your `kubeconfigs` into a single dir and let `kubectl-switch` manage them for you! ## Features -- Manage multiple kubeconfig files in a single directory. -- Easily switch between different Kubernetes contexts. -- Easily switch between different namespaces. -- Persistent context/namespace switching across different shells. -- Interactive prompts support fuzzy search. -- Non-destructive operations on your original kubeconfig files. `kubectl-switch` will never edit those. It will only work with copies of them. +- **Multiple kubeconfig files**: Manage multiple kubeconfig files with one or more contexts each, all present in a single directory. You don't have to generate a global kubeconfig to hold all of your contexts +- **Context Switching**: Easily switch between different Kubernetes contexts from multiple config files. +- **Namespace Switching**: Quickly change the current namespace in the active context. +- **Previous Config**: Switch back to the previous configuration with `kubectl switch -`. +- **Non-Interactive Mode**: Specify the desired context or namespace directly as an argument. +- **Interactive Mode**: Run the program with no arguments to get an interactive list of available namespaces or contexts to choose from. +- **Persistent Configuration**: Changes persist across different shell sessions. +- **Shell Completions**: Provides tab completion for available contexts and namespaces. +- **Non-destructive**: `kubectl-switch` will never edit those. It will only work with copies of them. ## Why `kubectl-switch`? @@ -72,93 +77,85 @@ docker pull ghcr.io/mirceanton/kubectl-switch 2. Build the tool: - If you have [Taskfile](https://taskfile.dev/) installed, run: - ```bash - task build + mise run build ``` - Otherwise, simply run the `go build` command: +## Usage - ```bash - go build -o kubectl-switch - ``` +### Context Command -## Usage +The `context` (or `ctx`) subcommand is used to switch between Kubernetes contexts (think of `kubectx`): -1. Place all of your `kubeconfig` files in a single directory. I personally prefer `~/.kube/configs/` but you can do whatever you fancy. +```bash +# Interactive mode - select context from a list +kubectl-switch context -2. Set the environment variable `KUBECONFIG_DIR` +# Switch to a specific context +kubectl-switch ctx my-context +``` - ```sh - export KUBECONFIG_DIR="~/.kube/configs/" # <- put here whatever folder you decided on at step 1 - ``` +### Namespace Command -3. Run `kubectl switch ctx` or `kubectl switch context` to interactively select your context from a list +The `namespace` (or `ns`) subcommand is used to switch the current namespace (think of `kubens`): - ```sh - vscode ➜ /workspaces/kubectl-switch $ kubectl switch context - ? Choose a context: [Use arrows to move, type to filter] - cluster1kubectl-switch - cluster2 - > cluster3kubectl-switch +```bash +# Interactive mode - select namespace from a list +kubectl-switch namespace - INFO[0102] Switched tkubectl-switchuster3' +# Switch to a specific namespace +kubectl-switch ns kube-system +``` - vscode ➜ /workspaces/kubectl-switch $ kubectl get nodes - NAME STATUS ROLES AGE VERSION - cluster3 Ready control-plane 21h v1.30.0 - ``` +### Quickly Switch to Previous Configuration - Alternatively, pass in a context name to the command to non-interactively switch to it: +Switch back to the previous configuration: - ```sh - vscode ➜ /workspaces/kubectl-switch $ kubectl switch ctx cluster3 - INFO[0000] Switched to context 'cluster3' +```bash +kubectl-switch - +``` - vscode ➜ /workspaces/kubectl-switch $ kubectl get nodes - NAME STATUS ROLES AGE VERSION - cluster3 Ready control-plane 21h v1.30.0 - ``` +### Usage with kubectl plugin - This will literally detect the file in which that context is defined and copy-paste it to the path defined in your `KUBECONFIG`. - -4. Run the `kubectl switch ns` or `kubectl switch namespace` to interactively select your current namespace from a list - - ```sh - vscode ➜ /workspaces/kubectl-switch $ kubectl switch namespace - ? Choose a namespace: [Use arrows to move, type to filter] - > default - kube-node-lease - kube-public - kube-system - - INFO[0012] Switched to namespace 'kube-system' - - vscode ➜ /workspaces/kubectl-switch $ kubectl get pods - NAME READY STATUS RESTARTS AGE - coredns-7db6d8ff4d-nqmlf 1/1 Running 1 (69m ago) 21h - etcd-cluster1 1/1 Running 1 (69m ago) 21h - kube-apiserver-cluster1 1/1 Running 1 (69m ago) 21h - kube-controller-manager-cluster1 1/1 Running 1 (69m ago) 21h - kube-proxy-lxnvr 1/1 Running 1 (69m ago) 21h - kube-scheduler-cluster1 1/1 Running 1 (69m ago) 21h - storage-provisioner 1/1 Running 3 (68m ago) 21h - ``` +When installed as a kubectl plugin, you can use it directly with the `kubectl` command: + +```sh +# These commands are equivalent +kubectl-switch ctx +kubectl switch ctx +``` - Alternatively, pass in a namespace name to the command to non-interactively switch to it: +## Configuration - ```sh - vscode ➜ /workspaces/kubectl-switch $ kubectl get pods - No resources found in default namespace. - vscode ➜ /workspaces/kubectl-switch $ kubectl switch ns kube-public - INFO[0000] Switched to namespace 'kube-public' - vscode ➜ /workspaces/kubectl-switch $ kubectl get pods - No resources found in kube-public namespace. - ``` +You can configure `kubectl-switch` using environment variables or CLI flags: + +| Environment Variable | CLI Flag | Description | Default Value | +| :--------------------: | :---------------: | :----------------------------------------------: | :--------------------------: | +| `KUBECONFIG_DIR` | `--kubeconfig-dir` | Directory containing your kubeconfig files. | None | +| `KUBECONFIG` | N/A | Path where the active kubeconfig will be stored. | `~/.kube/config` | + +## Shell Completion + +The `completion` subcommand generates shell completion scripts: + +```bash +# Generate completions for bash +kubectl-switch completion bash > /etc/bash_completion.d/kubectl-switch + +# Generate completions for zsh +kubectl-switch completion zsh > ~/.zsh/completion/_kubectl-switch + +# Generate completions for fish +kubectl-switch completion fish > ~/.config/fish/completions/kubectl-switch.fish + +# Generate completions for powershell +kubectl-switch completion powershell > ~/kubectl-switch.ps1 +``` + +## Contributing - This will modify your currently active kubeconfig file (not the original one from `KUBECONFIGS_DIR`, but rather the copy from `KUBECONFIG`) to set the current namespace. +Contributions are welcome! Please fork the repository, make your changes, and submit a pull request. ## License -This project is licensed under the MIT License. See the `LICENSE` file for details. +This project is licensed under the MIT License. See the [`LICENSE`](./LICENSE) file for details.