kilo/docs/kgctl.md

kgctl

Kilo provides a command line tool for inspecting and interacting with clusters: kgctl. This tool can be used to understand a mesh's topology, get the WireGuard configuration for a peer, or graph a cluster. kgctl requires a Kubernetes configuration file to be provided, either by setting the KUBECONFIG environment variable or by providing the --kubeconfig flag.

Installation

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.

Building from Source

Kilo is written in Golang and as a result the Go toolchain must be installed 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:

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.:

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:

make

This will produce a kgctl binary at ./bin/<your-os>/<your-architecture>/kgctl.

Binary Packages

Arch Linux

Install kgctl from the Arch User Repository using an AUR helper like paru or yay:

paru -S kgctl-bin

Arkade

The arkade CLI can be used to install kgctl on any OS and architecture:

arkade get kgctl

Commands

Command	Syntax	Description
graph	kgctl graph [flags]	Produce a graph in GraphViz format representing the topology of the cluster.
showconf	kgctl showconf ( node | peer ) NAME [flags]	Show the WireGuard configuration for a node or peer in the mesh.

graph

The graph command generates a graph in GraphViz format representing the Kilo mesh. This graph can be helpful in understanding or debugging the topology of a network. Example:

kgctl graph

This will produce some output in the DOT graph description language, e.g.:

digraph kilo {
	label="10.2.4.0/24";
	labelloc=t;
	outputorder=nodesfirst;
	overlap=false;
	"ip-10-0-6-7"->"ip-10-0-6-146"[ dir=both ];
	"ip-10-1-13-74"->"ip-10-1-20-76"[ dir=both ];
	"ip-10-0-6-7"->"ip-10-1-13-74"[ dir=both ];
	"ip-10-0-6-7"->"squat"[ dir=both, style=dashed ];
	"ip-10-1-13-74"->"squat"[ dir=both, style=dashed ];

# ...

}
;

To render the graph, use one of the GraphViz layout tools, e.g. circo:

kgctl graph | circo -Tsvg > cluster.svg

This will generate an SVG like:

showconf

The showconf command outputs the WireGuard configuration for a node or peer in the cluster, i.e. the configuration that the node or peer would need to set on its local WireGuard interface in order to participate in the mesh. Example:

NODE=master # the name of a node
kgctl showconf node $NODE

This will produce some output in INI format, e.g.

[Interface]
ListenPort = 51820

[Peer]
AllowedIPs = 10.2.0.0/24, 10.1.13.74/32, 10.2.4.0/24, 10.1.20.76/32, 10.4.0.2/32
Endpoint = 3.120.246.76:51820
PersistentKeepalive = 0
PublicKey = IgDTEvasUvxisSAmfBKh8ngFmc2leZBvkRwYBhkybUg=

The --as-peer flag modifies the behavior of the command so that it outputs the configuration that a different WireGuard interface would need in order to communicate with the specified node or peer. When further combined with the --output yaml flag, this command can be useful to register a node in one cluster as a peer of another cluster, e.g.:

NODE=master # the name of a node
kgctl --kubeconfig $KUBECONFIG1 showconf node $NODE --as-peer --output yaml | kubectl --kubeconfig $KUBECONFIG2 apply -f -