{"id":15637669,"url":"https://github.com/flavio/kuberlr","last_synced_at":"2025-04-05T03:09:53.111Z","repository":{"id":42472539,"uuid":"261144832","full_name":"flavio/kuberlr","owner":"flavio","description":"A tool that simplifies the management of multiple versions of kubectl","archived":false,"fork":false,"pushed_at":"2025-03-27T13:35:42.000Z","size":4284,"stargazers_count":118,"open_issues_count":12,"forks_count":20,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-29T02:06:16.407Z","etag":null,"topics":["kubectl","kubectl-binaries","kubernetes","kubernetes-cluster","versioning"],"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/flavio.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":"2020-05-04T10:35:08.000Z","updated_at":"2025-03-27T13:35:41.000Z","dependencies_parsed_at":"2024-02-12T14:55:44.849Z","dependency_job_id":"f4a17346-a422-4209-9fda-41a2d99fab35","html_url":"https://github.com/flavio/kuberlr","commit_stats":{"total_commits":223,"total_committers":17,"mean_commits":"13.117647058823529","dds":0.6278026905829597,"last_synced_commit":"956bdf4a41f797fb22fdc6b28daed24173f790b1"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavio%2Fkuberlr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavio%2Fkuberlr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavio%2Fkuberlr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flavio%2Fkuberlr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flavio","download_url":"https://codeload.github.com/flavio/kuberlr/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247280272,"owners_count":20912967,"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":["kubectl","kubectl-binaries","kubernetes","kubernetes-cluster","versioning"],"created_at":"2024-10-03T11:12:29.296Z","updated_at":"2025-04-05T03:09:53.093Z","avatar_url":"https://github.com/flavio.png","language":"Go","funding_links":[],"categories":["Build \u0026 Packaging Automation"],"sub_categories":[],"readme":"| Go Report                                                                                                                                | Unit tests                                                                                                                                                              | License                                                                                                                              |\n| ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |\n| [![Go Report Card](https://goreportcard.com/badge/github.com/flavio/kuberlr)](https://goreportcard.com/report/github.com/flavio/kuberlr) | [![tests](https://github.com/flavio/kuberlr/workflows/tests/badge.svg?branch=main)](https://github.com/flavio/kuberlr/actions?query=workflow%3Atests+branch%3Amain) | [![License: Apache 2.0](https://img.shields.io/badge/License-Apache2.0-brightgreen.svg)](https://opensource.org/licenses/Apache-2.0) |\n\n\u003e One kubectl to rule them all,  \n\u003e one kubectl to find them,  \n\u003e One kubectl to bring them all  \n\u003e and in the darkness bind them.\n\nManaging different kubernetes clusters often requires to keep multiple versions\nof the kubectl available on the system, plus it poses the challenge to ensure\nthe right binary is used when talking with a cluster.\n\nkubernetes defines a clear [version skew policy](https://kubernetes.io/docs/setup/release/version-skew-policy/)\nfor all its components. This is [what is stated about kubectl](https://kubernetes.io/docs/setup/release/version-skew-policy/#kubectl):\n\n\u003e kubectl is supported within one minor version (older or newer) of kube-apiserver.\n\u003e\n\u003e Example:\n\u003e\n\u003e ```\n\u003e kube-apiserver is at 1.18\n\u003e kubectl is supported at 1.19, 1.18, and 1.17\n\u003e ```\n\nkuberlr (_kube-ruler_) is a simple wrapper for kubectl. Its main purpose is to\nmake it easy to manage clusters running different versions of kubernetes.\n\nThis is how kuberlr looks like in action:\n[![asciicast](https://asciinema.org/a/326626.svg)](https://asciinema.org/a/326626)\n\nkuberlr can run on Linux, macOS and Windows.\n\n## Installation\n\nYou can find pre-built binaries of kuberlr under the\n[GitHub release](https://github.com/flavio/kuberlr/releases) tab.\n\nPut the `kuberlr` binary somewhere in your `PATH` and create a symlink named `kubectl`\npointing to it.\n\nFor example, assuming `~/bin` has a high priority inside of your `PATH`:\n\n```\n$ cp kuberlr /bin/\n$ ln -s ~/bin/kuberlr ~/bin/kubectl\n```\n\n\u003e **Note:** it's also possible to skip the creation of the symlink and use `kuberlr kubectl` instead.\n\n## Usage\n\nUse the `kubectl` _\"fake binary\"_ as you usually do. Behind the scene\nkuberlr will ensure a compatible version of `kubectl` is used.\n\nYou can invoke the `kuberlr` binary in a direct fashion to access its\nsub-commands. For example, the `kuberlr bins` will print all the `kubectl`\nbinaries that are available to the user.\n\n## How it works\n\nkuberlr connects to the API server of your kubernetes cluster and figures\nout its version.\n\nkuberlr obtains the url of the kubernetes cluster either by looking at the\n`~/.kube/config` file or by reading the contents of the file referenced by\nthe `KUBECONFIG` environment variable.\n\nOnce the version of the remote server is know, kuberlr looks for a compatible\nkubectl binary under the `~/.kuberlr/\u003cGOOS\u003e-\u003cGOARCH\u003e/` directory and `/usr/bin`.\n\nkuberlr reuses an already existing binary if it respects the kubectl\nversion skew policy, otherwise it downloads the right one from the\n[upstream mirror](https://kubernetes.io/docs/tasks/tools/install-kubectl/) into\nthe local user cache (`~/.kuberlr/\u003cGOOS\u003e-\u003cGOARCH\u003e/`).\n\nkuberlr names the kubectl binaries it downloads using the following naming\nscheme: `kubectl\u003cmajor version\u003e.\u003cminor version\u003e.\u003cpatch level\u003e`.\n\nFinally kuberlr performs an [execve(2)](https://www.unix.com/man-page/bsd/2/EXECVE/)\nsyscall and leaves the control to the kubectl binary. (٭)\n\n**Note well:** by default kuberlr will download the missing `kubectl` binaries\nfrom the upstream mirror. This behaviour can be disabled via kuberlr's\nconfiguration file.\n\nThe `execve` syscall is not available on Windows. On this platform another\napproach is used, but the end result doesn't change. (٭)\n\n## Reusing system-wide kubectl binaries\n\nAs pointed above kuberlr looks for a compatible kubectl binary both at user\nlevel (`~/.kuberlr/\u003cGOOS\u003e-\u003cGOARCH\u003e/`) and at system level (`/usr/bin`).\n\nThe kubectl binaries installed at system level must respect one of these naming\nschemes in order to be used:\n\n- `kubectl\u003cmajor version\u003e.\u003cminor version\u003e.\u003cpatch level\u003e` (e.g.: `kubectl1.18.3`)\n- `kubectl\u003cmajor version\u003e.\u003cminor version\u003e`: this would be handled as kubectl\n  version `\u003cmajor version\u003e.\u003cminor version\u003e.0`\n\n## Configuration\n\nThe behaviour of kuberlr can be adjusted by creating a configuration file in\none of these locations:\n\n1. `/usr/etc/kuberlr.conf`: this is the location used by distributions like\n   openSUSE to handle the split between `/etc` and `/usr/etc`. You can find\n   more details [here](https://en.opensuse.org/openSUSE:Packaging_UsrEtc).\n1. `/etc/kuberlr.conf`\n1. `$HOME/.kuberlr/kuberlr.conf`\n1. `$KUBERLR_CFG`\n\nThe configuration files are read in the order written above and merged together.\nConfiguration files can override the values defined by the previous ones, or\nprovide new ones.\n\nThe configuration file is written using the [TOML format](https://github.com/toml-lang/toml):\n\n```toml\n# Allow the download of missing kubectl binaries from kubernetes' upstream mirror\nAllowDownload = true\n\n# Directory where kubectl binaries are made accessible to all the users of the system\nSystemPath = \"/opt/bin\"\n\n# Timeout (sec) for requests made against the kubernetes API\nTimeout = 1\n\n# URL of the upstream mirror where kubectl binaries can be downloaded from\n# Default \"https://dl.k8s.io\"\nKubeMirrorUrl = \"https://dl.k8s.io\"\n```\n\nThe behaviour can also be adjusted by using environment variables matching the\nconfig file: `KUBERLR_ALLOWDOWNLOAD`, `KUBERLR_SYSTEMPATH`, `KUBERLR_TIMEOUT`,\n`KUBERLR_KUBEMIRRORURL`, and so on.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflavio%2Fkuberlr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflavio%2Fkuberlr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflavio%2Fkuberlr/lists"}