{"id":13509918,"url":"https://github.com/squat/kilo","last_synced_at":"2025-04-11T11:48:56.846Z","repository":{"id":37550066,"uuid":"162610275","full_name":"squat/kilo","owner":"squat","description":"Kilo is a multi-cloud network overlay built on WireGuard and designed for Kubernetes (k8s + wg = kg)","archived":false,"fork":false,"pushed_at":"2024-06-27T16:19:49.000Z","size":15152,"stargazers_count":2104,"open_issues_count":60,"forks_count":132,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-04-03T15:07:20.497Z","etag":null,"topics":["cni","federation","kubernetes","multi-cloud","multi-cluster","networking","vpn","wireguard"],"latest_commit_sha":null,"homepage":"https://kilo.squat.ai","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/squat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-20T17:22:11.000Z","updated_at":"2025-03-28T08:01:30.000Z","dependencies_parsed_at":"2024-01-13T16:23:03.716Z","dependency_job_id":"4c79042d-ef79-45e1-ae14-9934ec9a1b1d","html_url":"https://github.com/squat/kilo","commit_stats":{"total_commits":337,"total_committers":35,"mean_commits":9.628571428571428,"dds":0.3916913946587537,"last_synced_commit":"66b81d579acf7ceb8db329f223b1f3106493e579"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squat%2Fkilo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squat%2Fkilo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squat%2Fkilo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/squat%2Fkilo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/squat","download_url":"https://codeload.github.com/squat/kilo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248388908,"owners_count":21095479,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cni","federation","kubernetes","multi-cloud","multi-cluster","networking","vpn","wireguard"],"created_at":"2024-08-01T02:01:17.093Z","updated_at":"2025-04-11T11:48:56.828Z","avatar_url":"https://github.com/squat.png","language":"Go","funding_links":[],"categories":["NetWork","Go","Install from Source","Go (531)","kubernetes","vpn","Projects"],"sub_categories":["WireGuard Tools","Mesh Network"],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"./kilo.svg\" width=\"150\" /\u003e\u003c/p\u003e\n\n# Kilo\n\nKilo is a multi-cloud network overlay built on WireGuard and designed for Kubernetes.\n\n[![Build Status](https://github.com/squat/kilo/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/squat/kilo/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/squat/kilo)](https://goreportcard.com/report/github.com/squat/kilo)\n[![Docker Pulls](https://img.shields.io/docker/pulls/squat/kilo)](https://hub.docker.com/r/squat/kilo)\n[![Slack](https://img.shields.io/badge/join%20slack-%23kilo-brightgreen.svg)](https://slack.k8s.io/)\n\n## Overview\n\nKilo connects nodes in a cluster by providing an encrypted layer 3 network that can span across data centers and public clouds.\nThe Pod network created by Kilo is always fully connected, even when the nodes are in different networks or behind NAT.\nBy allowing pools of nodes in different locations to communicate securely, Kilo enables the operation of multi-cloud clusters.\nKilo's design allows clients to VPN to a cluster in order to securely access services running on the cluster.\nIn addition to creating multi-cloud clusters, Kilo enables the creation of multi-cluster services, i.e. services that span across different Kubernetes clusters.\n\nAn introductory video about Kilo from KubeCon EU 2019 can be found on [youtube](https://www.youtube.com/watch?v=iPz_DAOOCKA).\n\n## How It Works\n\nKilo uses [WireGuard](https://www.wireguard.com/), a performant and secure VPN, to create a mesh between the different nodes in a cluster.\nThe 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.\n\nKilo 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.\nThis 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.\n\n## Installing on Kubernetes\n\nKilo can be installed on any Kubernetes cluster either pre- or post-bring-up.\n\n### Step 1: get WireGuard\n\nKilo requires the WireGuard kernel module to be loaded on all nodes in the cluster.\nStarting at Linux 5.6, the kernel includes WireGuard in-tree; Linux distributions with older kernels will need to install WireGuard.\nFor most Linux distributions, this can be done using the system package manager.\n[See the WireGuard website for up-to-date instructions for installing WireGuard](https://www.wireguard.com/install/).\n\nClusters with nodes on which the WireGuard kernel module cannot be installed can use Kilo by leveraging a [userspace WireGuard implementation](./docs/userspace-wireguard.md).\n\n### Step 2: open WireGuard port\n\nThe nodes in the mesh will require an open UDP port in order to communicate.\nBy default, Kilo uses UDP port 51820.\n\n### Step 3: specify topology\n\nBy default, Kilo creates a mesh between the different logical locations in the cluster, e.g. data-centers, cloud providers, etc.\nFor this, Kilo needs to know which groups of nodes are in each location.\nIf the cluster does not automatically set the [topology.kubernetes.io/region](https://kubernetes.io/docs/reference/kubernetes-api/labels-annotations-taints/#topologykubernetesioregion) node label, then the [kilo.squat.ai/location](./docs/annotations.md#location) annotation can be used.\nFor example, the following snippet could be used to annotate all nodes with `GCP` in the name:\n\n```shell\nfor node in $(kubectl get nodes | grep -i gcp | awk '{print $1}'); do kubectl annotate node $node kilo.squat.ai/location=\"gcp\"; done\n```\n\nKilo allows the topology of the encrypted network to be completely customized.\n[See the topology docs for more details](./docs/topology.md).\n\n### Step 4: ensure nodes have public IP\n\nAt least one node in each location must have an IP address that is routable from the other locations.\nIf the locations are in different clouds or private networks, then this must be a public IP address.\nIf this IP address is not automatically configured on the node's Ethernet device, it can be manually specified using the [kilo.squat.ai/force-endpoint](./docs/annotations.md#force-endpoint) annotation.\n\n### Step 5: install Kilo!\n\nKilo can be installed by deploying a DaemonSet to the cluster.\n\nTo run Kilo on kubeadm:\n\n```shell\nkubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/crds.yaml\nkubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/kilo-kubeadm.yaml\n```\n\nTo run Kilo on bootkube:\n\n```shell\nkubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/crds.yaml\nkubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/kilo-bootkube.yaml\n```\n\nTo run Kilo on Typhoon:\n\n```shell\nkubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/crds.yaml\nkubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/kilo-typhoon.yaml\n```\n\nTo run Kilo on k3s:\n\n```shell\nkubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/crds.yaml\nkubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/kilo-k3s.yaml\n```\n\n## Add-on Mode\n\nAdministrators of existing clusters who do not want to swap out the existing networking solution can run Kilo in add-on mode.\nIn 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.\nKilo currently supports running on top of Flannel.\n\nFor example, to run Kilo on a Typhoon cluster running Flannel:\n\n```shell\nkubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/crds.yaml\nkubectl apply -f https://raw.githubusercontent.com/squat/kilo/main/manifests/kilo-typhoon-flannel.yaml\n```\n\n[See the manifests directory for more examples](https://github.com/squat/kilo/tree/main/manifests).\n\n## VPN\n\nKilo also enables peers outside of a Kubernetes cluster to connect to the VPN, allowing cluster applications to securely access external services and permitting developers and support to securely debug cluster resources.\nIn order to declare a peer, start by defining a Kilo Peer resource:\n\n```shell\ncat \u003c\u003c'EOF' | kubectl apply -f -\napiVersion: kilo.squat.ai/v1alpha1\nkind: Peer\nmetadata:\n  name: squat\nspec:\n  allowedIPs:\n  - 10.5.0.1/32\n  publicKey: GY5aT1N9dTR/nJnT1N2f4ClZWVj0jOAld0r8ysWLyjg=\n  persistentKeepalive: 10\nEOF\n```\n\nThis configuration can then be applied to a local WireGuard interface, e.g. `wg0`, to give it access to the cluster with the help of the `kgctl` tool:\n\n```shell\nkgctl showconf peer squat \u003e peer.ini\nsudo wg setconf wg0 peer.ini\n```\n\n[See the VPN docs for more details](./docs/vpn.md).\n\n## Multi-cluster Services\n\nA logical application of Kilo's VPN is to connect two different Kubernetes clusters.\nThis allows workloads running in one cluster to access services running in another.\nFor example, if `cluster1` is running a Kubernetes Service that we need to access from Pods running in `cluster2`, we could do the following:\n\n```shell\n# Register the nodes in cluster1 as peers of cluster2.\nfor n in $(kubectl --kubeconfig $KUBECONFIG1 get no -o name | cut -d'/' -f2); do\n    kgctl --kubeconfig $KUBECONFIG1 showconf node $n --as-peer -o yaml --allowed-ips $SERVICECIDR1 | kubectl --kubeconfig $KUBECONFIG2 apply -f -\ndone\n# Register the nodes in cluster2 as peers of cluster1.\nfor n in $(kubectl --kubeconfig $KUBECONFIG2 get no -o name | cut -d'/' -f2); do\n    kgctl --kubeconfig $KUBECONFIG2 showconf node $n --as-peer -o yaml --allowed-ips $SERVICECIDR2 | kubectl --kubeconfig $KUBECONFIG1 apply -f -\ndone\n# Create a Service in cluster2 to mirror the Service in cluster1.\ncat \u003c\u003cEOF | kubectl --kubeconfig $KUBECONFIG2 apply -f -\napiVersion: v1\nkind: Service\nmetadata:\n  name: important-service\nspec:\n  ports:\n    - port: 80\n---\napiVersion: v1\nkind: Endpoints\nmetadata:\n    name: important-service\nsubsets:\n  - addresses:\n      - ip: $CLUSTERIP # The cluster IP of the important service on cluster1.\n    ports:\n      - port: 80\nEOF\n```\n\nNow, `important-service` can be used on `cluster2` just like any other Kubernetes Service.\n\n[See the multi-cluster services docs for more details](./docs/multi-cluster-services.md).\n\n## Analysis\n\nThe topology and configuration of a Kilo network can be analyzed using the [`kgctl` command line tool](./docs/kgctl.md).\nFor example, the `graph` command can be used to generate a graph of the network in Graphviz format:\n\n```shell\nkgctl graph | circo -Tsvg \u003e cluster.svg\n```\n\n\u003cimg src=\"./docs/graphs/location.svg\" /\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquat%2Fkilo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsquat%2Fkilo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsquat%2Fkilo/lists"}