README
¶
Kubeswitch
The kubectx for operators.
kubeswitch (lazy: switch) is the single pane of glass for all of your kubeconfig files.
Caters to operators of large scale Kubernetes installations.
Designed as a drop-in replacement for kubectx.
Highlights
- Unified search over multiple providers
- Amazon Elastic Kubernetes Service (EKS)
- Azure Kubernetes Service (AKS)
- DigitalOcean Kubernetes (DOKS)
- Gardener
- Google Kubernetes Engine (GKE)
- Hashicorp Vault
- Local filesystem
- OVH
- Rancher
- Scaleway (documentation tbd)
- Akamai / Linode
- Cluster API (capi)
- Your favorite Cloud Provider or Managed Kubernetes Platform is not supported yet? Looking for contributions!
- Change the namespace
- Change to any context and namespace from the history
- Terminal Window Isolation
- Each terminal window can target a different cluster (does not overwrite the current-context in a shared Kubeconfig)
- Each terminal window can target the same cluster and set a different namespace preference
- Efficiency: uses local caches for kubeconfig contexts and namespaces
- Advanced Search Capabilities
- Hot reload capability (adds Kubeconfigs to the search on the fly - especially useful when searching large directories)
- Live preview of the selected Kubeconfig file (sanitized from credentials)
- Recursive search (e.g. on the local filesystem or in Vault)
- Easily find clusters with cryptic context names
- Easy Navigation
- Define alias names for contexts without changing the underlying Kubeconfig
- Extensibility
- Integrate custom functionality using Hooks (comparable with Git pre-commit hooks).
- Build your own integration e.g., synchronise Kubeconfig files of clusters from Git or remote systems.
Non-goals
- To provide a customized shell prompt. Use kube-ps1.
Installation
Kubeswitch can be installed using brew for OSX, MacPorts, from Github Releases or from source.
Please see the documentation.
Usage
$ switch -h
The kubectx for operators.
Usage:
switch [flags]
switch [command]
Available Commands:
alias Create an alias for a context. Use ALIAS=CONTEXT_NAME
clean Cleans all temporary and cached kubeconfig files
completion Generate the autocompletion script for the specified shell
exec Execute any command towards the matching contexts from the wildcard search
gardener gardener specific commands
help Help about any command
history Switch to any previous tuple {context,namespace} from the history
hooks Run configured hooks
list-contexts List all available contexts
namespace Change the current namespace
set-context Switch to context name provided as first argument
set-last-context Switch to the last used context from the history
set-previous-context Switch to the previous context from the history
version show switch version info
Flags:
--config-path string path on the local filesystem to the configuration file. (default "/Users/tommyolsen/.kube/switch-config.yaml")
--debug show debug logs
-h, --help help for switch
--kubeconfig-name string only shows kubeconfig files with this name. Accepts wilcard arguments '*' and '?'. Defaults to 'config'. (default "config")
--kubeconfig-path string path to be recursively searched for kubeconfigs. Can be a file or a directory on the local filesystem or a path in Vault. (default "$HOME/.kube/config")
--no-index stores do not read from index files. The index is refreshed.
--show-preview show preview of the selected kubeconfig. Possibly makes sense to disable when using vault as the kubeconfig store to prevent excessive requests against the API. (default true)
--state-directory string path to the local directory used for storing internal state. (default "/Users/tommyolsen/.kube/switch-state")
--store string the backing store to be searched for kubeconfig files. Can be either "filesystem" or "vault" (default "filesystem")
--vault-api-address string the API address of the Vault store. Overrides the default "vaultAPIAddress" field in the SwitchConfig. This flag is overridden by the environment variable "VAULT_ADDR".
-v, --version version for switch
Use "switch [command] --help" for more information about a command.
Just type switch to search over the context names defined in the default Kubeconfig file ~/.kube/config
or from the environment variable KUBECONFIG.
To recursively search over multiple directories, files and Kubeconfig stores, please see the documentation to set up the necessary configuration file.
Change namespace
Change the current namespace using switch ns
Uses a self-updating local namespace cache for instant search results.
History
Similar to the command histories of a shell, switch keeps a history of used contexts and namespaces.
A history entry is always a tuple of {context-name, namespace}.
This allows to jump back to any context and namespace in the history.
In addition, use
switch .to change to the last used context and namespace (handy for new terminals)switch -to change to the previous history entry
List and search for contexts
You can list all your indexed contexts by issuing the following command: switch list-contexts.
And if you want to search for only parts of those contexts, you can use wildcard search:
switch list-contexts "*-dev-?"
Wildcard search supports matching wildcards notation also known as globbing:
?matches exactly one occurrence of any character.*matches arbitrary many (including zero) occurrences of any character.
Execute commands
You can use the above wildcard search to execute any commands towards the matching clusters. This makes it powerful for quickly running a command through a given set of clusters and see the output of these commands:
switch exec "*-dev-?" -- kubectl get ns
You can also wrap the command(s) into a script and execute it via switch exec:
switch exec "*-dev-?" -- bash script.sh
For inline shell script execution, you need to specify the default shell in the SwitchConfig file:
# ~/.kube/switch-config.yaml
kind: SwitchConfig
execShell: "/bin/bash"
Then you can run shell commands like so:
# executes /bin/bash -c 'for i in 1 2 3; do sleep 1; echo "hi $i"; done'
switch exec "*-dev-?" -- 'for i in 1 2 3; do sleep 1; echo "hi $i"; done'
Kubeconfig stores
Multiple Kubeconfig stores are supported.
The local filesystem is the default store and does not require any additional setup.
However, if you intend to search for all Kubeconfig context/files in the ~/.kube directory,
please first consider this.
To search over multiple directories and setup Kubeconfig stores (such as Vault), please see here.
Kubeconfig cache
A cache for kubeconfig files can be added to a store to prevent loading from remote on each invocation of kubeswitch.
The kubeconfig file will be cached after first download.
To see how to configure the cache, please see here.
Transition from Kubectx
Offers a smooth transition as kubeswitch is a
drop-in replacement for kubectx.
You can set an alias and keep using your existing setup.
alias kubectx='switch'
alias kctx='switch'
However, that does not mean that kubeswitch behaves exactly like kubectx.
Please see here to read about some main differences to kubectx.
Alias
An alias for any context name can be defined. An alias does not modify or rename the context in the kubeconfig file, instead it is just injected for the search.
Define an alias.
$ switch alias mediathekview=gke_mediathekviewmobile-real_europe-west1-c_mediathekviewmobile
It is also possible to use switch alias <alias>=. to create an alias for the current context.
See the created alias
$ switch alias ls
+---------------+-------------------------------------------------------------------------------+
| ALIAS | CONTEXT |
+---------------+-------------------------------------------------------------------------------+
| mediathekview | mediathekview/gke_mediathekviewmobile-real_europe-west1-c_mediathekviewmobile |
+---------------+-------------------------------------------------------------------------------+
| TOTAL | 1 |
+---------------+-------------------------------------------------------------------------------+
Remove the alias
$ switch alias rm mediathekview
Caching
See here how to use a search index (cache) to speed up search operations. Using the search index is especially useful when
- dealing with large amounts of Kubeconfigs and querying the Kubeconfig store is slow (e.g. searching a large directory)
- when using a remote systems (such as Vault) as the Kubeconfig store to increase search speed, reduce latency and save API requests
Hot Reload
For large directories with many Kubeconfig files, the Kubeconfigs are added to the search set on the fly. For smaller directory sizes, the search feels instantaneous.
Search cryptic context names
Unfortunately operators sometimes have to deal with cryptic or generated kubeconfig context names that make it hard to guess which Kubernetes cluster this kubeconfig context actually points to. For example, these could be temporary CI clusters.
Without having to manually change the Kubeconfig file, kubeswitch makes it easier to identify
the right context name by including the direct parent path name in the fuzzy search.
This way, the directory layout can actually convey information useful for the search.
To exemplify this, look at the path layout below.
Each Kubernetes landscape (called dev, canary and live) have their own directory containing the Kubeconfigs
of the Kubernetes clusters on that landscape.
Every Kubeconfig is named config.
$ tree .kube/my-path
.kube/my-path
├── canary
│ └── config
├── dev
│ ├── config
│ └── config-tmp
└── live
└── config
This is how the search looks like for this directory. The parent directory name is part of the search.
You can either manually create such a path layout and place the kubeconfigs, or write a custom hook (script / binary) to do that prior to the search.
Extensibilty
Customization is possible by using Hooks (think Git pre-commit hooks).
Hooks can call an arbitrary executable or execute commands at a certain time (e.g every 6 hours) prior to the search via kubeswitch.
For more information take a look here.
Difference to kubectx
kubectx is great when dealing with few Kubeconfig files - however lacks support when
operating large Kubernetes installations where clusters spin up on demand,
have cryptic context names or are stored in various kubeconfig stores (e.g., Vault).
kubeswitch is build for a world where Kubernetes clusters are treated as cattle, not pets.
This has implications on how Kubeconfig files are managed.
kubeswitch is fundamentally designed for the modern Kubernetes operator of large dynamic Kubernetes
installations with possibly thousands of Kubeconfig files in various locations.
Has build-in
- convenience features (terminal window isolation, context history, context aliasing, improved search experience, sanitized Kubeconfig preview);
- advanced search capabilities (search index, hot reload);
- as well as integration points with external systems (hooks).
In addition, kubeswitch is a drop-in replacement for kubectx.
You can set an alias and keep using your existing setup.
alias kubectx='switch'
alias kctx='switch'
However, that does not mean that kubeswitch behaves exactly like kubectx.
Alias Names
kubectx supports renaming context names using kubectx <NEW_NAME>=<NAME>.
Likewise, use switch <NEW_NAME>=<NAME> to create an alias.
An alias does not modify or rename the context in the kubeconfig file.
It is just a local configuration that can be removed again via switch alias rm <NAME>.
Directly modifying the Kubeconfig is problematic:
- Common tooling might be used across the team which needs to rely on predictable cluster naming conventions
- Modifying the file is not always possible e.g., when the Kubeconfig is actually stored in a Vault
- No easy way to revert the alias or see aliases that are currently in use
Terminal Window isolation
kubectx directly modifies the kubeconfig file to set the current context.
This has the disadvantage that every other terminal using the same
Kubeconfig file (e.g, via environment variable KUBECONFIG) will also be affected and change the context.
A guideline of kubeswitch is to not modify the underlying Kubeconfig file.
Hence, a temporary copy of the original Kubeconfig file is created and used to modify the context.
This way, each terminal window works on its own copy of the Kubeconfig file and cannot interfere with each other.
Limitations
Please make sure there are no kubeconfig files that have the same context name within one directory. Define multiple search paths using the configuration file.
Future Plans
- Support more Cloud Providers and Managed Kubernetes Platforms
Directories