kubectl-co

README

= Kubectl-co

image:https://img.shields.io/badge/License-Apache%202.0-blue.svg[link="http://www.apache.org/licenses/LICENSE-2.0"]
image:https://github.com/steffakasid/kubectl-co/actions/workflows/codeql-analysis.yml/badge.svg[link:https://github.com/steffakasid/kubectl-co/actions/workflows/codeql-analysis.yml]
image:https://github.com/steffakasid/kubectl-co/actions/workflows/release.yml/badge.svg[link:https://github.com/steffakasid/kubectl-co/actions/workflows/release.yml]
image:https://github.com/steffakasid/kubectl-co/actions/workflows/go-test.yml/badge.svg[link:https://github.com/steffakasid/kubectl-co/actions/workflows/go-test.yml]

This tool aims to make it easy to manage multiple config files. I know there are alternatives around e.g. `kubectl krew info config-registry` but for me I didn't like the deep structure of the commands. I want something as short as possible. Before I created this tool I used some shell functions to basically do the same: 

[source,bash]
----
setKubeCtx() {
    export KUBECONFIG=$1
    unlink ~/.kube/config
    ln -s $1 ~/.kube/config
    kubectx $2
}

k8s() {
  if [ -z ${1} ]; then
    echo $KUBECONFIG
    ll ~/.kube/config
  else
    if [ $1 = "prod" ]; then
      setKubeCtx ~/.kube/eks-prod.yml eks-prod
    elif [ $1 = "dev" ]; then
      setKubeCtx ~/.kube/eks-dev.yml eks-dev
    elif [ $1 = "poc" ]; then
      setKubeCtx ~/.kube/eks-poc.yml eks-poc
    elif [ $1 = "nextcloud" ]; then
      setKubeCtx ~/.kube/config-nextcloud.yml microk8s
    elif [ $1 = "berlin" ]; then
      setKubeCtx ~/.kube/config-berlin.yml default/berlin/steffenrumpf
      oc project &> /dev/null || oc login | tail -n 2 | head -n 1 | sed -e 's/You must obtain an API token by visiting //g' | xargs open
    elif [ $1 = "madrid" ]; then
      setKubeCtx ~/.kube/config-madrid.yml default/madrid/steffenrumpf
      oc project &> /dev/null || oc login | tail -n 2 | head -n 1 | sed -e 's/You must obtain an API token by visiting //g' | xargs open
    else
      setKubeCtx ~/.kube/eks-test.yml eks-test
    fi
  fi
}
----

Unfortunately this was a bit limited so I decided to write a little go tool and integrate it as plugin into kubectl.

== When to use kubectl-co

kubectl-co is useful when you regularly work with **separate kubeconfig files** rather than a single merged config. Typical scenarios:

* **Multiple clusters with isolated credentials** – e.g. production, staging, and development EKS clusters each with their own kubeconfig file. Switching is a single `kubectl co dev` instead of juggling `KUBECONFIG` exports or manual symlinks.
* **Shared vs. personal clusters** – you maintain a personal homelab config alongside corporate cluster configs and want to toggle between them without risk of mixing contexts.
* **Onboarding new clusters quickly** – `kubectl co --add <name> <path>` registers a new config in one step; no manual file moves or edits required.
* **Quick rollback** – `kubectl co --previous` lets you toggle back to the last-used config instantly, which is handy during incident response when you need to jump between clusters.
* **OpenShift cluster sprawl** – `oc login` adds a new context _and_ namespace entry to your kubeconfig for every project you touch, quickly bloating a single file. Keeping each OpenShift cluster in its own config file via kubectl-co prevents that noise from leaking into your other clusters.
* **Avoiding credential conflicts from merged configs** – merging kubeconfig files via `KUBECONFIG=file1:file2` silently breaks when two files define the same user name (e.g. both use `kubernetes-admin`). kubectl-co never merges; each file stays independent, so conflicting names are not a problem.
* **CI scripts or dotfile setups** – the deterministic symlink approach (`~/.kube/config` always points to one file) works well in automation where `KUBECONFIG` merging would add complexity.

NOTE: https://github.com/ahmetb/kubectx[kubectx] solves a different problem: it switches _contexts_ inside a single (merged) kubeconfig file. kubectl-co switches _files_ — keeping credentials fully isolated. If all your clusters live in one kubeconfig and you just need fast context switching, kubectx is the right tool. If you want each cluster in its own file, kubectl-co is the right tool.


== Usage

[source,sh]
----
  kubectl co [flags]
  kubectl-co [flags]
----

NOTE: If you set the KUBECONFIG environment var this will always take precedence before the config file.

== Installation

Using https://brew.sh[Homebrew]:

[source,sh]
----
brew install steffakasid/kubectl-co/kubectl-co
----

Or download the binary from https://github.com/steffakasid/kubectl-co/releases[GitHub Releases] and place it in your `$PATH`.

== Prerequisites

kubectl should be installed (even if the application would also run on its own as `kubectl-co`)

== Examples

[source, sh]
----
  kubectl co --add new-config ~/.kube/config    - adds your current kubeconfig to be used by co with the name 'new-config'
  kubectl co --add completly-new                - adds a plain new config file which must be initialised afterwards
  kubectl co --previous                         - switch to previous config and set current config to previous
  kubectl co --delete config-name               - delete config with name 'config-name'
  kubectl co --current                          - show the current config path
  kubectl co new-config                         - switch to 'new-config' this will overwrite ~/.kube/config with a symbolic link
  kubectl co                                    - list all available configs
----

== Flags:
  -a, --add:: Add a new given config providing the name and optionally the path to copy from. Usage: `kubectl co --add <configname> [configpath]`
  -c, --current:: Show the current config path
  -d, --delete:: Delete the config with the given name. Usage: `kubectl co --delete <configname>`
  -p, --previous:: Switch to previous config
  --debug:: Turn on debug output
  --version:: Show version information

== Configuration

kubectl-co can be configured via flags, environment variables, or a config file at `~/.config/kubectl-co/config.yaml`.

.Environment variables
[source,sh]
----
# Prefix all config keys with KUBECTL_CO_
export KUBECTL_CO_DEBUG=true
----

== Shell completion

.Manually enable shell completion
[source,sh]
----
# bash
source <(kubectl-co completion bash)

# zsh (use bash completion)
source <(kubectl-co completion zsh)
----

.Or add to your shell rc file:
[source,sh]
----
# ~/.bashrc
echo 'source <(kubectl-co completion bash)' >> ~/.bashrc

# ~/.zshrc
echo 'source <(kubectl-co completion zsh)' >> ~/.zshrc
----

== TODO

* Publish Homebrew formula updates through one shared tap repository for all projects.

Documentation

Overview

Copyright © 2022 steffakasid