adelorenzo/kilo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #159 from squat/update_install_docs

Browse Source 
docs: note how to install precompiled kgctl
This commit is contained in:
Lucas Servén Marín 2021-05-11 18:25:55 +02:00 committed by GitHub
commit 2ba1376400
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 34 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Makefile
View File

@ -12,7 +12,6 @@ else
BINS := bin/$(OS)/$(ARCH)/kgctl
endif
RELEASE_BINS := $(addprefix bin/release/kgctl-, $(addprefix linux-, $(ALL_ARCH)) darwin-amd64 windows-amd64)
CLIENT_BINS := $(addsuffix /kgctl, $(addprefix bin/, $(addprefix linux/, $(ALL_ARCH)) darwin/amd64 windows/amd64))
PROJECT := kilo
PKG := github.com/squat/$(PROJECT)
REGISTRY ?= index.docker.io

2
README.md
View File

@ -18,7 +18,7 @@ In addition to creating multi-cloud clusters, Kilo enables the creation of multi
An introductory video about Kilo from KubeCon EU 2019 can be found on [youtube](https://www.youtube.com/watch?v=iPz_DAOOCKA).
## How it works
## How It Works
Kilo uses [WireGuard](https://www.wireguard.com/), a performant and secure VPN, to create a mesh between the different nodes in a cluster.
The Kilo agent, `kg`, runs on every node in the cluster, setting up the public and private keys for the VPN as well as the necessary rules to route packets between locations.

25
docs/kgctl.md
View File

@ -6,14 +6,31 @@ This tool can be used to understand a mesh's topology, get the WireGuard configu
## Installation
Installing `kgctl` currently requires building the binary from source.
*Note*: the [Go toolchain must be installed](https://golang.org/doc/install) in order to build the binary.
To build and install `kgctl`, run:
The `kgctl` binary is automatically compiled for Linux, macOS, and Windows for every release of Kilo and can be downloaded from [the GitHub releases page](https://github.com/squat/kilo/releases/latest).
### Building from Source
Kilo is written in Golang and as a result the [Go toolchain must be installed](https://golang.org/doc/install) in order to build the `kgctl` binary.
To download the Kilo source code and then build and install `kgctl` using the latest commit all with a single command, run:
```shell
go install github.com/squat/kilo/cmd/kgctl
go install github.com/squat/kilo/cmd/kgctl@latest
```
Alternatively, `kgctl` can be built and installed based on specific version of the code by specifying a Git tag or hash, e.g.:
```shell
go install github.com/squat/kilo/cmd/kgctl@0.2.0
```
When working on Kilo locally, it can be helpful to build and test the `kgctl` binary as part of the development cycle.
In order to build a binary from a local checkout of the Git repository, run:
```shell
make
```
This will produce a `kgctl` binary at `./bin/<your-os>/<your-architecture>/kgctl`.
## Commands
|Command|Syntax|Description|

16
docs/userspace-wireguard.md
View File

@ -6,13 +6,16 @@ This can make sense in cases where
* not all nodes in a cluster have WireGuard installed; or
* nodes are effectively immutable and kernel modules cannot be installed.
One example of a userspace implementation of WireGuard is [BoringTun].
## Homogeneous Clusters
In a homogeneous cluster where no node has the WireGuard kernel module, a userspace WireGuard implementation can be made available by deploying a DaemonSet.
This DaemonSet creates a WireGuard interface that Kilo will manage.
In order to avoid race conditions, `kg` needs to be passed the `--create-interface=false` flag.
An example configuration for a k3s cluster with [boringtun](https://github.com/cloudflare/boringtun) can be applied with:
__Note:__ in order to avoid race conditions, `kg` needs to be passed the `--create-interface=false` flag.
An example configuration for a K3s cluster with [BoringTun] can be applied with:
```shell
kubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/kilo-k3s-userspace.yaml
@ -23,12 +26,17 @@ __Note:__ even if some nodes have the WireGuard kernel module, this configuratio
## Heterogeneous Clusters
In a heterogeneous cluster where some nodes are missing the WireGuard kernel module, a userspace WireGuard implementation can be provided only to the nodes that need it while enabling the other nodes to leverage WireGuard via the kernel module.
An example of such a configuration for a k3s cluster can by applied with:
An example of such a configuration for a K3s cluster can by applied with:
```shell
kubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/kilo-k3s-userspace-heterogeneous.yaml
```
This configuration will deploy [nkml](https://github.com/leonnicolas/nkml) as a DaemonSet to label all nodes according to the presence of the WireGuard kernel module.
It will also create two different DaemonSets with Kilo: `kilo` without userspace WireGuard and `kilo-userspace` with boringtun as a sidecar.
It will also create two different DaemonSets with Kilo:
1. `kilo` without userspace WireGuard; and
1. `kilo-userspace` with [BoringTun] as a sidecar.
__Note:__ because Kilo is dependant on nkml, nkml must be run on the host network before CNI is available and requires a kubeconfig in order to access the Kubernetes API.
[BoringTun]: https://github.com/cloudflare/boringtun