diff --git a/README.md b/README.md index 3800370..230937a 100644 --- a/README.md +++ b/README.md @@ -9,94 +9,68 @@ This repository provides both `kubectx` and `kubens` tools. [Install →](#installation) -> **🥳📰 NEWS:** With v0.9.0 `kubectx` and `kubens` **are now rewritten in Go**. -> (Don't worry, our lovely **bash** versions are still available!) Please test -> this new Go binaries by downloading them from -> [**Releases →**](https://github.com/ahmetb/kubectx/releases) +## What are `kubectx` and `kubens`? -**`kubectx`** helps you switch between clusters back and forth: +**kubectx** is a tool to switch between contexts (clusters) on kubectl +faster.
+**kubens** is a tool to switch between Kubernetes namespaces (and +configure them for kubectl) easily. + +Here's a **`kubectx`** demo: ![kubectx demo GIF](img/kubectx-demo.gif) -**`kubens`** helps you switch between Kubernetes namespaces smoothly: +...and here's a **`kubens`** demo: ![kubens demo GIF](img/kubens-demo.gif) -# kubectx(1) - -kubectx is a utility to manage and switch between kubectl(1) contexts. - -``` -USAGE: - kubectx : list the contexts - kubectx : switch to context - kubectx - : switch to the previous context - kubectx -c, --current : show the current context name - kubectx = : rename context to - kubectx =. : rename current-context to - kubectx -d : delete context ('.' for current-context) - (this command won't delete the user/cluster entry - that is used by the context) - kubectx -u, --unset : unset the current context -``` - -### Usage +### Examples ```sh +# switch to anoter cluster that's in kubeconfig $ kubectx minikube Switched to context "minikube". +# switch back to previous cluster $ kubectx - Switched to context "oregon". -$ kubectx - -Switched to context "minikube". - +# create an alias for the context $ kubectx dublin=gke_ahmetb_europe-west1-b_dublin Context "dublin" set. Aliased "gke_ahmetb_europe-west1-b_dublin" as "dublin". -``` -`kubectx` supports Tab completion on bash/zsh/fish shells to help with -long context names. You don't have to remember full context names anymore. - ------ - -# kubens(1) - -kubens is a utility to switch between Kubernetes namespaces. - -``` -USAGE: - kubens : list the namespaces - kubens : change the active namespace - kubens - : switch to the previous namespace - kubens -c, --current : show the current namespace -``` - - -### Usage - -```sh +# change the active namespace on kubectl $ kubens kube-system Context "test" set. Active namespace is "kube-system". +# go back to the previous namespace $ kubens - Context "test" set. Active namespace is "default". ``` -`kubens` also supports Tab completion on bash/zsh/fish shells. +If you have [`fzf`](https://github.com/junegunn/fzf) installed, you can also +**interactively** select a context or cluster, or fuzzy-search by typing a few +characters. To learn more, read [interactive mode →](#interactive-mode) + +Both `kubectx` and `kubens` support Tab completion on bash/zsh/fish +shells to help with long context names. You don't have to remember full context +names anymore. ----- ## Installation -> **🥳📰 NEWS:** With v0.9.0 `kubectx` and `kubens` **are now rewritten in Go**. -> (Don't worry, our lovely **bash** versions are still available!) Please test -> this new Go binaries by downloading them from -> [**Releases →**](https://github.com/ahmetb/kubectx/releases) +Stable versions of `kubectx` and `kubens` are small bash scripts that you +can find in this repository. -There are several installation options: +Starting with v0.9.0, `kubectx` and `kubens` **are now rewritten in Go**. They +should work the same way (and we'll keep the bash-based implementations around) +but the new features will be added to the new Go programs. Please help us test +this new Go implementation by downloading the binaries from the [**Releases page +→**](https://github.com/ahmetb/kubectx/releases) + +**Installation options:** - [as kubectl plugins (macOS & Linux)](#kubectl-plugins-macos-and-linux) - [with Homebrew (macOS & Linux)](#homebrew-macos-and-linux) @@ -104,16 +78,19 @@ There are several installation options: - [with apt (Debian)](#apt-debian) - [with pacman (Arch Linux)](#pacman-arch-linux) - [manually (macOS & Linux)](#manual-installation-macos-and-linux) - -If you like to add context/namespace information to your shell prompt (`$PS1`), you can try out [kube-ps1](https://github.com/jonmosco/kube-ps1). - + +If you like to add context/namespace information to your shell prompt (`$PS1`), +you can try out [kube-ps1]. + +[kube-ps1]: https://github.com/jonmosco/kube-ps1 ### Kubectl Plugins (macOS and Linux) You can install and use the [Krew](https://github.com/kubernetes-sigs/krew/) kubectl plugin manager to get `kubectx` and `kubens`. -**NOTE:** This will not install the shell completion scripts. If you want them, choose another installation method +**Note:** This will not install the shell completion scripts. If you want them, +*choose another installation method or install the scripts [manually](#manual-installation-macos-and-linux). ```sh @@ -184,20 +161,32 @@ sudo ln -s /opt/kubectx/kubectx /usr/local/bin/kubectx sudo ln -s /opt/kubectx/kubens /usr/local/bin/kubens ``` -If you also want to have shell completions, pick an installation method for the [completion scripts](completion/) that fits your system best: [`zsh` with `antibody`](#completion-scripts-for-zsh-with-antibody), [plain `zsh`](#completion-scripts-for-plain-zsh), [`bash`](#completion-scripts-for-bash) or [`fish`](#completion-scripts-for-fish). +If you also want to have shell completions, pick an installation method for the +[completion scripts](completion/) that fits your system best: [`zsh` with +`antibody`](#completion-scripts-for-zsh-with-antibody), [plain +`zsh`](#completion-scripts-for-plain-zsh), +[`bash`](#completion-scripts-for-bash) or +[`fish`](#completion-scripts-for-fish). #### Completion scripts for `zsh` with [antibody](https://getantibody.github.io) -Add this line to your [Plugins File](https://getantibody.github.io/usage/) (e.g. `~/.zsh_plugins.txt`): +Add this line to your [Plugins File](https://getantibody.github.io/usage/) (e.g. +`~/.zsh_plugins.txt`): ``` ahmetb/kubectx path:completion kind:fpath ``` - -Depending on your setup, you might or might not need to call `compinit` or `autoload -U compinit && compinit` in your `~/.zshrc` after you load the Plugins file. If you use [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh), load the completions before you load `oh-my-zsh` because `oh-my-zsh` will call `compinit`. + +Depending on your setup, you might or might not need to call `compinit` or +`autoload -U compinit && compinit` in your `~/.zshrc` after you load the Plugins +file. If you use [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh), load the +completions before you load `oh-my-zsh` because `oh-my-zsh` will call +`compinit`. #### Completion scripts for plain `zsh` -The completion scripts have to be in a path that belongs to `$fpath`. Either link or copy them to an existing folder. + +The completion scripts have to be in a path that belongs to `$fpath`. Either +link or copy them to an existing folder. Example with [`oh-my-zsh`](https://github.com/ohmyzsh/ohmyzsh): @@ -208,14 +197,18 @@ ln -s /opt/kubectx/completion/_kubectx.zsh ~/.oh-my-zsh/completions/_kubectx.zsh ln -s /opt/kubectx/completion/_kubens.zsh ~/.oh-my-zsh/completions/_kubens.zsh ``` -If completion doesn't work, add `autoload -U compinit && compinit` to your `.zshrc` (similar to [`zsh-completions`](https://github.com/zsh-users/zsh-completions/blob/master/README.md#oh-my-zsh)). +If completion doesn't work, add `autoload -U compinit && compinit` to your +`.zshrc` (similar to +[`zsh-completions`](https://github.com/zsh-users/zsh-completions/blob/master/README.md#oh-my-zsh)). -If you are not using [`oh-my-zsh`](https://github.com/ohmyzsh/ohmyzsh), you could link to `/usr/share/zsh/functions/Completion` (might require sudo), depending on the `$fpath` of your zsh installation. +If you are not using [`oh-my-zsh`](https://github.com/ohmyzsh/ohmyzsh), you +could link to `/usr/share/zsh/functions/Completion` (might require sudo), +depending on the `$fpath` of your zsh installation. In case of errors, calling `compaudit` might help. #### Completion scripts for `bash` - + ```bash git clone https://github.com/ahmetb/kubectx.git ~/.kubectx COMPDIR=$(pkg-config --variable=completionsdir bash-completion) @@ -242,25 +235,28 @@ ln -s /opt/kubectx/completion/kubens.fish ~/.config/fish/completions/ ### Interactive mode If you want `kubectx` and `kubens` commands to present you an interactive menu -with fuzzy searching, you just need to [install `fzf`](https://github.com/junegunn/fzf) in your `$PATH`. +with fuzzy searching, you just need to [install +`fzf`](https://github.com/junegunn/fzf) in your `$PATH`. ![kubectx interactive search with fzf](img/kubectx-interactive.gif) -If you have `fzf` installed, but want to opt out of using this feature, set the environment variable `KUBECTX_IGNORE_FZF=1`. - -If you want to keep `fzf` interactive mode but need the default behavior of the command, you can do it using Unix composability: -``` -kubectx | cat -``` +If you have `fzf` installed, but want to opt out of using this feature, set the +environment variable `KUBECTX_IGNORE_FZF=1`. +If you want to keep `fzf` interactive mode but need the default behavior of the +command, you can do it by piping the output to another command (e.g. `kubectx | +cat `). ----- ### Customizing colors -If you like to customize the colors indicating the current namespace or context, set the environment variables `KUBECTX_CURRENT_FGCOLOR` and `KUBECTX_CURRENT_BGCOLOR` (refer color codes [here](https://linux.101hacks.com/ps1-examples/prompt-color-using-tput/)): +If you like to customize the colors indicating the current namespace or context, +set the environment variables `KUBECTX_CURRENT_FGCOLOR` and +`KUBECTX_CURRENT_BGCOLOR` (refer color codes +[here](https://linux.101hacks.com/ps1-examples/prompt-color-using-tput/)): -``` +```sh export KUBECTX_CURRENT_FGCOLOR=$(tput setaf 6) # blue text export KUBECTX_CURRENT_BGCOLOR=$(tput setab 7) # white background ``` @@ -270,27 +266,12 @@ Colors in the output can be disabled by setting the ----- -#### Users - -| What are others saying about kubectx? | -| ---- | -| _“Thank you for kubectx & kubens - I use them all the time & have them in my k8s toolset to maintain happiness :) ”_ – [@pbouwer](https://twitter.com/pbouwer/status/925896377929949184) | -| _“I can't imagine working without kubectx and especially kubens anymore. It's pure gold.”_ – [@timoreimann](https://twitter.com/timoreimann/status/925801946757419008) | -| _“I'm liking kubectx from @ahmetb, makes it super-easy to switch #Kubernetes contexts [...]”_ — [@lizrice](https://twitter.com/lizrice/status/928556415517589505) | -| _“Also using it on a daily basis. This and my zsh config that shows me the current k8s context 😉”_ – [@puja108](https://twitter.com/puja108/status/928742521139810305) | -| _“Lately I've found myself using the kubens command more than kubectx. Both very useful though :-)”_ – [@stuartleeks](https://twitter.com/stuartleeks/status/928562850464907264) | -| _“yeah kubens rocks!”_ – [@embano1](https://twitter.com/embano1/status/928698440732815360) | -| _“Special thanks to Ahmet Alp Balkan for creating kubectx, kubens, and kubectl aliases, as these tools made my life better.”_ – [@strebeld](https://medium.com/@strebeld/5-ways-to-enhance-kubectl-ux-97c8893227a) | -| _“❤️ this shell script @ahmetb wrote to help make switching between kubectl config contexts a breeze.”_ – [@briandanowski](https://twitter.com/briandanowski/status/1085409568165896193) | - -> If you liked `kubectx`, you may like my [`kubectl-aliases`](https://github.com/ahmetb/kubectl-aliases) project, too. - ------ - -Disclaimer: This is not an official Google product. - +If you liked `kubectx`, you may like my +[`kubectl-aliases`](https://github.com/ahmetb/kubectl-aliases) project, too. I +recommend pairing kubectx and kubens with [fzf](#interactive-mode) and +[kube-ps1]. #### Stargazers over time [![Stargazers over time](https://starchart.cc/ahmetb/kubectx.svg)](https://starchart.cc/ahmetb/kubectx) -![Google Analytics](https://ga-beacon.appspot.com/UA-2609286-17/kubectx/README?pixel) +![Google Analytics](https://ga-beacon.appspot.com/UA-2609286-17/kubectx/README?pixel)