kubeconfig-bikeshed

kubeconfig-bikeshed - kbs - is an opinionated tool to manage your kubeconfigs for accessing many Kubernetes APIs. Instead of managing a single kubeconfig file with many contexts, kbs maintains many kubeconfig files that can easily be switched between.

See the demo below for a typical kbs workflow (this assumes that all optional shell integration is set up):

Why kbs?

kbs can help restoring order to a scattered and inconsistent collection of kubeconfigs. It does so by enforcing standardized naming, by taking ownership of its kubeconfigs and by allowing to apply bulk operations like purging outdated kubeconfigs.

kbs maintains a kubeconfig "data store", which by default is located in ~/.config/kbs (kbs is aware of XDG_CONFIG_HOME and looks for the store directory in $XDG_CONFIG_HOME/kbs if it is set). For kubeconfigs imported into its store, kbs allows to set and update labels (just like on Kubernetes objects) that can be used to run bulk operations.

When it comes to naming standards, the core idea of kbs is that not all Kubernetes deployment tools generate "good" context names. Therefore, kbs automatically discovers the server name from a kubeconfig that is being imported, and uses that to identify any conflicts with existing kubeconfigs and to set a meaningful context name. This can be overridden, but kbs expects all names to be valid DNS-style names.

There is also a blog post that gets into details of the initial version and the motivation to start this project: Bikeshedding Kubeconfig Management.

Installation

kubeconfig-bikeshed can be installed as a standalone binary called kbs. Optionally, a kbs shell function that overrides the binary call can be loaded into some shells to allow selecting an active kubeconfig (see Setup).

Options

kbs can currently be installed via Homebrew, cargo or downloaded from the releases page.

Homebrew

kbs is available from my tap:

$ brew tap embik/tap
$ brew install kubeconfig-bikeshed

Cargo

kubeconfig-bikeshed is also directly available from crates.io and can be installed via cargo (if a working Rust toolchain is installed):

$ cargo install kubeconfig-bikeshed

This will install the kbs binary. Make sure $HOME/.cargo/bin is in your PATH.

Setup

After installing kbs, a few things can be set up for smoother usage of it. To change between contexts and namespaces, it is recommended to also install fubectl.

Autocompletion

kbs can generate shell autocompletion for many available shells via the kbs shell completion command. Specific instructions might differ by shell. For example, to install the zsh autocompletion, add the following snippet to your .zshrc:

source <(kbs shell completion zsh)

"Magic" Shell Functions

One of the most important features of a kubeconfig manager might be the ability to set the environment variable KUBECONFIG to point to a kubeconfig file of your choice. Unfortunately, the kbs binary on its own cannot provide that feature as it cannot set environment variables for the active shell.

To remedy that, kbs optionally provides shell "magic" that replaces the kbs binary in your shell with a function that can export KUBECONFIG. This requires fzf to be installed. Shell magic is supported for a subset of shells, the currently supported shells are:

• zsh
• bash

Specific instructions might differ by shell as well, e.g. to install the zsh magic you can add the following snippet to your .zshrc:

source <(kbs shell magic zsh)

Restore Last Active Kubeconfig

To start new shells with the last selected ("active") kubeconfig, add the following snippet (or similar, depending on your shell) to your login shell configuration (e.g. .zshrc):

eval $(kbs use -)

Usage

To select a kubeconfig from the kbs data store, simply run kbs (if shell integration is all set up). This will offer a selection via fzf and export the KUBECONFIG environment variable.

Full set of commands for kbs below.

Usage: kbs [OPTIONS] <COMMAND>

Commands:
  import   Import a kubeconfig into data store [aliases: i]
  list     List available kubeconfigs [aliases: ls]
  use      Use a kubeconfig by name and print shell snippet to source [aliases: u]
  shell    Print various shell related scripts [aliases: sh]
  remove   Remove kubeconfig from data store [aliases: rm, delete]
  version  Print version [aliases: v]
  label    Manage labels on kubeconfigs in the data store [aliases: l]
  prune    Remove kubeconfigs for Kubernetes API servers that are no longer accessible [aliases: p]
  move     Rename a kubeconfig in store [aliases: mv]
  help     Print this message or the help of the given subcommand(s)

Options:
  -v, --verbose                  Enable verbose (debug) logging
  -c, --config-dir <config-dir>  Directory to use for configuration and data store. Defaults to ~/.config/kbs or $XDG_CONFIG_DIR/kbs
  -h, --help                     Print help

Importing Kubeconfigs

kbs import allows to import a kubeconfig already existing on the local filesystem (e.g. because it was downloaded via a third-party tool or a web interface) into the kbs "data store".

The command takes a couple of flags to alter behaviour of the import process. When a kubeconfig has multiple severs configured, passing a --name might be necessary as kbs cannot determine a name automatically.

Updating Kubeconfig Labels

kbs label allows setting new labels or updating existing labels on a kubeconfig identified by name or by label selector. Labels can be passed as key=value pairs, separated by comma.

Existing label values can only be updated if --overwrite is set, mimicking kubectl behaviour.

Removing Kubeconfigs

kbs remove allows deleting kubeconfigs by name (or label selector) from the kbs data store.

Pruning Kubeconfigs

kbs prune is a helpful command in case removing kubeconfigs by hand or label selector proves cumbersome.

kbs will iterate over all kubeconfigs matched by the label selector passed to kbs prune (if none is passed, all kubeconfigs will be checked) and attempt to fetch the Kubernetes API server version from the remote server as a way to "ping" it. If that connection fails for whatever reason, kbs prune will consider the kubeconfig in question stale.

By default, this command runs in "dry mode", which means it will not delete any kubeconfigs (as this is a destructive action potentially elevated by temporary networking problems). To actually prune kubeconfigs, pass --dry-run=false to the command.

Alternatives

• konf-go by my colleague Simon, if you are looking for a more mature solution written in Go.
• kubecm is probably the "top dog" of kubeconfig managers.