kubectx README

The project's README from github.com/ahmetb/kubectx. As one markdown file: README.md.

kubectx + kubens: Power tools for kubectl

Latest GitHub release GitHub stars Homebrew downloads Go implementation (CI)

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, and launch readonly shells for each context.
kubens is a tool to switch between Kubernetes namespaces (and configure them for kubectl) easily.

Here's a kubectx demo: kubectx demo GIF

...and here's a kubens demo: kubens demo GIF

Usage

kubectx

Switch to another cluster that's in kubeconfig:

$ kubectx minikube
Switched to context "minikube".

Switch back to previous cluster:

$ kubectx -
Switched to context "oregon".

Start an isolated shell that only has a single context:

$ kubectx -s minikube

Start a read-only shell where write operations are blocked:

$ kubectx -r minikube

Rename context:

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

kubens

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

Change the active namespace even if it doesn't exist:

$ kubens namespace-404 -f
Context "test" set.
Active namespace is "namespace-404".

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

Package manager Command
Homebrew (macOS & Linux) brew install kubectx
MacPorts (macOS) sudo port install kubectx
apt (Debian/Ubuntu) sudo apt install kubectx
pacman (Arch Linux) sudo pacman -S kubectx
Chocolatey (Windows) choco install kubens kubectx
Scoop (Windows) scoop bucket add main && scoop install main/kubens main/kubectx
winget (Windows) winget install --id ahmetb.kubectx && winget install --id ahmetb.kubens
Krew (kubectl plugin) kubectl krew install ctx && kubectl krew install ns

Alternatively, download binaries from the Releases page → and add them to somewhere in your PATH.

Shell completion scripts

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.

zsh (plain)

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.

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

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/

[!NOTE] Tip: Show context/namespace in your shell prompt with oh-my-posh or simply with kube-ps1.

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.

kubectx interactive search with fzf

Caveats:

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

Stargazers over time Google Analytics

kubectx (ahmetb/kubectx)

Searching Database…

20K ·GitHub
Kubectx
What is this?Two tiny command-line helpers for kubectl: kubectx switches between your Kubernetes clusters (contexts) and kubens switches the active namespace — no more typing long kubectl config commands.
Is this one tool or two?Two separate commands from one repo: kubectx for cluster contexts, kubens for namespaces. They are standalone binaries, and Krew can also install them as kubectl plugins.
Do I need anything besides kubectl?Just kubectl and your kubeconfig — the tools read and rewrite it. fzf is optional: with it on your PATH both tools switch to an interactive menu with fuzzy search.
Any gotchas I should know about?If fzf is installed it takes over listing automatically — opt out with KUBECTX_IGNORE_FZF=1 or pipe the output (kubectx | cat) for default behavior. zsh tab completion may need manual fpath/compinit setup.
What can it do besides plain switching?kubectx can switch back to the previous cluster, rename contexts, and start an isolated shell bound to a single context or a read-only shell where write operations are blocked. kubens can return to the previous namespace and even switch to a namespace that does not exist yet.
Does switching touch the cluster itself?No. Both tools only update your local kubeconfig — the current context and the default namespace kubectl uses — so a switch is instant and nothing changes on the cluster side.
Can I see the current cluster in my shell prompt?The README suggests pairing kubectx and kubens with kube-ps1 or oh-my-posh, which show the active context and namespace right in your prompt.
Can I customize or turn off the colored output?Yes — environment variables set the colors of the current context/namespace indicators, and setting NO_COLOR disables colors entirely.
What are similar projects?k9s, k10s, kompose, kind, helm, sofka, vcluster, podman
Which topics is it in?kubectl, fuzzy-search, cloud-native, homebrew, sysadmin, kubernetes, developers, devops, go, terminal, apache-2.0, cli
Creator
ahmetb
Size
1 MB
Stars
20K
Updated
CommitJul 26Releasev0.11.0Mar 27
Age
9y
Commits · 90 Days