ksw

Kubeconfig SWitcher

ksw is a fast and lightweight Go CLI tool to switch Kubernetes contexts by starting a new shell with an isolated kubeconfig file. This allows different terminals to use different contexts concurrently without interfering with each other.

Why ksw?

I wanted a kubeconfig switcher that is simple (as in Unix philosophy) and integrates easily with my existing ZSH and Prezto setup without getting in the way. It also needs to work with other Kubernetes tools without many changes.

Other solutions I tried:

• kubectx / kubens: Changing the context in one terminal changes it everywhere.
• kubie: It does too much and broke my ZSH setup.
• kube_ps1: I still use it to show the current context alongside ksw.

Features

• Isolated contexts per terminal: Work with different Kubernetes contexts across multiple terminals simultaneously.
• No nested shells: Switching contexts in an active session updates the config file in-place instead of spawning new shells.
• Fuzzy finder: Shows a fuzzy finder to select a context if no exact match is specified.
• Optional minification: Can strip unused clusters, contexts, and users from the temporary kubeconfig.

Installation

brew install chickenzord/tap/ksw

Alternatively, install from source:

go install github.com/chickenzord/ksw

Configuration

ksw loads configuration from ~/.config/ksw/config.yaml or ~/.ksw.yaml (fallback).

kubeconfig:
  # When true, extracts only the cluster, user, and context needed for the active context.
  # Defaults to false, which preserves other contexts but updates current-context.
  minify: false

  # Directory to store generated session kubeconfigs.
  # Defaults to ~/.ksw/sessions.
  sessions_dir: ~/.ksw/sessions

How it works

ksw [context-name]

First time (not in a ksw session):

1. Loads kubeconfig from these locations (in order):
   • Path set in KSW_KUBECONFIG_ORIGINAL
   • Path set in KUBECONFIG
   • Default location $HOME/.kube/config
2. Evaluates configuration options. If minify is enabled, extracts only the cluster, user, and context for the specified context. Otherwise, copies the config and updates the current-context.
3. Writes the isolated config to a session file under ~/.ksw/sessions (named <context>.<pid>.yaml).
4. Replaces the ksw process with your shell using syscall.Exec(), setting KUBECONFIG to the session file.
5. Your shell now uses the isolated context.

When already in a ksw session:

1. Running ksw [another-context] detects you are already in a session.
2. Updates the existing session kubeconfig file in-place.
3. Returns immediately. Kubectl sees the new context right away without spawning new shells.

Environment variables set in the shell:

• KSW_KUBECONFIG_ORIGINAL: Path to your original kubeconfig file
• KSW_KUBECONFIG: Path to the isolated session kubeconfig
• KUBECONFIG: Same as KSW_KUBECONFIG
• KSW_ACTIVE: Always set to "true" when in a ksw session
• KSW_SHELL: Path to your shell (e.g. /bin/zsh)

Limitations

• No automatic prompt indicator. Use the environment variables (KSW_ACTIVE, KSW_KUBECONFIG_ORIGINAL) in your prompt setup.
• Primarily tested on ZSH on Darwin Arm64.