DOCSEARCHbyAlgolia
Submit Docs

Kubeswitch

repository·master·Indexed 22 days ago

https://github.com/danielfoehrkn/kubeswitch

A high-performance Kubernetes context switcher and drop-in replacement for kubectx. It features terminal window isolation by using temporary Kubeconfig copies instead of modifying original files, unified search across providers like EKS, GKE, and Vault, and a flexible hook system for automating Kubeconfig organization. Supports context aliasing, wildcard searches, and executing commands across multiple clusters via the switch exec command.

Tokens
22.7K
Snippets
83
Records
120
Agent score
77%

What's inside kubeswitch

  1. Extend kubeswitch with Hooks

    master
    You can customize kubeswitch behavior using Hooks, which function similarly to Git pre-commit hooks. Hooks allow you to execute an arbitrary executable or command at specific intervals (e.g., every 6 hours) prior to performing a search. This is useful for automating the organization of Kubeconfig files into searchable directory structures.

  2. Handle expired GKE credentials

    master
    Kubeswitch reuses valid JWT tokens obtained via the gcloud OIDC flow. Because these tokens expire, Kubeswitch is designed to detect failed requests against the GCP API. When an expiration is detected, Kubeswitch automatically triggers a re-authentication via gcloud, which will open your default web browser to complete the flow.

  4. Configure multiple indexed stores with unique IDs

    master

    When using an index for multiple stores of the same kind (e.g., multiple filesystem stores), you must provide a unique id for each store. This allows kubeswitch to create separate index files and refresh them individually.

    If a store is the only one of its kind using an index (e.g., a single Vault store), it uses the default id _default.

    kind: SwitchConfig
version: v1alpha1
refreshIndexAfter: 1h
kubeconfigStores:
  - kind: filesystem
    id: unique-1
    paths:
    - "~/.kube/static-kubeconfigs/"
  - kind: filesystem
    id: unique-2
    paths:
    - "~/.kube/next-kubeconfigs/"
  - kind: Vault
    paths:
    - "path/in/vault"

  5. Search cryptic context names using parent directory paths

    master

    When Kubernetes context names are cryptic or generated (e.g., by CI systems), kubeswitch allows you to identify them by including the direct parent path name in the fuzzy search.

    To use this feature, organize your Kubeconfig files into a directory structure where the parent directory name provides meaningful context. For example:

    .kube/my-path
├── canary
│   └── config
├── dev
│   ├── config
│   └── config-tmp
└── live
    └── config

    In this layout, searching for dev will include contexts found within the dev/ directory. You can manually create this layout or use Hooks to automate it.

  6. How Kubeswitch works

    master

    Kubeswitch operates through a two-component system designed to provide terminal-isolated Kubernetes context switching. It uses a shell function to manage environment variables and a Go binary to handle the logic of context selection.

    Components

    • switch.sh: A shell script containing the switch() function. This is the user-facing entry point.
    • switcher: A Go binary that performs the heavy lifting: searching kubeconfig stores, providing a fuzzy search interface, and manipulating kubeconfig files.

    Execution Flow

    1. The user runs the switch command (provided by the switch() shell function).
    2. switch.sh locates the switcher binary in the user's $PATH and executes it.
    3. The switcher binary searches for kubeconfigs defined in the SwitchConfig file.
    4. A fuzzy search interface is displayed to the user to select a context name.
    5. Once a context is selected, switcher creates a temporary copy of that kubeconfig, sets the current-context within it, and saves it to ~/.kube/switch_tmp.
    6. switcher outputs the path of this temporary file to STDOUT.
    7. switch.sh captures the path and executes export KUBECONFIG=<path/to/tmp/kubeconfig/file>.

    Terminal Isolation

    Because the KUBECONFIG environment variable is exported within the shell session where switch was called, each terminal window operates on its own independent temporary copy of the kubeconfig. Switching contexts in one terminal does not affect other open terminals.

  7. How the Search Index works in Kubeswitch

    master

    The search index is a local file stored in the state directory (default: ~/.kube/switch-state/switch.<store>.<id>.index). It maps all discovered kubecontext names across all kubeconfig stores to their respective kubeconfig file paths.

    Instead of querying the kubeconfig store directly, Kubeswitch queries this index. This provides several benefits:

    • Performance: Significantly faster when dealing with large amounts of Kubeconfigs where querying the store (e.g., searching a large directory) is slow.
    • Efficiency: Reduces API requests when using stores that query an external API (such as Vault or Gardener).
    • Speed: Contexts become available almost instantly compared to standard loading.

    Note: Because the index is a snapshot, search results may be outdated if kubeconfigs were added or deleted since the last refresh. The index is not used by default.

  8. Understand Hook State and Storage

    master

    Kubeswitch tracks the last execution time of hooks to manage intervals. This state is stored in files within a state directory.

    • Default State Directory: ~/.kube/switch-state
    • Custom State Directory: Can be specified using the --state-directory flag when running switch commands.

    By maintaining these state files, Kubeswitch can accurately calculate the NEXT EXECUTION time shown in the switch hooks ls command.

  9. Understand Terminal Window Isolation in kubeswitch

    master

    A key difference between kubeswitch and kubectx is how they handle context switching:

    • kubectx: Modifies the original Kubeconfig file. This affects all terminal windows using that same Kubeconfig.
    • kubeswitch: Does not modify the original Kubeconfig. Instead, it creates a temporary copy of the Kubeconfig file to set the context. This provides terminal window isolation, allowing different terminal sessions to operate on different contexts without interfering with each other.

  10. Precedence rules for CLI flags and SwitchConfig

    master

    When using both the command line and a SwitchConfig file, the following precedence rules apply:

    • The --vault-api-address flag takes precedence over the vaultAPIAddress field in the config file.
    • Specifying --kubeconfig-path via the CLI and kubeconfigPaths in the config file results in a combined search over all those paths.

  11. Search for GKE clusters

    master

    Kubeconfig context names for GKE clusters follow a specific naming convention that allows for fuzzy searching.

    Naming Convention: gke_<account-name>-<region/zone>-<cluster-name>/gke_<cluster-name>

    Example: gke_sweet-account-europe-west2-a-sweet-cluster/gke_sweet-cluster

    • Account name: sweet-account
    • Location (zone/region): europe-west2-a
    • Cluster name: sweet-cluster

    You can also define an alias for each context to create more memorable or queryable names.

  12. Use the Preview functionality in Gardener search

    master

    When searching, Kubeswitch can show a preview containing metadata such as the Gardener landscape, the Seed name where the Shoot's control plane runs, and the Shoot name.

    Warning: Enabling preview causes additional requests against the Gardener API server, even if a search index is being used.

    To disable this feature, use the flag: --show-preview false