ahmetb / kubectx

Faster way to switch between clusters and namespaces in kubectl

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

kubectx's Issues

kubectx A=B should use rename

Currently we're creating alias of a context by running kubectx A=B.

With the new kubectl context rename function we should just use it to rename.

Rename kubectx

If the project goal is to save keystrokes, kubectx is inconvenient because it breaks autocompletion to kubectl.

(i'd have to enter kub<tab>l<space>)

kubectx minikube=minikube deletes context

Executed this command, and my minikube context was gone:

$ kubectx minikube=minikube
Context "minikube" exists, deleting...
error: cannot rename the context "minikube", it's not in ...

Add fzf support for interactive search

We can optionally support fzf if it is in the PATH to provide interactive context selecting with partial/fuzzy input!

it would work like:

if len(args) == 1 && output is tty && fzf in path:
    # interactive mode
    choice="$(FZF_DEFAULT_COMMAND=kubectx NO_COLOR=1 fzf)"
	set_context $choice
else:
    # non-interactive mode (list contexts and exit)
    list_contexts
end

Anyone like this?

close

close

Unable to run kubectx with short name (kctx) on Mac

Hi,

I tried to install kubectx on Mac using brew install kubectx --with-short-names .

When I try to run kctx , I get an error error: converting to : type names don't match (Unknown, RawExtension), and no conversion 'func (runtime.Unknown, runtime.RawExtension) error' registered.

Any idea what could be wrong?

kubectx and kubens no longer work on macOS due to missing readlink -f option

Hi Ahmet, first of all, excellent tool!

This morning, I noticed that the current versions of both kubectx and kubens no longer (since #6) work on macOS (and possibly other BSD-based systems), because readlink on these systems don't know about the -f option (to follow symlinks, and canonicalise the name).

$ kubens

readlink: illegal option -- f
usage: readlink [-n] [file ...]
/usr/local/bin/kubens: line 28: ./../include/utils.bash: No such file or directory

We could either require the GNU version of readlink (which supports -f/--canonicalize), and add a case to use greadlink on macOS, or add our own function that behaves like GNU's readlink, i.e. iterate through symlinks, and return the canonical name.

Could be great if you could add auto switch / activate proxy when running kctx

Windows support

Would love to see Windows executables similar to kubectl and helm.
kubectx.exe and kubens.exe

add Japanese translation

Hi.

I’m a fun of your project.
I’ve thought it will be nice if there is a Japanese version of README, because I sometimes have to make a small lesson about how to use/install this project for new employees who can not read English.

So I decided to add README in Japanese and create a pull request, although I’m not sure whether the location of README_ja.md is appropriate or not.
Please give me your opinion.

Finally, when you want to update README, just create an issue or contact me. I’ll be happy to modify README_ja.md based on the changes of the original README.

Thanks!

Shoot a demo GIF for readme

We need some catchy stuff in the README. Currently it's too abstract.

kubectx -d: add shell completion (zsh)

I just realized we didn't code the bash/zsh/fish completions in a way that it can complete context names in subcommands like -d.

"$ kubectx -d TabTab" should suggest some context to delete.

Additionally, in case of -d, supporting multiple arguments for (#39) would require completion scripts should to auto-complete context names in multiple positions ($2, $3, ... $N) as well.

kubectx -d is not deleting multiple contexts

It's only deleting the first context specified.

It's visible on 8df9231 or v0.5.1 easily.

kubectx kubens in centos7 run error

error log:
/usr/local/bin/kubectx: line 30: /usr/local/bin/../include/utils.bash: No such file or directory

Since 0.6.0 kctx doesn't work anymore

Setup:
I am using MacOS and installed kubectx this way:

brew install kubectx --with-short-names

I just upgraded to 0.6.0.

Problem:
Running kctx command shows fzf-view and [$FZF_DEFAULT_COMMAND failed]

Cause:
I found the line of code which causes trouble: https://github.com/ahmetb/kubectx/blob/master/kubectx#L94

choice="$(FZF_DEFAULT_COMMAND='kubectx' fzf --ansi || true)"

kubectx does not exist in my environment, because I installed kubectx with --with-short-names. I only have kctx

Support $NO_COLOR

http://no-color.org/
related: #53

Add merge/import command

Would it be possible to add a merge/import command where I could specify a kubeconfig file (e.g. generated by different systems) to import that kubeconfig file and append/merge it with the default ~/.kube/config file?

why help exits with 1?

https://github.com/ahmetb/kubectx/blob/master/kubectx#L40

Must show colors for the current context in fzf mode

When fzf installed, kubectx v0.6.1 is not showing any colors about current context.

I think we need something like KUBECTX_FORCE_COLOR while invoking fzf. Need to investigate whether --ansi flag on fzf will be a problem or not.

Proposal: rename current context easier with "kubectx <NEW_NAME>=."

This =. syntax would allow users to rename current context without typing its name.

e.g.

{⎈ |gke_ahmetb-samples-playground_us-central1-b_test:default} $ echo hello
hello

{⎈ |gke_ahmetb-samples-playground_us-central1-b_test:default} $ kubectx test=.
Context "gke_ahmetb-samples-playground_us-central1-b_test" renamed to "test".

{⎈ |test:default} $ # happy!

Completions not working with oh-my-zsh on Linux

I am working on Linux with oh-my-zsh and I can't get completions to work.

I have updated my fpath line in ~/.oh-my-zsh/oh-my-zsh.sh to be:
fpath=($ZSH/functions $ZSH/completions /home/username/kubectx/completion $fpath)

When I run echo $fpath, I get the expected output:
... /home/username/kubectx/completion ...

The directory above (/home/username/kubectx/completion) contains only one script, which is the kubectx.zsh script in the repo.

Have I done something wrong in the setup?

tab completion not working

Hey, installed kubectx and kubens via brew on OSX and it works great, thank you! Unfortunately tab completion isn't working for me with either kubectx or kubens in my terminal. Other instances of tab completion work for me, but I probably just have something setup wrong with my terminal. How should I go about getting this to work?

Update homebrew formula with latest changes

Make a PR to the homebrew-core. This PR would:

• add fish completion
• stop installing utils.bash file

Export current config

It is only propose to add a function for export config for a specific cluster to file. What do you think?

Fish completions install incorrectly through homebrew

Performing a brew install kubectx results in the completion files being symlinked to _kubectx and _kubens within the fish vendor completions directory. These don't appear to be getting parsed (I'm using fish 2.7.1, also installed via homebrew).

Moving these files to kubectx.fish and kubens.fish solves this and makes completions available.

(I realize the change will have to be made in the homebrew repository, not this one, but this seemed the right place to open up the issue)

Proposal for deleting contexts: kubectx -d NAME

I'm really sad about all the context entries that accrued in my global KUBECONFIG file after using GKE for a while.

I think we can have a shorthand kubectx -d foo that removes that context, and the associated cluster and user entries in the KUBECONFIG file.

Currently kubectl config delete-context doesn't offer a cascading deletion of the associated user and cluster entries, but I think this command should assume people don't edit kubeconfig file manually, or if they do, they wouldn't use kubectx -d. This also assumes there’s 1:1:1 mapping between "contexts", "users", "clusters" entries.

Renaming must overwrite the existing context name

If there's a context named test, this will fail today:

 kubectx test=gke_ahmetb-samples-playground_us-central1-b_test

I think we should overwrite the existing entry, but the important point here is what to do with users and clusters entry of that context that we'll be deleting. This is to be decided in #23.

[Idea] make it possible to use different contexts/namespaces in multiple shells

What do people following kubectx think of this idea:

We can detect if kubectx command is executed in interactive mode OR eval'ed in a shell (like eval $(kubectx ...), piped elsewhere or redirected to a file, by checking if /dev/stdout is a TTY or not.

If kubectx is evaluated in a shell, we can print an alias that aliases kubectl to kubectl --context=NAME. So when that shell is exited, the default context would go back to what's set before. This would let users work on multiple clusters simultaneously in different terminal tabs. It would look like this:

eval $(kubectx NAME)

and it would print something like alias kubectl=kubectl --context=NAME which then is evaluated in the current shell, therefore creating an alias. Similarly, eval $(kubens ...) would also evaluate an alias kubectl=kubectl --namespace=NAME (these two wouldn't work together, but I might have a solution for that too, by writing a basic bash function that picks up these names from env.

Just an idea. The good old way of using kubectx/kubens would still be around and would continue to work the same way.

kubens should be switching to other namespace when current namespace is deleted

current:

$ kubens
default
kube-public
kube-system
management-ui

$ kubectl delete ns management-ui 
namespace "management-ui" deleted

$ kubens
default
kube-public
kube-system
management-ui

$ kubectl get ns
NAME          STATUS    AGE
default       Active    4d
kube-public   Active    4d
kube-system   Active    4d

Expected:
management-ui namespace should not be listed after it has been deleted.

Looking for volunteers to nominate/submit brew formula to Homebrew core

It is frowned upon for a package owner to submit a formula to Homebrew core formulae repository.

Once this repository reaches 50 stars (which it recently did), I encourage someone from kubectx user community to submit our existing formula` to homebrew-core.

This formula passes the brew audit --new-formula Formula/kubectx.rb check.

kubens command to display current namespace

It would be nice to have a command like kubens current that would return the current namespace. I would like this for instance to add the current namespace to my command prompt.

GitBASH on windows throws character set not supported

$ DEBUG=1 kubectx
+ set -eou pipefail
+ IFS='
        '
+ SELF_CMD=/c/apps/Kubernetes/kubectx
+ KUBECTX=/c/Users/me/.kube/kubectx
+ main
+ [[ 0 -eq 0 ]]
+ [[ -t 1 ]]
+ [[ -z '' ]]
++ type fzf
++ echo 0
+ [[ 0 -eq 0 ]]
+ choose_context_interactive
+ local choice
++ FZF_DEFAULT_COMMAND=/c/apps/Kubernetes/kubectx
++ fzf --ansi
character set not supported
++ true
+ choice=
+ [[ -z '' ]]
+ echo 'error: you did not choose any of the options'
error: you did not choose any of the options
+ exit 1

Does it make sense to add kubecl?

This might be a bit too philosophical, but here it goes.

In kubeconfig, Context is a thing that binds together Cluster, User and Namespace.

We have a kubectx command that mutates global current-context in kubeconfig.
We also have a kubens command that mutates namespace inside the current Context.

So why don't we have a kubecl (name TBD) that mutates cluster inside the current Context?
And maybe even kubeusr (or something) that does the same for user?

---

As far as I understand, the current assumption behind kubectx is that each Context is completely isolated (e.g. minikube vs GKE), so switching between Clusters while keeping User and even Namespace is meaningless.

On the other hand, I'd like to be able to switch between multiple production Clusters while keeping the same User and Namespace. With an extra benefit of not having to create N contexts for managing N clusters.

Do you think such a PR would be a good idea?

Add Debian/Ubuntu packaging

What do you think about building installation packages? I'm interested in Debian/Ubuntu in particular.

Add command-line integration tests with bats

We should use bats test framework and integrate travis CI to test many edge cases etc of the script.

I suspect bugs may be lurking (or occur later in refactoring) in env handling, switching back and forth, storing state etc

KUBECTX_IGNORE_FZF not being respected

If you have fzf installed, but want to opt out of using this feature, set the environment variable KUBECTX_IGNORE_FZF=1.

I have the KUBECTX_IGNORE_FZF var set and it doesn't seem to be respected. I double checked (echo $KUBECTX_IGNORE_FZF) and it is set to 1. I set it in my .bashrc file...

zsh tab completion not working when 2+ contexts

$ kubectx
docker-for-desktop
gke_ahmetb-samples-playground_australia-southeast1-a_eu
gke_ahmetb-samples-playground_us-central1-b_demo
gke_istio-next-2_us-central1-b_demo
gke_istio-next-3_us-central1-b_demo
gke_istio-next-4_us-central1-b_demo
gke_istio-next-4_us-east4-a_east-coast
gke_istio-next-5_us-central1-a_istio-service-mesh
gke_istio-next-5_us-central1-b_demo
gke_istio-next_us-central1-b_demo
gke_microservices-demo-app_us-central1-b_demo-app

but when I do kubectxTabTab I get only two items:

$ kubectx -
-                   docker-for-desktop

which is basically the hardcoded - and the first context in the list.

When I edit the _kubectx script:

  9     _arguments "1: :((- \
 10         "${contexts[@]}" \
 11 |_______))"

to add a hardcoded name like:

  9     _arguments "1: :((- \
 10         "${contexts[@]}" \
 11         hardcoded_cluster
 12 |_______))"

tab completion shows everything correctly.

What's going on here?

doc: how to add new context?

so i have minikube in output, how do i add new "context"?

please add such section to readme.

Kubectx switching removes heptio user from config file

Please let me know if this isn't a bug and I'm just doing something wrong, but I haven't been able to find any info related to this.

So for AWS EKS clusters, Amazon's guide (https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html) tells you to use their heptio authenticator and that your .kube/config should look like:

apiVersion: v1
clusters:
- cluster:
    server: <endpoint-url>
    certificate-authority-data: <base64-encoded-ca-cert>
  name: kubernetes
contexts:
- context:
    cluster: kubernetes
    user: aws
  name: aws
current-context: aws
kind: Config
preferences: {}
users:
- name: aws
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1alpha1
      command: heptio-authenticator-aws
      args:
        - "token"
        - "-i"
        - "<cluster-name>"
        # - "-r"
        # - "<role-arn>"
      # env:
        # - name: AWS_PROFILE
        #   value: "<aws-profile>"

But every time I switch contexts using kubectx it modifies the .kube/config to:

apiVersion: v1
clusters:
- cluster:
    server: <endpoint-url>
    certificate-authority-data: <base64-encoded-ca-cert>
  name: kubernetes
contexts:
- context:
    cluster: kubernetes
    user: aws
  name: aws
current-context: aws
kind: Config
preferences: {}
users:
- name: aws
  user: {}

So it removes the entire heptio auth user part of the config so I have to re-add it manually each time to access my cluster after switching from another context.

kubectx -d: support multiple arguments

I wish to see kubectx -d used to delete multiple commands at once. Ideally I should be able to say:

kubectx -d ctx1 ctx2

to delete multiple contexts.

kubectx must fail when it fails to retrieve namespaces/contexts

when we have

get_contexts() {
  kubectl config get-contexts -o=name | sort -n
}

and we use it like for c in $(get_contexts); do ... it doesn't exit immediately even though set -e is set.

https://stackoverflow.com/questions/44014857/function-invocation-in-for-loop-does-not-fail-even-though-set-e

Ability to set Namespace when switching contexts

When switching a context, it would be nice to be able to set the active (default) namespace for the context as well.

kubectx my-cluster test-namespace

If test-namespace is left off, it would just be ignored.

Support Bash on Windows

I'm using a bash on Windows. kubectl is on the path but as kubectl.exe. I've tried a number of things on my side to get around it (alias, shell hackery, etc) to no avail.

I've submitted a potential fix in #96. Thank you.

Allow setting namespace when no permission to list namespaces

We have users that are only allowed to access single namespace in the cluster with very restricted permissions. It would be nice to have option to set namespace to context even when user doesn't have permission to list all namespaces. Ideally kubens could verify from user if they want to set namespace even if it can't verify the namespace exists or to have a flag like --force to set without verifying.

This it what happens now even if namespace exists but user doesn't have right to list namespaces:

$ kubens helloworld
Error from server (Forbidden): namespaces is forbidden: User "josalmi" cannot list namespaces at the cluster scope: Required "container.namespaces.list" permission.
error: no namespace exists with name "helloworld".

why kubernetes-cli installed via brew?

I already have kubectl in my path via "Docker for Mac"
why brew install kubectx again installing kubernetes-cli ?

kubens cannot switch if user doesn't have container.namespaces.get permission

I use kubectx/kns to switch between multiple GKE clusters spread across multiple Google accounts. Occasionally, I'll switch to a context that my current user is unable to access. When I run kns, I get the following:

$ kns
Error from server (Forbidden): namespaces is forbidden: User "paul@***" cannot list namespaces at the cluster scope: No policy matched.
Required "container.namespaces.list" permission.

How would I go about updating the user that kubectx is using so that it uses the correct user? In the past, I've had to create a whole new context to get it working again.

Add "default" context and/or namespace

Would there be any way to add a "default" namespace and cluster context that kubectx would switch to either after a timeout or in each new bash window?

Primarily to make it harder to accidentally apply something to a production cluster.

[New Release] Cut release 0.5.1

Please release a new version that includes the color configuration. Thanks!

how do I install "manually" completions in Ubuntu?

Any ideas? I can't see anything useful by googling it up.

TERM=vt100 causing empty output

Currently if using something like no color or vt100 terminal you won't see what the current context is... if the terminal supports color it will be bold and a color.

1. For non-color terminals add * to current context?

~ » export TERM=vt100
~ » kubectx
aws
docker-for-desktop
k8s

~ » export TERM=xterm
~ » kubectx
aws
docker-for-desktop
k8s

2. Add option to only print current context (theoretically this and similar option for kubens can be used to add to PS1 prompt)

kubectx --
k8s