Skip to main content


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;
  • improving the development flow of applications by running them locally and connecting them to the cluster;
  • 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:

kind: Peer
name: squat
- # Example IP address on the peer's interface.
publicKey: GY5aT1N9dTR/nJnT1N2f4ClZWVj0jOAld0r8ysWLyjg=
persistentKeepalive: 10

Then, apply the resource to the cluster:

kubectl apply -f peer.yaml

Now, the kgctl tool can be used to generate the WireGuard configuration for the newly defined peer:

kgctl showconf peer $PEER

This will produce some output like:

PublicKey = 2/xU029dz/WtvMZAbnSzmhicl8U1/Y3NYmunRr8EJ0Q=
AllowedIPs =,,
Endpoint =

The configuration can then be applied to a local WireGuard interface, e.g. wg0:

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

for ip in $(kgctl showconf peer $PEER | grep AllowedIPs | cut -f 3- -d ' ' | tr -d ','); do
sudo ip route add $ip dev $IFACE

Once the routes are in place, the connection to the cluster can be tested. For example, try connecting to the API server:

curl -k https://$(kubectl get endpoints kubernetes | tail -n +2 | tr , \\t | awk '{print $2}')

Likewise, the cluster now also has layer 3 access to the newly added peer. From any node or Pod on the cluster, one can now ping the peer:


If the peer exposes a layer 4 service, for example an HTTP server listening on TCP port 80, then one could also make requests against that endpoint from the cluster:


Kubernetes Services can be created to provide better discoverability to cluster workloads for services exposed by peers, for example:

cat <<'EOF' | kubectl apply -f -
apiVersion: v1
kind: Service
name: important-service
- port: 80
apiVersion: v1
kind: Endpoints
name: important-service
- addresses:
- ip:
- port: 80

See the multi-cluster services docs for more details on connecting clusters to external services.

Although it is not a primary goal of the project, the VPN created by Kilo can also be used by peers as a gateway to the Internet; for more details, see the VPN server docs.