# How to set up replicators Replicators sync instances across LXD cluster links. This is useful for active-passive disaster recovery, where a leader (active) cluster handles all workloads while a standby cluster remains ready to take over if the leader fails. LXD supports this strategy using project replicators over a [cluster link](https://canonical.com/lxd/docs/latest/explanation/clusters/index.html.md#exp-cluster-links). ## Prerequisites Before setting up replicators: 1. Two LXD clusters must be initialized. We will call them “leader” and “standby”. 2. You need sufficient permissions on both clusters to establish links and manage projects. 3. A [cluster link must be established](https://canonical.com/lxd/docs/latest/howto/cluster_links_create/index.html.md#howto-cluster-links-create) between the two clusters. 4. Network connectivity must exist between the clusters. ## Prepare authentication Replicators communicate over cluster links, so the linked cluster identities must be granted the permissions they need on the replicated project. Configure these permissions using authentication groups and [Manage permissions](https://canonical.com/lxd/docs/latest/explanation/authorization/index.html.md#manage-permissions). For project replication, the cluster-link identity on each cluster typically needs at least these permissions: - `operator` on the replicated project, so it can perform instance replication work in that project - `can_edit` on the replicated project, so replica project configuration can be validated and updated as part of the workflow For example, if the replicated project is called `myproject`, you can prepare an authentication group on each cluster before creating the cluster links: ```bash lxc auth group create replicators lxc auth group permission add replicators project myproject operator lxc auth group permission add replicators project myproject can_edit ``` Then create the cluster links with that authentication group, as described in [How to create cluster links](https://canonical.com/lxd/docs/latest/howto/cluster_links_create/index.html.md#howto-cluster-links-create). ## Configure projects for replication Both clusters need a project with the same name. Only the standby project requires the [`replica.cluster`](https://canonical.com/lxd/docs/latest/reference/projects/index.html.md#project-replica:replica.cluster) configuration key; the leader project does not need it because the replicator defines the target cluster. 1. On the leader cluster, create a project: CLI ```bash lxc project create ``` UI Expand the Project drop-down and select + Create project at the bottom. Enter a name and optionally a description for the new project. 2. On the standby cluster, create a project with the same name and configure it to accept replication from the leader cluster: CLI ```bash lxc project create -c replica.cluster= ``` UI Expand the Project drop-down and select + Create project at the bottom. Enter the same name as in the previous step, and optionally a description for the new project. Go to the new project’s configuration and select the Replication tab. Under Replica cluster, select the cluster link established between the standby and the leader. 3. On the standby cluster, demote the project to standby mode. This prevents new instances from being created in the project and existing instances from being started. The project must be promoted to `leader` during a failover before instances can be started. CLI ```bash lxc project demote-replica ``` UI Under Replica mode, click Demote to standby. 4. On the leader cluster, promote the project to leader mode: CLI ```bash lxc project promote-replica ``` UI Go to the leader project’s configuration and select the Replication tab. Under Replica mode, click Promote to leader. ## Create a replicator After configuring the projects on both clusters, create a replicator on the leader cluster. The `cluster` configuration key is required and must be set to the name of an existing cluster link. Each cluster link can be targeted by at most one replicator per project. Creating or updating a replicator to target a cluster link already used by another replicator in the same project fails with a conflict error. CLI ```bash lxc replicator create cluster= --project ``` For example: ```bash lxc replicator create my-replicator cluster=lxd-standby --project myproject ``` You can also create a replicator with a schedule: ```bash lxc replicator create my-replicator cluster=lxd-standby schedule="@daily" --project myproject ``` UI Click Clustering in the navigation sidebar, then select Replicators from the expanded drop-down list. Click on the + Create replicator button to open the side panel. Select the cluster link established between the leader and the standby. Enter a name and optionally a description for the new replicator. Select the [project that you configured](#howto-replicators-project-setup). You can also enter a schedule. Click Create. See [Replicator configuration](https://canonical.com/lxd/docs/latest/reference/replicator_config/index.html.md#ref-replicator-config) for all available configuration options. ## Run a replicator To manually trigger a replicator run: CLI Use the following command on the leader cluster: ```bash lxc replicator run ``` UI On the leader cluster, click Clustering in the navigation sidebar, then select Replicators from the expanded drop-down list. Click on the “run” button at the end of the replicator’s row. Alternatively, click on a replicator name to view its detail page, then click on the Run button in the header. This syncs all instances in the source project, together with the custom volumes attached only to them, to the standby cluster. To schedule replication automatically, set the `schedule` configuration key with a cron expression: CLI ```bash lxc replicator set schedule="0 0 * * *" ``` UI In the Create replicator or Edit replicator side panel, enter a cron expression in the Schedule input box. ## Snapshot before replication Each replicator run performs an incremental instance sync to the standby cluster using the equivalent of `lxc copy --refresh`. This transfers only the data that has changed since the last sync, using any existing snapshots as a reference point to minimize the amount of data transferred. Before the incremental copy, LXD creates a point-in-time snapshot of each source instance. This gives the copy operation a consistent reference point, which reduces the amount of data transferred on each sync and provides a rollback point on the source in case anything goes wrong during replication. Snapshot naming and expiry are controlled entirely by the instance’s own configuration (for example [`snapshots.pattern`](https://canonical.com/lxd/docs/latest/reference/instance_options/index.html.md#instance-snapshots:snapshots.pattern) and [`snapshots.expiry`](https://canonical.com/lxd/docs/latest/reference/instance_options/index.html.md#instance-snapshots:snapshots.expiry)), or by the profile applied to the instance. The replicator does not impose its own naming scheme. If an instance already has a [`snapshots.schedule`](https://canonical.com/lxd/docs/latest/reference/instance_options/index.html.md#instance-snapshots:snapshots.schedule) set at the instance or profile level, the replicator skips creating a new snapshot and reuses the most recent existing snapshot as the reference point for the incremental copy instead. #### NOTE Snapshots created by replication accumulate over time. Use `snapshots.expiry` on the instance or profile to automatically prune them, or delete them manually with `lxc snapshot delete`. ## Next steps Once replicators are running, see [How to manage replicators](https://canonical.com/lxd/docs/latest/howto/replicators_manage/index.html.md#howto-replicators-manage) to view, configure, or delete replicators, and [How to perform disaster recovery with replicators](https://canonical.com/lxd/docs/latest/howto/replicators_dr/index.html.md#howto-replicators-dr) to fail over to the standby cluster if the leader becomes unavailable.