Liqo: making several Kubernetes clusters behave like one

The problem: several clusters that cannot talk to each other

Infrastructure drifts. A team ends up with a cluster on GKE for one product, a cluster on AKS for another, an OpenShift installation on premise, and an edge site with its own small cluster. Each is fine on its own, and together they are a problem: capacity sits idle in one while another is short of nodes, a service in one cluster cannot be called from another, and a stateful workload cannot be replicated across sites without someone writing the failover logic.

Liqo is an open source project that enables dynamic and seamless Kubernetes multi-cluster topologies, supporting heterogeneous on premise, cloud and edge infrastructures. The project description is short, and the ambition is large: treat a set of independent clusters as one pool of resources without asking the application to know that it is spread out.

The audience is platform engineers and operators who have ended up with more than one cluster and want them to be useful together. This is emphatically not a developer library, and it is not a managed service. It is a large Go control plane that you install into each cluster you want to join.

The scope of a multi-cluster project is where most of the difficulty lives, and Liqo names its four areas explicitly: peering, offloading, the network fabric and the storage fabric. Each of those is a separate engineering discipline, and the fact that a project has to address all four tells you what you are signing up for.

Peering: how two clusters negotiate a relationship

Peering is the automatic peer-to-peer establishment of resource and service consumption relationships between independent and heterogeneous clusters. The selling point is what you do not have to do: the documentation says there is no need to worry about complex VPN configurations and certification authorities, because everything is transparently self-negotiated.

That is a real simplification, and it is also the part to be careful about. Self-negotiated means Liqo is establishing trust between clusters on its own, which means the trust model, the credential exchange and the identity of the remote cluster all have to be handled inside the project rather than by your network team. For a platform team that already runs a service mesh or a custom mutual TLS layer, that is a decision point, not a convenience.

The peer relationship is what everything else hangs off. Once two clusters are peered, resource and service consumption between them becomes possible, and the network fabric and the storage fabric have something to work with. The examples in the repository are ordered to match that progression, starting from a quick start that gives an overview of what Liqo can do and moving on to offloading with policies, offloading a service, stateful applications, global ingress and replicated deployments.

The peer relationship is also where the topologies get interesting. Liqo describes its goal as dynamic and seamless, and the cluster topology in use is not fixed, which is a considerably harder problem than connecting two known clusters by hand.

Offloading: a remote cluster presented as a virtual node

Offloading is the workload placement feature, and the mechanism is the part that makes it usable.

The documentation says workloads are offloaded to remote clusters without requiring any modification to Kubernetes or the applications themselves, and that multi-cluster is made native and transparent by collapsing an entire remote cluster to a virtual node compliant with the standard Kubernetes approaches and tools. A remote cluster therefore appears to the scheduler as a single node, and the scheduler can send a pod there the way it sends a pod anywhere else.

That design comes from Virtual Kubelet, and the go.mod file shows it as a direct dependency at version 1.11.0. The project documentation also notes that the project includes code from the Virtual Kubelet project, licensed under the Apache 2.0 licence, and the licence section repeats that Liqo is distributed under the Apache-2.0 licence.

The scheduler-facing view is a double-edged sword. It is what makes offloading transparent, and it is also what hides the remote cluster's real shape from the scheduler, so placement decisions are made on the basis of a virtual node rather than on the actual capacity behind it. Policies are the answer to that, and the project has an example dedicated to tuning namespace offloading and using policies to select which clusters may host each workload.

Two related examples complete the picture. Offloading a service shows how to create a multi-cluster service and consume it from each connected cluster, and replicated deployments shows how to deploy an application by replicating it on multiple remote clusters. Between them they cover the two obvious offloading shapes: one workload in one place, and one workload in many places.

The fabrics: pod-to-pod reachability and remote stateful workloads

The network fabric handles connectivity, and its claim is about independence from the underlying configuration: transparent multi-cluster pod-to-pod and pod-to-service connectivity, regardless of the underlying configurations and CNI plugins. You can natively access the services exported by remote clusters, and spread interconnected application components across multiple infrastructures, with all cross-cluster traffic flowing through secured network tunnels.

The Go dependencies show the implementation. WireGuard appears twice in go.mod, the tunnel library and its control library, and there is also a dependency on nftables and another on netlink, so the data path is built from kernel level packet filtering and WireGuard tunnels rather than from a user space proxy. That is the right choice for a data path, and it also means the clusters need the kernel features and the privileges to program nftables rules, which is a real operational constraint rather than a detail.

The storage fabric covers the harder problem. It provides support for remote execution of stateful workloads according to the data gravity approach, and it extends standard high availability deployment techniques, such as a database deployment, to the multi-cluster scenario for increased guarantees, all without the complexity of managing multiple independent cluster and application replicas. The stateful applications example is the one to read if this is your use case.

Global ingress is the remaining piece of the puzzle. That example routes external traffic to multi-cluster applications through a global ingress and automatic DNS configurations, and the go.mod dependencies on a DNS library and an HTTP router match that description.

Installing Liqo: liqoctl, the Makefile and the kind target

