{"id":13515194,"url":"https://github.com/SimonTheLeg/konf-go","last_synced_at":"2025-03-31T04:36:38.118Z","repository":{"id":41207869,"uuid":"449014863","full_name":"SimonTheLeg/konf-go","owner":"SimonTheLeg","description":"konf is a lightweight kubeconfig manager. With konf you can use different kubeconfigs at the same time. And because it does not need subshells, konf is blazing fast!","archived":false,"fork":false,"pushed_at":"2024-09-07T15:46:17.000Z","size":670,"stargazers_count":168,"open_issues_count":10,"forks_count":12,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-16T07:10:10.357Z","etag":null,"topics":["kubeconfig","kubernetes"],"latest_commit_sha":null,"homepage":"","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/SimonTheLeg.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":"2022-01-17T19:00:33.000Z","updated_at":"2024-09-27T00:36:43.000Z","dependencies_parsed_at":"2023-02-18T23:01:55.511Z","dependency_job_id":"09bf6c07-8cca-4b52-96e6-2dcda8a2b132","html_url":"https://github.com/SimonTheLeg/konf-go","commit_stats":{"total_commits":132,"total_committers":4,"mean_commits":33.0,"dds":"0.022727272727272707","last_synced_commit":"8ad03362b014b0ae5539dd6bd93c65d65ac15f7a"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonTheLeg%2Fkonf-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonTheLeg%2Fkonf-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonTheLeg%2Fkonf-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimonTheLeg%2Fkonf-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SimonTheLeg","download_url":"https://codeload.github.com/SimonTheLeg/konf-go/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246418658,"owners_count":20773934,"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","kubernetes"],"created_at":"2024-08-01T05:01:07.373Z","updated_at":"2025-03-31T04:36:33.637Z","avatar_url":"https://github.com/SimonTheLeg.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Konf - Lightweight kubeconfig Manager\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/simontheleg/konf-go)](https://goreportcard.com/report/github.com/simontheleg/konf-go)\n![test](https://github.com/simontheleg/konf-go/actions/workflows/test.yaml/badge.svg)\n\n- [Konf - Lightweight kubeconfig Manager](#konf---lightweight-kubeconfig-manager)\n  - [Why konf?](#why-konf)\n  - [Installation](#installation)\n    - [1. Install the konf-go binary](#1-install-the-konf-go-binary)\n    - [2. Install the konf shellwrapper](#2-install-the-konf-shellwrapper)\n    - [Customizations to Have a Good Time](#customizations-to-have-a-good-time)\n  - [Usage](#usage)\n  - [How does it work?](#how-does-it-work)\n    - [kubeconfig management across shells](#kubeconfig-management-across-shells)\n    - [zsh/bash-func-magic](#zshbash-func-magic)\n    - [Upgrading spf13/cobra](#upgrading-spf13cobra)\n  - [Contributing](#contributing)\n    - [Usage of stdout and stderr](#usage-of-stdout-and-stderr)\n    - [Tests](#tests)\n  - [Ideas for Future Improvements](#ideas-for-future-improvements)\n\n## Why konf?\n\n- konf allows you to quickly switch between different kubeconfig files\n- konf allows you to simultaneously use different kubeconfigs in different shells\n- konf executes directly in your current shell and does not start any subshell (unlike kubie). As a result it works extremely fast\n\n![demo.gif](doc/demo.gif)\n\n## Installation\n\n### 1. Install the konf-go binary\n\n#### 1.1 Pre-compiled binary\n\nThe [GH Releases](https://github.com/SimonTheLeg/konf-go/releases) provide pre-compiled binaries for common platforms.\n\n#### 1.2 Nix Package\n\nThe package can be installed in the local nix-profile.\n\n```shell\nnix-env -iA nixpkgs.konf\n```\n\nFor adhoc or testing purposes a shell with the package can be spawned.\n\n```shell\nnix-shell -p konf\n```\n\nFor NixOS users it is highly recommended to install the package by adding it to the list of `systemPackages`.\n\n```nix\n{ # ...\n\n  environment.systemPackages = with pkgs; [\n    konf\n    # ...\n  ];\n}\n```\n\n#### 1.3 Building from source\n\n```shell\ngo install github.com/simontheleg/konf-go@latest\n```\n\nPlease do not rename or alias this binary, it is not be called by the user directly. Instead alias the konf shellwrapper described in the next step!\n\n### 2. Install the konf shellwrapper\n\nDepending on whether you are using zsh/bash or fish, please use the following:\n\n#### A) zsh/bash\n\nAdd the following to your `.zshrc` / `.bashrc` and restart your shell or re-source this file:\n\n```sh\n# Currently supported shells: zsh, bash\nsource \u003c(konf-go shellwrapper zsh)\n```\n\n#### B) fish\n\nAdd the following to your `config.fish` and restart your shell or re-source this file:\n\n```sh\nkonf-go shellwrapper fish | source\n```\n\nThis will install a shellwrapper called `konf`, which you can use like any command. The wrapper can also be aliased if need be.\n\n### Customizations to Have a Good Time\n\nA collection of optional settings to improve quality of life with konf.\n\n#### A) zsh/bash\n\nThese can be added to your `.zshrc` / `.bashrc`:\n\n```sh\n# Autocompletion. Currently supported shells: zsh, bash\nsource \u003c(konf completion zsh)\n\n# Open last konf on new shell session\nkonf --silent set -\n\n# Alias\nalias kctx=\"konf set\"\nalias kns=\"konf ns\"\n```\n\n#### B) fish\n\nThese can be added to your `config.fish`:\n\n```sh\n# Autocompletion\nkonf completion fish | source\n\n# Open last konf on new shell session\nset -x KUBECONFIG (konf --silent set -)\n\n# Alias\nabbr --add --global -- kctx 'konf set'\nabbr --add --global -- kns 'konf ns'\n```\n\n## Usage\n\nBefore any kubeconfig can be used with konf you have to import it:\n\n```sh\nkonf import \u003cpath-to-your-kubeconf\u003e\n```\n\nThis is required, because konf maintains its own store of kubeconfigs to be able to work its \"no-additional-shell-required\"-magic.\n\nAfterwards you can quickly switch between konfs using either:\n\n```sh\nkonf set      # will open a picker dialogue\nkonf set -    # will open the last konf\nkonf set \u003cid\u003e # will set a specific konf. \u003cid\u003e is usually \u003ccontext\u003e_\u003ccluster\u003e\n```\n\nAdditional commands and flags can be seen by calling `konf --help`\n\n## How does it work?\n\n### kubeconfig management across shells\n\nEssentially konf maintains its state via two directories:\n\n- `\u003ckonfDir\u003e/store` -\u003e contains all of your imported kubeconfigs, where each context is split into its own file\n- `\u003ckonfDir\u003e/active` -\u003e contains all currently active konfs. The filename refers to the PID of the shell. Konf will automatically clean unused files after you close the session\n\nWe need these two extra directories because:\n\n- each konf file must only contain one context. This is because konf can only use the `$KUBECONFIG` variable to point to one kubeconfig file. If there are multiple contexts in that file, kubernetes looks for a `current-context` key and sets the config to that, thus introducing some ambiguity. To avoid this, konf import splits all the contexts into separate files\n- in order to allow for different shells to have different kubeconfigs we need to maintain a single one per shell. Otherwise when you run modifications like changing the namespace, these would affect all shells, which is not what we want\n\n### zsh/bash-func-magic\n\nOne of the largest difficulties in this project lies in the core design of the shell.\nEssentially a child process cannot make modifications to its parents.\nThis includes setting an environment variable, which affects us because we want to set `$KUBECONFIG`.\nThe way we work around this \"limitation\" is by using a zsh/bash function that executes our binary and then sets `$KUBECONFIG` to the output of `konf-go`.\nWith this trick we are able to set `$KUBECONFIG` and can make this project work. Since only the result of stdout will be captured by the zsh/bash-func, we can still communicate normally with the user by using stderr.\n\n## Contributing\n\n### Usage of stdout and stderr\n\nWhen developing for konf, it is important to understand the konf-shellwrapper. It is designed to solve the problem described in the [zsh/bash-func-magic section](###zsh/bash-func-magic).\nIt works by saving the stdOut of konf-go in a separate variable and then evaluating the result. Should the result contain the keyword `KUBECONFIGCHANGE:`, the wrapper will set `$KUBECONFIG` to the value after the colon.\nOtherwise the wrapper ist just going to print the result to stdOut in the terminal. This setup allows for konf-go commands to print to stdOut (which is required for example for zsh/bash completion). Additionally it should be able to handle large stdOut outputs as well, as it only parses the first line of output.\nInteractive prompts however (like promptUI) should always print their dialogue to stdErr, as the wrapper has troubles with user input. Nonetheless you can still easily submit the result of the selection to the wrapper later on using the aforementioned keyword. So it should not be a big issue.\n\n### Tests\n\nBy default `go test ./...` will run both unit and integration tests. Integration tests are mainly used to check for filename validity and only write in the `/tmp/konf` directory. They are mainly being used by the CI. If you only want to run unit-test, you can do so by using the `-short` flag:\n\n```sh\ngo test -short ./...\n```\n\nIf you want to only run integration tests, simply run:\n\n```sh\ngo test -run Integration ./...\n```\n\n### Upgrading spf13/cobra\n\nSpecial care should be taken before upgrading the cobra package.\nThis is due to the fact that in `completion.go` we use the standard completion from the library and then apply some string insertions at certain positions.\nAs a result, before any upgrade of the package, it should be checked whether the GenXYZCompletion funcs from cobra have changed.\nUnfortunately I was not able to find a more elegant solution, so for now we just have to be vigilant when upgrading the dependency.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSimonTheLeg%2Fkonf-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSimonTheLeg%2Fkonf-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSimonTheLeg%2Fkonf-go/lists"}