Skip to content

Commit

Permalink
Improve README
Browse files Browse the repository at this point in the history
Remove typos, improve sentences
  • Loading branch information
flavio committed May 16, 2020
1 parent 46c10db commit 7cd66fc
Showing 1 changed file with 17 additions and 23 deletions.
40 changes: 17 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@
> One kubectl to bring them all
> and in the darkness bind them.
Managing different kubernetes clusters ofter requires to keep multiple versions
of the kubectl available on the system, plus it requires some way to ensure the
right binary is used when talking with a cluster.
Managing different kubernetes clusters often requires to keep multiple versions
of the kubectl available on the system, plus it poses the challenge to ensure
the right binary is used when talking with a cluster.

kubernetes defines a clear [version skew policy](https://kubernetes.io/docs/setup/release/version-skew-policy/)
for all its components. This is [what is stated about kubectl](https://kubernetes.io/docs/setup/release/version-skew-policy/#kubectl):
Expand All @@ -23,13 +23,16 @@ for all its components. This is [what is stated about kubectl](https://kubernete
> kubectl is supported at 1.19, 1.18, and 1.17
> ```
kuberlr (*kube-ruler*) is a simple wrapper for kubectl. It's main purpose is to
kuberlr (*kube-ruler*) is a simple wrapper for kubectl. Its main purpose is to
make it easy to manage clusters running different versions of kubernetes.

This is how kuberlr looks like:
This is how kuberlr looks like in action:
[![asciicast](https://asciinema.org/a/326626.svg)](https://asciinema.org/a/326626)

## Usage
## Installation

You can find pre-built binaries of kuberlr under the
[GitHub release](https://github.com/flavio/kuberlr/releases) tab.

Put the `kuberlr` binary somewhere in your `PATH` and create a symlink named `kubectl`
pointing to it.
Expand All @@ -41,8 +44,10 @@ $ cp kuberlr /bin/
$ ln -s ~/bin/kuberlr ~/bin/kubectl
```

Now you can use `kubectl` as you would, behind the scene `kuberlr` will ensure
the right version of `kubectl` is used.
## Usage

Use the `kubectl` *"fake binary"* as you usually do. Behind the scene
kuberlr will ensure a compatible version of `kubectl` is used.

## How it works

Expand All @@ -54,25 +59,14 @@ kuberlr obtains the url of the kubernetes cluster either by looking at the
the `KUBECONFIG` environment variable.

Once the version of the remote server is know, kuberlr looks for a compatible
version under the `~/.kuberlr/<GOOS>-<GOARCH>/` directory.
kubectl binary under the `~/.kuberlr/<GOOS>-<GOARCH>/` directory.

kuberlr reuses an already existing binary if it respects the kubectl
version skew policy, otherwise it downloads the right one from the
[upstream mirror](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
kuberlr downloads the kubectl binary to the following destination:
`~/.kuberlr/<GOOS>-<GOARCH>/kubectl-<remote server major version>.<remote server minor version>.<remote server patch level>`

kuberlr names the kubectl binaries it downloads using the following naming
scheme: `kubectl-<major version>.<minor version>.<patch level>`.

Finally kuberlr performs an [execve(2)](https://www.unix.com/man-page/bsd/2/EXECVE/)
syscall and leaves the control to the kubectl binary.

## TODO

* [ ] I've tested kuberlr only on Linux. It should work also on macOS and on Windows.
Feedback is welcome.
* [x] Provide pre-built binaries for kuberlr (WIP)
* [x] Test coverage, code linting,... right now this is a toy project I created
during a weekend afternoon
* [x] Relax the versioning constraint when downloading the kubectl version.
Right now accessing a kubernetes 1.16.0 and a 1.16.3 cluster would result in two
kubectl binaries being downloaded, while it would just be fine to use the latest
one

0 comments on commit 7cd66fc

Please sign in to comment.