From 5ba45af4fe66fe7a687d369cf9c933da2d02668a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lucas=20Serv=C3=A9n=20Mar=C3=ADn?= Date: Fri, 1 Apr 2022 15:11:38 +0200 Subject: [PATCH] docs: add documentation for `kgctl connect` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Lucas Servén Marín --- docs/kgctl.md | 40 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/kgctl.md b/docs/kgctl.md index 6e54fbc..f991da4 100644 --- a/docs/kgctl.md +++ b/docs/kgctl.md @@ -54,9 +54,47 @@ arkade get kgctl |Command|Syntax|Description| |----|----|-------| +|[connect](#connect)|`kgctl connect [flags]`|Connect the host to the cluster, setting up the required interfaces, routes, and keys.| |[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.| +|[showconf](#showconf)|`kgctl showconf ( node \| peer ) [flags]`|Show the WireGuard configuration for a node or peer in the mesh.| +### connect + +The `connect` command configures the local host as a WireGuard Peer of the cluster and applies all of the necessary networking configuration to connect to the cluster. +As long as the process is running, it will watch the cluster for changes and automatically manage the configuration for new or updated Peers and Nodes. +If the given Peer name does not exist in the cluster, the command will register a new Peer and generate the necessary WireGuard keys. +When the command exits, all of the configuration, including newly registered Peers, is cleaned up. + +Example: + +```shell +PEER_NAME=laptop +SERVICECIDR=10.43.0.0/16 +kgctl connect $PEER_NAME --allowed-ips $SERVICECIDR +``` + +The local host is now connected to the cluster and all IPs from the cluster and any registered Peers are fully routable. +When combined with the `--clean-up false` flag, the configuration produced by the command is persistent and will remain in effect even after the process is stopped. + +With the service CIDR of the cluster routable from the local host, Kubernetes DNS names can now be resolved by the cluster DNS provider. +For example, the following snippet could be used to resolve the clusterIP of the Kubernetes API: +```shell +dig @$(kubectl get service -n kube-system kube-dns -o=jsonpath='{.spec.clusterIP}') kubernetes.default.svc.cluster.local +short +# > 10.43.0.1 +``` + +For convenience, the cluster DNS provider's IP address can be configured as the local host's DNS server, making Kubernetes DNS names easily resolvable. +For example, if using `systemd-resolved`, the following snippet could be used: +```shell +systemd-resolve --interface kilo0 --set-dns $(kubectl get service -n kube-system kube-dns -o=jsonpath='{.spec.clusterIP}') --set-domain cluster.local +# Now all lookups for DNS names ending in `.cluster.local` will be routed over the `kilo0` interface to the cluster DNS provider. +dig kubernetes.default.svc.cluster.local +short +# > 10.43.0.1 +``` + +> **Note**: The `connect` command is currently only supported on Linux. + +> **Note**: The `connect` command requires the `CAP_NET_ADMIN` capability in order to configure the host's networking stack; unprivileged users will need to use `sudo` or similar tools. ### graph