The installation path runs through a Go binary called liqoctl, and the Makefile shows exactly how it is built and used. The ctl target compiles the CLI with the git commit stamped into the version string:

	go build -o ${BINDIR} -buildvcs=false -ldflags="-s -w -X 'github.com/liqotech/liqo/pkg/liqoctl/version.LiqoctlVersion=$(GIT_COMMIT)'" ./cmd/liqoctl

The install target depends on the manifests and on that binary, and then runs the installer against a target cluster:

	$(BINDIR)/liqoctl install $(TARGET) --generate-name

The default value of TARGET is kind, which is a useful detail, because it means the default path is a local Kubernetes-in-Docker cluster for testing rather than a production cluster. The other targets are set with the same variable, and the repository carries a .krew.yaml file, which is the manifest format for publishing a kubectl plugin, so liqoctl is also usable as a plugin invoked through kubectl.

Removal is a first class target too. There is an uninstall target and a purge variant that adds the purge flag, so a teardown that removes everything the install created is a supported operation rather than a manual cleanup.

For learning the system rather than installing it, the repository ships a set of examples with a common shell script, and the documentation lists a quick start, offloading with policies, offloading a service, stateful applications, global ingress, replicated deployments and provisioning with Terraform, the last of which covers a Liqo Terraform provider. There is also a devcontainer configuration in the repository, which suggests the authors develop inside a container.

The Go codebase, the dependencies and the test story

The module is github.com/liqotech/liqo and it targets a recent Go toolchain:

module github.com/liqotech/liqo

go 1.27.2

The dependency list explains a lot about what the project does. There are cloud provider SDKs for Azure and AWS, the OpenShift API and client-go bindings, the Prometheus operator APIs alongside the Prometheus client, Helm client libraries for chart management, Ginkgo and Gomega for the test suites, terratest for infrastructure testing, a DNS library and an HTTP router for the ingress side, nftables and netlink for the network fabric, and conntrack for connection tracking. Cobra and pflag provide the command line interface, and pterm handles the terminal output.

The layout follows the usual Go convention for a project of this size: apis/ for the custom resource definitions, cmd/ for the command entry points, internal/ and pkg/ for the implementation, deployments/ for the Helm charts and manifests, examples/, docs/, hack/, build/ and test/.

Testing is a first class concern, and the Makefile shows it. The test target runs unit and e2e suites, the unit target depends on a test container built from build/liqo-test/Dockerfile and runs it with the repository bind mounted, and there is a PACKAGE_PATH variable so a single package can be tested. A separate target builds a documentation image with a flag that distinguishes production from development builds.

The repository also carries a CodeQL workflow, a Go report card badge, a golangci configuration, a pre-commit configuration, a gitguardian configuration and a devcontainer setup, which is a fairly complete picture of a project that takes its own engineering seriously.

Providers, releases, licence and the case against it

The project states that it was kicked off at the Polytechnic of Turin in Italy and is actively maintained by the Liqo community, with a Slack workspace, a public community meeting schedule and a governance document in the repository. The release history is recent and regular: v1.2.0 on 2026-07-03, v1.1.2 on 2026-03-03 and v1.1.1 on 2026-02-17, and the repository is not archived with the last push on 2026-10-15. The documentation is published through readthedocs at docs.liqo.io with a stable branch, and the installation pages are parameterised by provider, with badges for Google GKE, Azure AKS, Amazon EKS and OpenShift Container Platform.

Now the case against it. A multi-cluster fabric puts a control plane and a data path between your workloads and your users, and every cross-cluster hop is a hop that can fail, that adds latency and that your monitoring has to understand. If a single cluster, sized properly, can carry the workload, then this entire system is complexity bought for nothing. And the alternative approach to the same goal, growing one cluster and splitting it by namespace, is simpler in a way that matters at three in the morning.

There is also a middle path to consider, which is the multi-cluster story that Liqo is explicitly designed around: several clusters that are genuinely independent, on different providers or in different locations, that you do not want to unify because they belong to different teams or different compliance boundaries. In that case the cost of a fabric is the price of the feature, and the alternatives are hand-built federation or a mesh that only solves the networking half.

One more caveat is about licensing, and it is benign here. The project includes code from Virtual Kubelet, which is Apache 2.0, and Liqo itself is distributed under the Apache-2.0 licence, with a LICENSE file at the root. The permissions are permissive, so embedding or modifying Liqo in an internal platform carries no copyleft obligation, provided the notice is kept.

Editorial conclusion

Adopt Liqo if you already run several independent Kubernetes clusters, on different providers or across on premise and edge sites, and you want to schedule workloads across them and reach services between them without rewriting your applications. Do not adopt it if a single large cluster can hold your workload, since the control plane, the network fabric and the cross-cluster hops all add cost for a problem you do not have. Before you install, read the quick start example for your provider, confirm the two clusters can reach each other over the addresses Liqo negotiates, and check the version your provider supports, because v1.2.0 dates from 2026-07-03.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. liqotech/liqo on GitHub
3. Project website
4. README
5. Releases