mirror of
https://github.com/ahmetb/kubectx.git
synced 2025-07-03 18:46:12 +00:00
overhaul the readme
Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>
This commit is contained in:
Ahmet Alp Balkan
parent
bdb1ea9e9d
commit
207dd606bb
167
README.md
167
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.<br/>
|
||||
**kubens** is a tool to switch between Kubernetes namespaces (and
|
||||
configure them for kubectl) easily.
|
||||
|
||||
Here's a **`kubectx`** demo:
|
||||
|
||||
|
||||
**`kubens`** helps you switch between Kubernetes namespaces smoothly:
|
||||
...and here's a **`kubens`** demo:
|
||||
|
||||
|
||||
# kubectx(1)
|
||||
|
||||
kubectx is a utility to manage and switch between kubectl(1) contexts.
|
||||
|
||||
```
|
||||
USAGE:
|
||||
kubectx : list the contexts
|
||||
kubectx <NAME> : switch to context <NAME>
|
||||
kubectx - : switch to the previous context
|
||||
kubectx -c, --current : show the current context name
|
||||
kubectx <NEW_NAME>=<NAME> : rename context <NAME> to <NEW_NAME>
|
||||
kubectx <NEW_NAME>=. : rename current-context to <NEW_NAME>
|
||||
kubectx -d <NAME> : delete context <NAME> ('.' 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 <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.
|
||||
|
||||
-----
|
||||
|
||||
# kubens(1)
|
||||
|
||||
kubens is a utility to switch between Kubernetes namespaces.
|
||||
|
||||
```
|
||||
USAGE:
|
||||
kubens : list the namespaces
|
||||
kubens <NAME> : 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 <kbd>Tab</kbd> 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 <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
|
||||
|
||||
> **🥳📰 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)
|
||||
@ -105,15 +79,18 @@ There are several installation options:
|
||||
- [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,9 +197,13 @@ 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.
|
||||
|
||||
@ -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`.
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
[](https://starchart.cc/ahmetb/kubectx)
|
||||
|
||||
 <!-- TODO broken since Aug 2021 as igrigorik left Google -->
|
||||
|
||||
Loading…
Reference in New Issue
Block a user