Once Liqo is installed in your cluster, you can start discovering new peers. Specifically, you can rely on three different methods to discover other clusters:

  1. LAN Discovery.
  2. Manual Configuration: manual addition of specific clusters to the list of known ones. This method is particularly appropriate outside LAN, without requiring any DNS configuration.
  3. DNS Discovery: automatic discovery of the clusters associated with a specific DNS domain (e.g. This is achieved by querying specific DNS entries. This looks similar to the discovery of voice-over-IP SIP servers, and it is mostly oriented to big organizations that wish to adopt Liqo in production.

Depending on your environment, you only have to decide the proper discovery method. They are detailed below:

LAN Discovery

Automatic discovery of neighboring clusters available in the same LAN. It looks similar to the automatic discovery of Wi-Fi hotspots, and it is particularly suitable when your cluster has a single node (e.g., in a combination with K3s). Liqo can automatically discover any available clusters running on the same L2 Broadcast Domain. Besides, mDNS discovery implies also that your cluster is discoverable by others.

Enable and Disable the discovery on LAN

LAN discovery is enabled by default. You can disable it by setting to false the enable-lan-discovery flag of liqoctl install. For example:

liqoctl install ${YOUR_PROVIDER} --cluster-name ${YOUR_CLUSTER_NAME} --enable-lan-discovery=false

where ${YOUR_PROVIDER} is the provider for your cluster and ${YOUR_CLUSTER_NAME} is the name you want to assign to it.

If you want to turn it on again you just have to:

liqoctl install ${YOUR_PROVIDER} --cluster-name ${YOUR_CLUSTER_NAME} --enable-lan-discovery=true

Manual Configuration

In Liqo, remote clusters are defined as ForeignClusters: each time a new ForeignCluster resource is added in a Liqo cluster, it is possible to peer with it.

Forging the ForeignCluster

A ForeignCluster resource needs the authentication service URL and the port to be set: it is the backend of the authentication server (mandatory to peer with another cluster).

The address is or the hostname or the IP address where it is reachable. If you specified a name during the installation, it is reachable through an Ingress (you can get it with kubectl get ingress -n liqo), if an ingress is not configured, the other cluster is exposed with a NodePort Service, you can get one if the IPs of your cluster’s nodes (kubectl get nodes -o wide).

The port where the remote cluster’s auth service is reachable, if you are using an Ingress, it should be 443 by default. Otherwise, if you are using a NodePort Service you can get the port executing kubectl get service -n liqo liqo-auth, an output example could be:

NAME           TYPE       CLUSTER-IP    EXTERNAL-IP   PORT(S)         AGE
liqo-auth      NodePort   <none>        443:30740/TCP   2m7s

An example of ForeignCluster resource can be:

kind: ForeignCluster
  name: my-cluster
  outgoingPeeringEnabled: "Yes" # optional (defaults to "Auto")
  foreignAuthUrl: "https://<ADDRESS>:<PORT>"

When you create the ForeignCluster, the Liqo control plane will contact the foreignAuthUrl (i.e. the public URL of a cluster authentication server) to retrieve all the required cluster information.

Access the cluster configurations

You can get the cluster configurations exposed by the Auth Service endpoint of the other cluster. This allows retrieving the information necessary to peer with the remote cluster.

curl --insecure https://<ADDRESS>:<PORT>/ids

DNS Discovery

In addition to LAN discovery and manual configuration, Liqo supports DNS-based discovery: such a mechanism is useful, for instance, when dealing with multiple clusters, which are dynamically spawned and decommissioned. The DNS discovery procedure requires two orthogonal actions to be enabled:

  1. Register your cluster into your DNS server to make it discoverable by others (the required parameters are available in the section below).
  2. Connect to a foreign cluster, specifying the remote domain.

Register the home cluster

To allow the other clusters to peer with your cluster(s), you need to register a set of DNS records that specify the cluster(s) available in your domain, with the different parameters required to establish the connection.

In a scenario where we have to manage multiple clusters’ discovery, it can be useful to manage the entire set updating it in a unique place. We only have to know how the Authentication Service is reachable from the external world.

DNS Configuration

In the following example, we present a bind9-like configuration for a hypothetical domain It exposes two Liqo-enabled cluster named liqo-cluster and liqo-cluster-2. The first one exposes the Auth Service at, while the second at                  PTR
                                 SRV     0 0 443   SRV     0 0 8443      A    A

Remember to adapt the configuration according to your setup, modifying the urls, ips and ports accordingly.

Expand here to know more about the meaning of each record.

Connect to a remote cluster

To leverage the DNS discovery to peer to a remote cluster, it is necessary to specify the remote domain called SearchDomain. When a SearchDomain is configured, Liqo performs periodical queries on specific search domains looking for new clusters to peer with. For any SearchDomain, you need to configure the following parameters:

  1. Domain: the domain where the cluster you want to peer with is located.
  2. Name: a mnemonic name to identify the domain.
  3. Join: to specify whether to trigger the peering procedure automatically.

Using kubectl, it is also possible to perform the following configuration. A SearchDomain for the domain, may be look like:

cat << "EOF" | kubectl apply -f -
kind: SearchDomain
  autojoin: true

Get discovered clusters

Using kubectl, you can manually obtain the list of discovered foreign clusters by typing:

kubectl get foreignclusters
ff5aa14a-dd6e-4fd2-80fe-eaecb827cf55   Established              Established              Established         Established             93s