kubectx Ahmet Alp Balkan

kubectx is a tool to switch between contexts (clusters) on kubectl faster.

README

kubectx + kubens: Power tools for kubectl

This repository provides both kubectx and kubens tools. Install →

What are kubectx and kubens?

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:

...and here's a kubens demo:

Examples

# switch to another cluster that's in kubeconfig
$ kubectx minikube
Switched to context "minikube".

# switch back to previous cluster
$ kubectx -
Switched to context "oregon".

# rename context
$ kubectx dublin=gke_ahmetb_europe-west1-b_dublin
Context "gke_ahmetb_europe-west1-b_dublin" renamed to "dublin".

# 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".

If you have 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 →

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

Stable versions of kubectx and kubens are small bash scripts that you can find in this repository.

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 →

Installation options:

• as kubectl plugins (macOS & Linux)
• with Homebrew (macOS & Linux)
• with MacPorts (macOS)
• with apt (Debian)
• with pacman (Arch Linux)
• with Chocolatey (Windows)
• Windows Installation (using Scoop)
• with winget (Windows)
• manually (macOS & Linux)

If you like to add context/namespace information to your shell prompt ($PS1), you can try out kube-ps1.

Kubectl Plugins (macOS and Linux)

You can install and use the 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 or install the scripts manually.

kubectl krew install ctx
kubectl krew install ns

After installing, the tools will be available as kubectl ctx and kubectl ns.

Homebrew (macOS and Linux)

If you use Homebrew you can install like this:

brew install kubectx

This command will set up bash/zsh/fish completion scripts automatically. Make sure you configure your shell to load completions for installed Homebrew formulas.

MacPorts (macOS)

If you use MacPorts you can install like this:

sudo port install kubectx

apt (Debian)

sudo apt install kubectx

Newer versions might be available on repos like Debian Buster (testing), Sid (unstable) (if you are unfamiliar with the Debian release process and how to enable testing/unstable repos, check out the Debian Wiki):

pacman (Arch Linux)

Available as official Arch Linux package. Install it via:

sudo pacman -S kubectx

Windows Installation (using Chocolatey)

Available as packages on Chocolatey

choco install kubens kubectx

Windows Installation (using Scoop)

Available as packages on Scoop

scoop bucket add main
scoop install main/kubens main/kubectx

Windows Installation (using winget)

Available as packages on winget

winget install --id ahmetb.kubectx
winget install --id ahmetb.kubens

Manual Installation (macOS and Linux)

Since kubectx and kubens are written in Bash, you should be able to install them to any POSIX environment that has Bash installed.

• Download the kubectx, and kubens scripts.
• Either:
  • save them all to somewhere in your PATH,
  • or save them to a directory, then create symlinks to kubectx/kubens from somewhere in your PATH, like /usr/local/bin
• Make kubectx and kubens executable (chmod +x ...)

Example installation steps:

sudo git clone https://github.com/ahmetb/kubectx /opt/kubectx
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 that fits your system best: zsh with antibody, plain zsh, bash or fish.

Completion scripts for zsh with antibody

Add this line to your Plugins File (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, 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.

Example with oh-my-zsh:

mkdir -p ~/.oh-my-zsh/custom/completions
chmod -R 755 ~/.oh-my-zsh/custom/completions
ln -s /opt/kubectx/completion/_kubectx.zsh ~/.oh-my-zsh/custom/completions/_kubectx.zsh
ln -s /opt/kubectx/completion/_kubens.zsh ~/.oh-my-zsh/custom/completions/_kubens.zsh
echo "fpath=($ZSH/custom/completions $fpath)" >> ~/.zshrc

If completion doesn't work, add autoload -U compinit && compinit to your .zshrc (similar to zsh-completions).

If you are not using oh-my-zsh, 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

git clone https://github.com/ahmetb/kubectx.git ~/.kubectx
COMPDIR=$(pkg-config --variable=completionsdir bash-completion)
ln -sf ~/.kubectx/completion/kubens.bash $COMPDIR/kubens
ln -sf ~/.kubectx/completion/kubectx.bash $COMPDIR/kubectx
cat << EOF >> ~/.bashrc


#kubectx and kubens
export PATH=~/.kubectx:\$PATH
EOF

Completion scripts for fish

mkdir -p ~/.config/fish/completions
ln -s /opt/kubectx/completion/kubectx.fish ~/.config/fish/completions/
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 in your $PATH.

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):

export KUBECTX_CURRENT_FGCOLOR=$(tput setaf 6) # blue text
export KUBECTX_CURRENT_BGCOLOR=$(tput setab 7) # white background

Colors in the output can be disabled by setting the NO_COLOR environment variable.

---

If you liked kubectx, you may like my kubectl-aliases project, too. I recommend pairing kubectx and kubens with fzf and kube-ps1.

Stargazers over time