docs/kgctl.md: add kgctl doc

This commit introduces a new doc for the kgctl commandline tool.

Signed-off-by: Lucas Servén Marín <lserven@gmail.com>

README.md

@@ -174,7 +174,7 @@ Now, `important-service` can be used on `cluster2` just like any other Kubernete
 
 ## Analysis
 
-The topology and configuration of a Kilo network can be analyzed using the `kgctl` binary.
+The topology and configuration of a Kilo network can be analyzed using the [`kgctl` command line tool](./docs/kgctl.md).
 For example, the `graph` command can be used to generate a graph of the network in Graphviz format:
 
 ```shell

docs/kgctl.md

@@ -0,0 +1,94 @@
+# 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.
+
+## Getting Started
+
+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`, simply run:
+
+```shell
+go install github.com/squat/kilo/cmd/kgctl
+```
+
+## Commands
+
+|Command|Syntax|Description|
+|----|----|-------|
+|[graph](#graph)|`kgctl graph [flags]`|Produce a graph in GraphViz format representing the topology of the cluster.|
+|[showconf](#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:
+
+```shell
+kgctl graph
+```
+
+This will produce some output in the DOT graph description language, e.g.:
+
+```dot
+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`:
+
+```shell
+kgctl graph | circo -Tsvg > cluster.svg
+```
+
+This will generate an SVG like:
+
+<img src="./graphs/location.svg">
+
+### 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:
+
+```shell
+NODE=master # the name of a node
+kgctl showconf node $NODE
+```
+
+This will produce some output in INI format, e.g.
+
+```ini
+[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.:
+
+```shell
+NODE=master # the name of a node
+kgctl --kubeconfig $KUBECONFIG1 showconf node $NODE --as-peer --output yaml | kubectl --kubeconfig $KUBECONFIG2 apply -f -
+```