How to create cluster links

Cluster links connect separate LXD clusters. There are two link types — bidirectional and unidirectional — each with a different creation flow.

Prepare authentication

Before creating bidirectional or unidirectional cluster links, set up proper authentication groups and manage permissions:

lxc auth group create <group-name>
lxc auth group permission add <group-name> <entity-type> <entitlement>

The example below shows how to create an authentication group for each cluster called link with the admin entitlement on the server entity type:

Example: Cluster A

lxc auth group create link
lxc auth group permission add link server admin

Example: Cluster B

lxc auth group create link
lxc auth group permission add link server admin

Adjust the permissions according to your security requirements. Fine-grained permissions can be applied to control what operations each cluster can perform on the other.

For example, you can create a more restricted group for backup operations only:

lxc auth group create backup
lxc auth group permission add backup instance my-instance can_manage_backups

Create a bidirectional cluster link

To create a bidirectional cluster link between two clusters (Cluster A and Cluster B), you must create the link on both sides. Follow these steps:

1. On Cluster A, create a new cluster link to Cluster B and receive a trust token:

   CLIUI

   lxc cluster link create <name-of-link-to-cluster-b> --auth-group <auth-group-name>
   

   This command:

   • Creates a pending identity for Cluster B under the link name you provided.

   • Assigns this identity to the specified authentication group.

   • Returns a trust token.

   Copy the trust token. You’ll need it for the next step.

   Example:

   lxc cluster link create cluster_b --auth-group clusters
   

2. On Cluster B, create the corresponding cluster link using the trust token from Cluster A:

   CLIUI

   lxc cluster link create <name-of-link-to-cluster-a> --token <token-from-A> --auth-group <auth-group-name>
   

   This command:

   • Verifies the token’s fingerprint against Cluster A’s certificate.

   • Creates an identity for Cluster A under the name you provided and assigns it to the specified authentication group.

   • Activates the pending link with Cluster A by sending Cluster B’s certificate.

   • Establishes bidirectional trust between the clusters.

   Example:

   lxc cluster link create cluster_a --token <token-from-A> --auth-group clusters
   

Create a unidirectional cluster link

A unidirectional link lets Cluster A access Cluster B’s resources, but Cluster B cannot initiate requests to Cluster A. Cluster B creates an identity for Cluster A, but Cluster A does not create an identity for Cluster B.

Follow these steps:

1. On Cluster B (the target), issue a pending identity token:

   lxc auth identity create cluster-link/<name-for-cluster-a> --auth-group <auth-group-name>
   

   This command creates a pending Cluster link certificate identity on Cluster B and returns a trust token.

   Example:

   lxc auth identity create cluster-link/cluster_a --auth-group clusters
   

2. On Cluster A (the initiator), create the cluster link using the token from Cluster B:

   lxc cluster link create <name-for-cluster-b> --token <token-from-B> --unidirectional
   

   This command:

   • Pins Cluster B’s certificate on Cluster A.

   • Calls back to Cluster B to activate Cluster B’s pending identity for Cluster A.

   • Stores Cluster B’s addresses in volatile.addresses so Cluster A can reach B.

   Example:

   lxc cluster link create cluster_b --token <token-from-B> --unidirectional
   

After these steps, Cluster A has a link with type: unidirectional and no associated identity. Cluster B has an active Cluster link certificate identity for Cluster A but no cluster link record.

View the underlying identities

LXD creates Cluster link certificate identities differently depending on the link type:

• Bidirectional links: each cluster creates an identity for the other. On either cluster, view the identity for the remote cluster with:

  lxc auth identity show tls/<cluster-link-name>
  

• Unidirectional links: only the target cluster (B) has an identity for the initiator cluster (A). The initiator cluster has no associated identity. To view the identity, run the following on Cluster B:

  lxc auth identity show tls/<name-for-cluster-a>
  

The output shows the identity with the type Cluster link certificate.

Next steps

• How to set up replicators — set up replicators to sync instances across this link for active-passive disaster recovery.

• How to manage cluster links — view, configure, and delete existing cluster links.