{"id":13524281,"url":"https://github.com/danielfoehrKn/kubeswitch","last_synced_at":"2025-04-01T02:31:18.294Z","repository":{"id":37601158,"uuid":"230920758","full_name":"danielfoehrKn/kubeswitch","owner":"danielfoehrKn","description":"The kubectx  for operators.","archived":false,"fork":false,"pushed_at":"2025-03-18T00:06:44.000Z","size":190410,"stargazers_count":961,"open_issues_count":39,"forks_count":87,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-31T19:05:45.674Z","etag":null,"topics":["kubeconfig","kubecontext","kubectx","kubernetes","kubeswitch"],"latest_commit_sha":null,"homepage":"https://danielfoehrkn.medium.com/the-case-of-kubeswitch-aff4b6a04ae7","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielfoehrKn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-30T13:27:12.000Z","updated_at":"2025-03-27T14:28:52.000Z","dependencies_parsed_at":"2023-02-19T03:00:28.783Z","dependency_job_id":"b1a857d6-ceb4-4406-bbbb-c2bcc22905d7","html_url":"https://github.com/danielfoehrKn/kubeswitch","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfoehrKn%2Fkubeswitch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfoehrKn%2Fkubeswitch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfoehrKn%2Fkubeswitch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielfoehrKn%2Fkubeswitch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielfoehrKn","download_url":"https://codeload.github.com/danielfoehrKn/kubeswitch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246523872,"owners_count":20791444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kubeconfig","kubecontext","kubectx","kubernetes","kubeswitch"],"created_at":"2024-08-01T06:01:08.624Z","updated_at":"2025-04-01T02:31:18.287Z","avatar_url":"https://github.com/danielfoehrKn.png","language":"Go","funding_links":[],"categories":["Go","kubernetes","\u003ca name=\"k8s\"\u003e\u003c/a\u003ek8s","K8S-Tools"],"sub_categories":[],"readme":"# Kubeswitch\n\n![Latest GitHub release](https://img.shields.io/github/v/release/danielfoehrkn/kubeswitch.svg)\n[![Build](https://github.com/danielfoehrKn/kubeswitch/workflows/Build/badge.svg)](https://github.com/danielfoehrKn/switch/actions?query=workflow%3A\"Build\")\n[![Go Report Card](https://goreportcard.com/badge/github.com/danielfoehrKn/kubeswitch)](https://goreportcard.com/badge/github.com/danielfoehrKn/kubeswitch)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\nThe kubectx for operators.\n\n`kubeswitch` (lazy: `switch`) is the single pane of glass for all of your kubeconfig files.  \nCaters to operators of large scale Kubernetes installations.\nDesigned as a [drop-in replacement](#difference-to-kubectx) for [kubectx](https://github.com/ahmetb/kubectx).\n\n## Highlights\n\n- **Unified search over multiple providers**\n  - [Amazon Elastic Kubernetes Service (EKS)](docs/stores/eks/eks.md)\n  - [Azure Kubernetes Service (AKS)](docs/stores/azure/azure.md)\n  - [DigitalOcean Kubernetes (DOKS)](docs/stores/digitalocean/digitalocean.md)\n  - [Exoscale](docs/stores/exoscale/exoscale.md)\n  - [Gardener](docs/stores/gardener/gardener.md)\n  - [Google Kubernetes Engine (GKE)](docs/stores/gke/gke.md)\n  - [Hashicorp Vault](docs/stores/vault/use_vault_store.md)\n  - [Local filesystem](docs/stores/filesystem/filesystem.md)\n  - [OVH](docs/stores/ovh/ovh.md)\n  - [Rancher](docs/stores/rancher/rancher.md)\n  - Scaleway (documentation tbd)\n  - [Akamai / Linode](docs/stores/akamai/akamai.md)\n  - [Cluster API (capi)](docs/stores/capi/capi.md)\n  - Your favorite Cloud Provider or Managed Kubernetes Platform is not supported yet? Looking for contributions!\n- **Change the namespace**\n- **Change to any context and namespace from the history**\n- **Terminal Window Isolation**\n  - Each terminal window can target a different cluster (does not overwrite the current-context in a shared Kubeconfig)\n  - Each terminal window can target the same cluster and set a [different namespace preference](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/#setting-the-namespace-preference)\n- **Efficiency**: uses local caches for kubeconfig contexts and namespaces\n- **Advanced Search Capabilities**\n  - Hot reload capability (adds Kubeconfigs to the search on the fly - especially useful when searching large directories)\n  - Live preview of the selected Kubeconfig file (**sanitized from credentials**)\n  - Recursive search (e.g. on the local filesystem or in Vault)\n  - Easily find clusters with [cryptic context names](#search-cryptic-context-names)\n- **Easy Navigation**\n  - Define alias names for contexts without changing the underlying Kubeconfig\n- **Extensibility** \n  - Integrate custom functionality using [Hooks](./hooks/README.md) (comparable with Git pre-commit hooks).\n  - Build your own integration e.g., synchronise Kubeconfig files of clusters from Git or remote systems.\n\n![demo GIF](resources/gifs/switch-demo-large.gif)\n\n## Non-goals\n\n- To provide a customized shell prompt. Use [kube-ps1](https://github.com/jonmosco/kube-ps1).\n\n## Installation\n\nKubeswitch can be installed using `brew` for OSX, MacPorts, from Github Releases or from source. \nPlease [see the documentation](docs/installation.md).\n\n## Usage \n\n```\n$ switch -h\nThe kubectx for operators.\n\nUsage:\n  switch [flags]\n  switch [command]\n\nAvailable Commands:\n  alias                Create an alias for a context. Use ALIAS=CONTEXT_NAME\n  clean                Cleans all temporary and cached kubeconfig files\n  completion           Generate the autocompletion script for the specified shell\n  exec                 Execute any command towards the matching contexts from the wildcard search\n  gardener             gardener specific commands\n  help                 Help about any command\n  history              Switch to any previous tuple {context,namespace} from the history\n  hooks                Run configured hooks\n  list-contexts        List all available contexts\n  namespace            Change the current namespace\n  set-context          Switch to context name provided as first argument\n  set-last-context     Switch to the last used context from the history\n  set-previous-context Switch to the previous context from the history\n  version              show switch version info\n\nFlags:\n      --config-path string         path on the local filesystem to the configuration file. (default \"/Users/tommyolsen/.kube/switch-config.yaml\")\n      --debug                      show debug logs\n  -h, --help                       help for switch\n      --kubeconfig-name string     only shows kubeconfig files with this name. Accepts wilcard arguments '*' and '?'. Defaults to 'config'. (default \"config\")\n      --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\")\n      --no-index                   stores do not read from index files. The index is refreshed.\n      --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)\n      --state-directory string     path to the local directory used for storing internal state. (default \"/Users/tommyolsen/.kube/switch-state\")\n      --store string               the backing store to be searched for kubeconfig files. Can be either \"filesystem\" or \"vault\" (default \"filesystem\")\n      --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\".\n  -v, --version                    version for switch\n\nUse \"switch [command] --help\" for more information about a command.\n```\n\nJust type `switch` to search over the context names defined in the default Kubeconfig file `~/.kube/config`\nor from the environment variable `KUBECONFIG`.\n\nTo recursively **search over multiple directories, files and Kubeconfig stores**, please see the [documentation](docs/kubeconfig_stores.md) \nto set up the necessary configuration file.\n\n## Change namespace\n\nChange the current namespace using `switch ns`\nUses a **self-updating** local namespace **cache** for instant search results.\n\n![](resources/gifs/namespace.gif)\n\n## History\n\nSimilar to the command histories of a shell, `switch` keeps a history of used contexts and namespaces.\nA history entry is always a tuple of `{context-name, namespace}`.\nThis allows to jump back to any context and namespace in the history.\n\n![](resources/gifs/history.gif)\n\nIn addition, use \n- `switch .` to change to the last used context and namespace (handy for new terminals)\n- `switch -` to change to the previous history entry\n\n## List and search for contexts\n\nYou can list all your indexed contexts by issuing the following command: `switch list-contexts`. \nAnd if you want to search for only parts of those contexts, you can use wildcard search:\n\n```sh\nswitch list-contexts \"*-dev-?\"\n```\n\nWildcard search supports [matching wildcards](https://en.wikipedia.org/wiki/Matching_wildcards) notation also known as globbing:\n\n- `?` matches exactly one occurrence of any character.\n- `*` matches arbitrary many (including zero) occurrences of any character.\n\n## Execute commands\n\nYou 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:\n\n```sh\nswitch exec \"*-dev-?\" -- kubectl get ns\n```\n\nYou can also wrap the command(s) into a script and execute it via `switch exec`:\n\n```sh\nswitch exec \"*-dev-?\" -- bash script.sh\n```\n\nFor inline shell script execution, you need to specify the default shell in the `SwitchConfig` file:\n\n```yaml\n# ~/.kube/switch-config.yaml\nkind: SwitchConfig\nexecShell: \"/bin/bash\"\n```\n\nThen you can run shell commands like so:\n```sh\n# executes /bin/bash -c 'for i in 1 2 3; do sleep 1; echo \"hi $i\"; done'\nswitch exec \"*-dev-?\" -- 'for i in 1 2 3; do sleep 1; echo \"hi $i\"; done'\n```\n\n## Kubeconfig stores\n\nMultiple Kubeconfig stores are supported.\nThe local filesystem is the default store and does not require any additional setup.\nHowever, if you intend to search for all Kubeconfig context/files in the `~/.kube` directory, \nplease [first consider this](docs/kubeconfig_stores.md#additional-considerations).\n\nTo search over multiple directories and setup Kubeconfig stores (such as Vault), [please see here](docs/kubeconfig_stores.md).\n\n## Kubeconfig cache\n\nA cache for kubeconfig files can be added to a store to prevent loading from remote on each invocation of `kubeswitch`.\nThe kubeconfig file will be cached after first download.\n\nTo see how to configure the cache, [please see here](docs/kubeconfig_cache.md).\n\n## Transition from Kubectx\n\nOffers a smooth transition as `kubeswitch` is a \ndrop-in replacement for _kubectx_.\nYou can set an alias and keep using your existing setup.\n```\n  alias kubectx='switch'\n  alias kctx='switch'\n```\n\nHowever, that does not mean that `kubeswitch` behaves exactly like `kubectx`. \nPlease [see here](#difference-to-kubectx) to read about some main differences to kubectx.\n\n## Alias\n\nAn alias for any context name can be defined. \nAn alias **does not modify** or rename the context in the kubeconfig file, \ninstead it is just injected for the search.\n\nDefine an alias.\n\n```\n$ switch alias mediathekview=gke_mediathekviewmobile-real_europe-west1-c_mediathekviewmobile\n```\n\nIt is also possible to use `switch alias \u003calias\u003e=.` to create an alias for the current context.\n\nSee the created alias\n```\n$ switch alias ls\n+---------------+-------------------------------------------------------------------------------+\n| ALIAS         | CONTEXT                                                                       |\n+---------------+-------------------------------------------------------------------------------+\n| mediathekview | mediathekview/gke_mediathekviewmobile-real_europe-west1-c_mediathekviewmobile |\n+---------------+-------------------------------------------------------------------------------+\n| TOTAL         | 1                                                                             |\n+---------------+-------------------------------------------------------------------------------+ \n```\n\nRemove the alias\n\n```\n$ switch alias rm mediathekview\n```\n\n### Caching\n\nSee [here](docs/search_index.md) how to use a search index (cache) to speed up search operations.\nUsing the search index is especially useful when\n- dealing with large amounts of Kubeconfigs and querying the Kubeconfig store is slow (e.g. searching a large directory)\n- when using a remote systems (such as Vault) as the Kubeconfig store to increase search speed, reduce latency and save API requests\n\n### Hot Reload\n\nFor large directories with many Kubeconfig files, the Kubeconfigs are added to the search set on the fly.\nFor smaller directory sizes, the search feels instantaneous.\n\n![demo GIF](resources/gifs/hot-reload.gif)\n\n## Search cryptic context names \n\nUnfortunately operators sometimes have to deal with cryptic or generated kubeconfig context names that make\nit hard to guess which Kubernetes cluster this kubeconfig context actually points to.\nFor example, these could be temporary CI clusters.\n\nWithout having to manually change the Kubeconfig file, `kubeswitch` makes it easier to identify\nthe right context name by including the **direct parent path** name in the fuzzy search.\nThis way, the directory layout can actually convey information useful for the search.\n\nTo exemplify this, look at the path layout below. \nEach Kubernetes landscape (called `dev`, `canary` and `live`) have their own directory containing the Kubeconfigs \nof the Kubernetes clusters on that landscape.\nEvery `Kubeconfig` is named `config`.\n\n```\n$ tree .kube/my-path\n.kube/my-path\n├── canary\n│   └── config\n├── dev\n│   ├── config\n│   └── config-tmp\n└── live\n    └── config\n```\nThis is how the search looks like for this directory.\nThe parent directory name is part of the search.\n\n![demo GIF](resources/gifs/search-show-parent-folder.png)\n\nYou can either manually create such a path layout and place the kubeconfigs, or write a [custom \nhook](hooks/README.md) (script / binary) to do that prior to the search.\n\n### Extensibilty \n\nCustomization is possible by using `Hooks` (think Git pre-commit hooks). \nHooks can call an arbitrary executable or execute commands at a certain time (e.g every 6 hours) prior to the search via `kubeswitch`.\nFor more information [take a look here](./hooks/README.md).\n\n### Difference to kubectx\n\n`kubectx` is great when dealing with few Kubeconfig files - however lacks support when\noperating large Kubernetes installations where clusters spin up on demand,\nhave cryptic context names or are stored in various kubeconfig stores (e.g., Vault).\n\n`kubeswitch` is build for a world where Kubernetes clusters are [treated as cattle, not pets](https://devops.stackexchange.com/questions/653/what-is-the-definition-of-cattle-not-pets).\nThis has implications on how Kubeconfig files are managed. \n`kubeswitch` is fundamentally designed for the modern Kubernetes operator of large dynamic Kubernetes \ninstallations with possibly thousands of Kubeconfig files in [various locations](docs/kubeconfig_stores.md).\n\nHas build-in\n - convenience features (terminal window isolation, context history, [context aliasing](#alias), [improved search experience](#search-cryptic-context-names), sanitized Kubeconfig preview);\n - advanced search capabilities (search index, hot reload);\n - as well as integration points with external systems ([hooks](hooks/README.md)).\n\n\nIn addition, `kubeswitch` is a drop-in replacement for _kubectx_.\nYou can set an alias and keep using your existing setup.\n```\n  alias kubectx='switch'\n  alias kctx='switch'\n```\n\nHowever, that does not mean that `kubeswitch` behaves exactly like `kubectx`.\n\n**Alias Names**\n\n`kubectx` supports renaming context names using `kubectx \u003cNEW_NAME\u003e=\u003cNAME\u003e`.\nLikewise, use `switch \u003cNEW_NAME\u003e=\u003cNAME\u003e` to create an alias.\nAn alias **does not modify** or rename the context in the kubeconfig file. \nIt is just a local configuration that can be removed again via `switch alias rm \u003cNAME\u003e`.\nDirectly modifying the Kubeconfig is problematic: \n - Common tooling might be used across the team which needs to rely on predictable cluster naming conventions\n - Modifying the file is not always possible e.g., when the Kubeconfig is actually stored in a Vault\n - No easy way to revert the alias or see aliases that are currently in use\n\n**Terminal Window isolation**\n\n`kubectx` directly modifies the kubeconfig file to set the current context.\nThis has the disadvantage that every other terminal using the same \nKubeconfig file (e.g, via environment variable _KUBECONFIG_) will also be affected and change the context.\n\nA guideline of `kubeswitch` is to not modify the underlying Kubeconfig file.\nHence, a temporary copy of the original Kubeconfig file is created and used to modify the context.\nThis way, each terminal window works on its own copy of the Kubeconfig file and cannot interfere with each other.\n\n### Limitations\n\nPlease make sure there are no kubeconfig files that have the same context name within one directory.\nDefine multiple search paths using the [configuration file](docs/kubeconfig_stores.md).\n\n### Future Plans\n\n- Support more Cloud Providers and Managed Kubernetes Platforms\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FdanielfoehrKn%2Fkubeswitch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FdanielfoehrKn%2Fkubeswitch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FdanielfoehrKn%2Fkubeswitch/lists"}