mirror of
https://github.com/ahmetb/kubectx.git
synced 2025-07-06 12:06:13 +00:00
b5daf2cef7
* feat(kubens): added force flag to switch namespaces even if it doesn't exist * Merged lines * fixed README.md and flags.go * updated flags.go, flags_test.go
312 lines
10 KiB
Markdown
312 lines
10 KiB
Markdown
# `kubectx` + `kubens`: Power tools for kubectl
|
|
|
|
|
|
|
|
|
|
[/badge.svg)](https://github.com/ahmetb/kubectx/actions?query=workflow%3A"Go+implementation+(CI)")
|
|
|
|
|
|
This repository provides both `kubectx` and `kubens` tools.
|
|
[Install →](#installation)
|
|
|
|
## What are `kubectx` and `kubens`?
|
|
|
|
**kubectx** is a tool to switch between contexts (clusters) on kubectl
|
|
faster.<br/>
|
|
**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
|
|
|
|
```sh
|
|
# 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".
|
|
|
|
# change the active namespace even if it doesn't exist
|
|
$ kubens not-found-namespace --force
|
|
Context "test" set.
|
|
Active namespace is "not-found-namespace".
|
|
---
|
|
$ kubens not-found-namespace -f
|
|
Context "test" set.
|
|
Active namespace is "not-found-namespace".
|
|
```
|
|
|
|
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 <kbd>Tab</kbd> 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
|
|
→**](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)
|
|
- [with MacPorts (macOS)](#macports-macos)
|
|
- [with apt (Debian)](#apt-debian)
|
|
- [with pacman (Arch Linux)](#pacman-arch-linux)
|
|
- [with Chocolatey (Windows)](#windows-installation-using-chocolatey)
|
|
- [Windows Installation (using Scoop)](#windows-installation-using-scoop)
|
|
- [with winget (Windows)](#windows-installation-using-winget)
|
|
- [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].
|
|
|
|
[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
|
|
or install the scripts [manually](#manual-installation-macos-and-linux).
|
|
|
|
```sh
|
|
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](https://brew.sh/) you can install like this:
|
|
|
|
```sh
|
|
brew install kubectx
|
|
```
|
|
|
|
This command will set up bash/zsh/fish completion scripts automatically. Make sure you [configure your shell](https://docs.brew.sh/Shell-Completion) to load completions for installed Homebrew formulas.
|
|
|
|
|
|
### MacPorts (macOS)
|
|
|
|
If you use [MacPorts](https://www.macports.org) you can install like this:
|
|
|
|
```sh
|
|
sudo port install kubectx
|
|
```
|
|
|
|
### apt (Debian)
|
|
|
|
``` bash
|
|
sudo apt install kubectx
|
|
```
|
|
Newer versions might be available on repos like
|
|
[Debian Buster (testing)](https://packages.debian.org/buster/kubectx),
|
|
[Sid (unstable)](https://packages.debian.org/sid/kubectx)
|
|
(_if you are unfamiliar with the Debian release process and how to enable
|
|
testing/unstable repos, check out the
|
|
[Debian Wiki](https://wiki.debian.org/DebianReleases)_):
|
|
|
|
|
|
### pacman (Arch Linux)
|
|
|
|
Available as official Arch Linux package. Install it via:
|
|
|
|
```bash
|
|
sudo pacman -S kubectx
|
|
```
|
|
|
|
### Windows Installation (using Chocolatey)
|
|
|
|
Available as packages on [Chocolatey](https://chocolatey.org/why-chocolatey)
|
|
```pwsh
|
|
choco install kubens kubectx
|
|
```
|
|
|
|
### Windows Installation (using Scoop)
|
|
|
|
Available as packages on [Scoop](https://scoop.sh/)
|
|
```pwsh
|
|
scoop bucket add main
|
|
scoop install main/kubens main/kubectx
|
|
```
|
|
|
|
### Windows Installation (using winget)
|
|
|
|
Available as packages on [winget](https://learn.microsoft.com/en-us/windows/package-manager/)
|
|
```pwsh
|
|
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:
|
|
|
|
``` bash
|
|
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](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`):
|
|
|
|
```
|
|
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`.
|
|
|
|
#### 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`](https://github.com/ohmyzsh/ohmyzsh):
|
|
|
|
```bash
|
|
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`](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.
|
|
|
|
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)
|
|
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`
|
|
|
|
```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`](https://github.com/junegunn/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](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
|
|
```
|
|
|
|
Colors in the output can be disabled by setting the
|
|
[`NO_COLOR`](https://no-color.org/) environment variable.
|
|
|
|
-----
|
|
|
|
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
|
|
|
|
[](https://starchart.cc/ahmetb/kubectx)
|
|
 <!-- TODO broken since Aug 2021 as igrigorik left Google -->
|