Replicators

Replicators are LXD entities that periodically copy instances from one cluster to another across a cluster link. They are designed for active-passive disaster recovery, where a leader cluster runs all workloads and a standby cluster stays ready to take over if the leader fails.

Leader and standby projects

Replication is configured at the project level. Both clusters have a project with the same name, and each project has a replica mode:

  • leader: The project is writable. Instances in this project are the source of replication. The replicator runs from this cluster.

  • standby: Instances in this project are replicas, kept in sync by the replicator. New instances cannot be created directly in this project, and existing instances cannot be started. The project must be promoted to leader during a failover before instances can be started.

  • (empty): The project is not part of any replication setup. This is the default for new projects.

Replica mode is managed via lxc project promote-replica, lxc project demote-replica, and lxc project clear-replica (which resets the replica mode back to empty). It is not a configuration key and cannot be set with lxc project set.

Only the standby project needs the replica.cluster configuration key, which identifies the cluster link that is allowed to push replication data into it. The leader project does not need this key because the replicator defines the target cluster.

The leader project pushes its instances to the standby project over the cluster link. The standby project mirrors the leader at the time of the last replicator run.

How replication works

When a replicator runs, LXD performs an incremental refresh of every instance in the leader project to the standby project, together with the custom storage volumes attached only to that instance. Instances and volumes that do not yet exist on the standby are created; existing ones are updated to match the leader’s current state. A custom volume attached to more than one instance is not replicated and must exist on the standby before the instances using it can be replicated. A volume attached through a profile is replicated when one instance alone uses it. Because a profile device must point at an existing volume, create the volume on the standby and add the device to the standby’s copy of the profile before the first run; the run then refreshes it. Without the device the run refuses the instance before any data is sent. Custom volumes are only replicated when the project has features.storage.volumes=true; projects that inherit volumes from the default project have no project-local custom volumes to replicate.

Before each refresh, LXD creates a point-in-time snapshot of each instance on the leader, capturing its root disk and the custom volumes attached only to it at the same moment. This provides a consistent rollback point on the source cluster in case anything goes wrong during replication, and the volume snapshots travel to the standby with the volumes. The exception is instances that already have a snapshots.schedule configured and no custom volume attached: their scheduled snapshots already provide point-in-time history, so LXD skips the extra snapshot to avoid redundancy. Scheduled snapshots capture the root disk alone, so an instance with custom volumes always gets a snapshot here.

Replication can be triggered manually with lxc replicator run, or scheduled automatically using a cron expression in the schedule configuration key.

Failover and recovery

If the leader cluster fails, the standby project can be promoted with lxc project promote-replica. This makes the project writable and allows instances to be started. If the leader cluster is unreachable, validation against it is skipped automatically. Use --force to skip all validation without attempting to connect, which is useful when the leader is known to be down or during a planned takeover.

When the original leader comes back online, it can be re-synced from the new leader by running the replicator in restore mode (lxc replicator run --restore), then returning both projects to their original roles with lxc project demote-replica and lxc project promote-replica. In restore mode, the remote leader’s instance list is used as the authoritative source: instances that were created on the new leader after failover are also created on the recovering cluster, not just the instances that existed before the failure.

See How to perform disaster recovery with replicators for step-by-step instructions.

Replicators vs. storage replication

LXD supports two distinct approaches to cross-site disaster recovery:

Replicators

Storage replication

Level

LXD instance layer

Storage array layer

Mechanism

Incremental instance refresh over cluster links

Vendor storage replication (Ceph RBD mirroring, PowerFlex RCG, etc.)

Scheduling

Controlled by LXD (schedule config key)

Controlled by the storage vendor

Requires cluster link

Yes

No

Recovery method

Promote standby project with lxc project promote-replica

Promote storage array, then run lxd recover

Snapshot support

Automatic pre-replication snapshots

Depends on storage vendor

Use replicators when you want LXD to manage replication end-to-end across two clusters without dependency on a specific storage backend. Use storage replication when you need replication at the storage array level, or when you are not using cluster links.