README,docs: document VPN

README.md

@@ -11,6 +11,7 @@ Kilo is a multi-cloud network overlay built on WireGuard and designed for Kubern
 
 Kilo connects nodes in a cluster by providing an encrypted layer 3 network that can span across data centers and public clouds.
 By allowing pools of nodes in different locations to communicate securely, Kilo enables the operation of multi-cloud clusters.
+Kilo's design allows clients to VPN to a cluster in order to securely access services running on the cluster.
 
 ## How it works
 
@@ -76,6 +77,33 @@ To run Kilo on Typhoon:
 kubectl apply -f https://raw.githubusercontent.com/squat/kilo/master/manifests/kilo-typhoon.yaml
 ```
 
+## VPN
+
+Kilo enables peers outside of a Kubernetes cluster to also connect to the VPN, allowing cluster applications to securely access external services and permitting developers and support to securely debug cluster resources.
+In order to declare a peer, start by defining a Kilo peer resource:
+
+```shell
+cat <<'EOF' | kubectl apply -f -
+apiVersion: kilo.squat.ai/v1alpha1
+kind: Peer
+metadata:
+  name: squat
+spec:
+  allowedIPs:
+  - 10.4.1.1/32
+  publicKey: GY5aT1N9dTR/nJnT1N2f4ClZWVj0jOAld0r8ysWLyjg=
+  persistentKeepalive: 10
+EOF
+```
+
+This configuration can then be applied to a local WireGuard interface, e.g. `wg0`, with the help of the `kgctl` tool:
+
+```shell
+sudo wg setconf wg0 <(kgctl showconf peer squat)
+```
+
+[See the VPN docs for more details](./docs/vpn.md).
+
 ## Analysis
 
 The topology of a Kilo network can be analyzed using the `kgctl` binary.

docs/vpn.md

@@ -0,0 +1,61 @@
+# VPN
+
+Kilo enables peers outside of a Kubernetes cluster to connect to the created WireGuard network.
+This enables several use cases, for example:
+* giving cluster applications secure access to external services, e.g. services behind a corporate VPN;
+* allowing external services to access the cluster; and
+* enabling developers and support to securely debug cluster resources.
+
+In order to declare a peer, start by defining a Kilo Peer resource.
+See the following `peer.yaml`, where the `publicKey` field holds a [generated WireGuard public key](https://www.wireguard.com/quickstart/#key-generation):
+
+```yaml
+apiVersion: kilo.squat.ai/v1alpha1
+kind: Peer
+metadata:
+  name: squat
+spec:
+  allowedIPs:
+  - 10.4.1.1/32
+  publicKey: GY5aT1N9dTR/nJnT1N2f4ClZWVj0jOAld0r8ysWLyjg=
+  persistentKeepalive: 10
+```
+
+Then, apply the resource to the cluster:
+
+```shell
+kubectl apply -f peer.yaml
+```
+
+Now, the `kgctl` tool can be used to generate the WireGuard configuration for the newly defined peer:
+
+```shell
+PEER=squat
+kgctl --kubeconfig=$KUBECONFIG showconf peer $PEER
+```
+
+This will produce some output like:
+
+```ini
+[Peer]
+PublicKey = 2/xU029dz/WtvMZAbnSzmhicl8U1/Y3NYmunRr8EJ0Q=
+AllowedIPs = 10.4.0.2/32, 10.2.3.0/24, 10.1.0.3/32
+Endpoint = 108.61.142.123:51820
+```
+
+The configuration can then be applied to a local WireGuard interface, e.g. `wg0`:
+
+```shell
+IFACE=wg0
+kgctl --kubeconfig=$KUBECONFIG showconf peer $PEER > peer.ini
+sudo wg setconf $IFACE peer.ini
+```
+
+Finally, in order to access the cluster, the client will need appropriate routes for the new configuration.
+For example, on a Linux machine, the creation of these routes could be automated by running:
+
+```shell
+for ip in $(kgctl --kubeconfig=$KUBECONFIG showconf peer $PEER | grep AllowedIPs | cut -f 3- -d ' ' | tr -d ','); do
+	sudo ip route add $ip dev $IFACE
+done
+```