Skip to content
Kilo is a multi-cloud network overlay built on WireGuard and designed for Kubernetes (k8s + wg = kg)
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd manifests,pkg/encapsulation: Flannel compatibility May 13, 2019
docs docs: fix links May 18, 2019
manifests manifests: default hostname to spec.nodeName May 17, 2019
pkg pkg/mesh: don't let hostname resolution stop mesh May 17, 2019
vendor vendor: revendor May 16, 2019
.gitignore Makefile,Dockerfile: add multi-arch images May 16, 2019
.header init Jan 18, 2019
.travis.yml Makefile: improve tooling May 16, 2019
Dockerfile Dockerfile: update alpine repo for wg May 22, 2019
LICENSE init Jan 18, 2019
Makefile Makefile: improve tooling May 16, 2019 manifests,pkg/encapsulation: Flannel compatibility May 13, 2019
kilo.svg init Jan 18, 2019
tools.go Makefile: improve tooling May 16, 2019


Kilo is a multi-cloud network overlay built on WireGuard and designed for Kubernetes.

Build Status Go Report Card


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. In addition to creating multi-cloud clusters, Kilo enables the creation of multi-cluster services, i.e. services that span across different Kubernetes clusters.

How it works

Kilo uses WireGuard, a performant and secure VPN, to create a mesh between the different nodes in a cluster. The Kilo agent, kg, runs on every node in the cluster, setting up the public and private keys for the VPN as well as the necessary rules to route packets between locations.

Kilo can operate both as a complete, independent networking provider as well as an add-on complimenting the cluster-networking solution currently installed on a cluster. This means that if a cluster uses, for example, Flannel for networking, Kilo can be installed on top to enable pools of nodes in different locations to join; Kilo will take care of the network between locations, while Flannel will take care of the network within locations.

Installing on Kubernetes

Kilo can be installed on any Kubernetes cluster either pre- or post-bring-up.

Step 1: install WireGuard

Kilo requires the WireGuard kernel module on all nodes in the cluster. For most Linux distributions, this can be installed using the system package manager. For Container Linux, WireGuard can be easily installed using a DaemonSet:

kubectl apply -f

Step 2: open WireGuard port

The nodes in the mesh will require an open UDP port in order to communicate. By default, Kilo uses UDP port 51820.

Step 3: specify topology

By default, Kilo creates a mesh between the different logical locations in the cluster, e.g. data-centers, cloud providers, etc. For this, Kilo needs to know which groups of nodes are in each location. If the cluster does not automatically set the node label, then the annotation can be used. For example, the following snippet could be used to annotate all nodes with GCP in the name:

for node in $(kubectl get nodes | grep -i gcp | awk '{print $1}'); do kubectl annotate node $node"gcp"; done

Kilo allows the topology of the encrypted network to be completely customized. See the topology docs for more details.

Step 4: ensure nodes have public IP

At least one node in each location must have a public IP address. If the public IP address is not automatically configured on the node's Ethernet device, it can be manually specified using the annotation.

Step 5: install Kilo!

Kilo can be installed by deploying a DaemonSet to the cluster.

To run Kilo on kubeadm:

kubectl apply -f

To run Kilo on bootkube:

kubectl apply -f

To run Kilo on Typhoon:

kubectl apply -f

To run Kilo on k3s:

kubectl apply -f

Add-on Mode

Administrators of existing clusters who do not want to swap out the existing networking solution can run Kilo in add-on mode. In this mode, Kilo will add advanced features to the cluster, such as VPN and multi-cluster services, while delegating CNI management and local networking to the cluster's current networking provider. Currently, Kilo, supports running on top of Flannel.

For example, to run Kilo on Typhoon cluster running Flannel:

kubectl apply -f

See the manifests directory for more examples.


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:

cat <<'EOF' | kubectl apply -f -
kind: Peer
  name: squat
  publicKey: GY5aT1N9dTR/nJnT1N2f4ClZWVj0jOAld0r8ysWLyjg=
  persistentKeepalive: 10

This configuration can then be applied to a local WireGuard interface, e.g. wg0, with the help of the kgctl tool:

kgctl showconf peer squat > peer.ini
sudo wg setconf wg0 peer.ini

See the VPN docs for more details.

Multi-cluster Services

A logical application of Kilo's VPN is to connect two different Kubernetes clusters. This allows workloads running in one cluster to access services running in another. For example, if cluster1 is running a Kubernetes Service that we need to access from Pods running in cluster2, we could do the following:

# Register the nodes in cluster1 as peers of cluster2.
for n in $(kubectl --kubeconfig $KUBECONFIG1 get no -o name | cut -d'/' -f2); do
    kgctl --kubeconfig $KUBECONFIG1 showconf node $n --as-peer -o yaml --allowed-ips $SERVICECIDR1 | kubectl --kubeconfig KUBECONFIG2 apply -f -
# Register the nodes in cluster2 as peers of cluster1.
for n in $(kubectl --kubeconfig $KUBECONFIG2 get no -o name | cut -d'/' -f2); do
    kgctl --kubeconfig $KUBECONFIG2 showconf node $n --as-peer -o yaml --allowed-ips $SERVICECIDR2 | kubectl --kubeconfig KUBECONFIG1 apply -f -
# Create a Service in cluster2 to mirror the Service in cluster1.
cat <<'EOF' | kubectl --kubeconfig $KUBECONFIG2 apply -f -
apiVersion: v1
kind: Service
  name: important-service
    - port: 80
apiVersion: v1
kind: Endpoints
    name: important-service
  - addresses:
      - ip: $CLUSTERIP # The cluster IP of the important service on cluster1.
      - port: 80

Now, important-service can be used on cluster2 just like any other Kubernetes Service.

See the multi-cluster services docs for more details.


The topology and configuration of a Kilo network can be analyzed using the kgctl binary. For example, the graph command can be used to generate a graph of the network in Graphviz format:

kgctl graph | circo -Tsvg > cluster.svg

You can’t perform that action at this time.