Key Concepts

This page defines the core terminology, Kubernetes operator concepts, and custom resource abstractions that Site Recovery uses. Understanding these concepts will help you interpret status fields, write protection manifests, and reason about failover behavior across your clusters. Each term here appears throughout the rest of the documentation and in the resources you create and monitor with kubectl.

Deployment Models

Site Recovery supports two distinct deployment models, and several concepts apply differently depending on which model you use.

DRBD Operator model — The DRBD Operator runs on both the primary and DR clusters and manages DRBD-backed storage volumes directly. VM protection is declared through ProtectionRequest resources. This model supports two-cluster or three-cluster topologies and is the recommended path for OpenShift Virtualization environments.

Centralized storage model — A shared storage controller manages replication from the quorum cluster. VM protection is declared through ProtectionGroup resources. This model requires a three-cluster topology (quorum + primary + DR).

Test failover is only supported in the DRBD Operator deployment model.

Cluster Roles

Quorum cluster

Also called the management cluster or quorum. This is a dedicated Kubernetes cluster that hosts the management plane: failover controllers, protection controllers, the Site Manager UI, and the credentials for your primary and DR clusters. The quorum cluster does not run application workloads and does not carry storage replication traffic — it is purely a control and orchestration layer.

All FailoverRequest, ProtectionRequest, and TestFailover resources are created on the quorum cluster, inside the namespace for the relevant deployment.

Primary cluster

Also called the source cluster or active site. This is the Kubernetes cluster where your production VMs run and where storage replication originates. The protection-group-controller and, in the DRBD Operator model, the DRBD Operator itself run here.

DR cluster

Also called the disaster recovery cluster, standby cluster, standby site, or target cluster. This cluster receives replicated storage and hosts VMs only after a failover is triggered. Under normal operating conditions, VMs on the DR cluster are stopped and their volumes are kept in sync as replication targets.

Deployment and Multi-Tenancy

Deployment

Also called a DR deployment or deployment context. A deployment is a named DR configuration that links a primary cluster and a DR cluster under management by the quorum cluster. Each deployment lives in its own namespace (dr-<name>) on the quorum cluster, with dedicated credentials and its own set of controllers. This namespace isolation is what enables multi-tenant operation.

You manage deployment contexts using pgctl or the quorum-deployments.sh interactive script.

Multi-tenant quorum

Also called a multi-tenant deployment or multi-tenancy. A single quorum cluster can manage multiple independent DR deployments simultaneously, each isolated in its own dr-<name> namespace with dedicated credentials and controllers. This means one quorum cluster can protect workloads across many independent primary/DR cluster pairs from a single management plane, without any cross-deployment interference.

Protection Constructs

Protection Group

Also called a pg or PG. A ProtectionGroup is a Kubernetes custom resource that groups multiple VMs so they fail over together as a coordinated unit. It tracks the collective replication state of the group — Syncing, Consistent, or Degraded — and is the primary failover target in centralized storage deployments. When you trigger a FailoverRequest, you reference a Protection Group.

ProtectionRequest

Also called a pr or protect. A ProtectionRequest is a Kubernetes custom resource used in DRBD Operator deployments to request DR protection for a single VM. When you apply a ProtectionRequest, the protection-controller on the quorum cluster validates the VM and its PVCs, creates the necessary DRBDVolume resources, waits for replication to synchronize, and then switches the VM to use DRBD-backed frontend PVCs. The controller drives through a defined lifecycle from validation to fully protected status.

Frontend PVC

Also called a DRBD-backed PVC or frontend PersistentVolumeClaim. After protection is established for a VM, the protection-controller replaces the VM's original PVC with a DRBD-backed PersistentVolumeClaim. All VM disk I/O then flows through the DRBD replication layer, ensuring that every write is replicated to the DR cluster according to the configured replication protocol. The swap is transparent to the VM.

Failover Operations

FailoverRequest

Also called a fr or failover request. A FailoverRequest is a Kubernetes custom resource that triggers either a planned or unplanned failover for a Protection Group. You create it on the quorum cluster, and the failover-controller watches for it and orchestrates the entire failover sequence: volume promotion on the DR cluster, VM shutdown on the primary cluster (if reachable), and VM startup on the DR cluster.

Planned failover

Also called a graceful failover. A planned failover is a controlled operation where VMs on the primary cluster are gracefully stopped before volumes are promoted on the DR cluster. Because all writes are flushed before the switchover, a planned failover guarantees zero data loss regardless of replication protocol.

Unplanned failover

Also called an emergency failover or disaster failover. An unplanned failover is triggered when the primary cluster is unavailable — for example, during a site outage. The failover-controller promotes DR volumes and starts VMs without a graceful shutdown of the primary side. If you were using asynchronous replication (Protocol A), a small amount of data that had not yet been acknowledged on the DR side may be lost. With synchronous replication (Protocol C), data loss is zero even in this scenario.

Failback

Also called a reverse failover. Failback is the operation that returns VMs from the DR cluster back to the primary cluster after the primary has been restored. It also reverses the replication direction so that the primary cluster once again becomes the replication source. Failback follows the same FailoverRequest mechanism as a standard failover.

TestFailover

Also called a tf, test failover, or non-disruptive DR test. A TestFailover is a Kubernetes custom resource that initiates a non-disruptive DR validation exercise. It snapshots production volumes on the source cluster, provisions test VMs from those snapshots on the DR cluster, runs verification checks, and then cleans up — all without affecting running production workloads. Test failover is only supported in the DRBD Operator deployment model and requires CSI VolumeSnapshot support on both clusters.

The test-failover-controller automatically determines which cluster to target: it checks whether the VMs are running on the primary or DR cluster and selects the opposite cluster as the test target. This means test failovers work correctly whether you run them before or after a real failover event.

Storage and Replication

DRBDReplicationPolicy

Also called a replication policy. A DRBDReplicationPolicy is a Kubernetes custom resource used in DRBD Operator deployments to define how volumes replicate between clusters. It specifies the replication protocol (synchronous or asynchronous), storage class mappings between the primary and DR clusters, and the replication endpoints for each cluster. Each deployment typically has one DRBDReplicationPolicy that governs all protected volumes.

DRBDVolume

Also called a replicated volume. A DRBDVolume is a Kubernetes custom resource representing a single DRBD-replicated PVC. It is created automatically by the protection-controller when a ProtectionRequest is processed. It exposes sync progress and frontend PVC references, giving you per-volume visibility into replication status.

Storage class mapping

Also called storageClassMappings. A storage class mapping is a configuration entry within a DRBDReplicationPolicy that pairs a storage class name on the primary cluster with the corresponding storage class name on the DR cluster. This allows the system to provision correctly matched volumes on both sides when protection is established. You can define multiple mappings in a single policy to cover heterogeneous storage environments.

Protocol C

Also called synchronous replication or sync replication. Protocol C is DRBD's synchronous replication mode: a write is acknowledged to the application only after the data has been committed to disk on both the primary and DR clusters. This guarantees zero data loss (RPO=0) but requires a network round-trip latency of less than 50ms between clusters. Protocol C is the recommended choice for deployments where RPO=0 is a hard requirement.

Protocol A

Also called asynchronous replication or async replication. Protocol A is DRBD's asynchronous replication mode: a write is acknowledged to the application after it commits to local disk on the primary cluster, with data transmitted to the DR cluster in the background. This supports long-distance or high-latency links and imposes no strict latency requirement, but introduces a small RPO window — typically measured in seconds — representing data that has been acknowledged locally but not yet committed on the DR cluster.

Split-brain

A split-brain is a failure condition where both the primary and DR DRBD volumes simultaneously assume the primary (active) role, resulting in divergent data on each side. This can occur during network partitions. Split-brain cannot be resolved automatically; it requires manual intervention to identify which side has authoritative data and to resynchronize volumes. Site Recovery's replication-monitor component detects and surfaces this condition through ReplicationGroupStatus resources.

Replication Health and Observability

RPO

Also called Recovery Point Objective. RPO is the maximum amount of data loss, measured in time, that is acceptable if a failure occurs. With Protocol C (synchronous replication), Site Recovery achieves RPO=0. With Protocol A (asynchronous replication), Site Recovery achieves near-zero RPO, typically on the order of seconds.

RTO

Also called Recovery Time Objective. RTO is the maximum acceptable duration of downtime after a failure before VMs must be running again. Site Recovery targets 3–8 minutes for automated failover, covering the time from failover trigger to VMs running on the DR cluster.

RPOEvent

Also called an RPO violation or replication lag event. An RPOEvent is a Kubernetes custom resource that records instances where replication lag exceeded an acceptable threshold. It captures which Protection Group was affected, the observed lag value, and the severity of the violation. These resources are created by the replication-monitor component and are used for auditing and alerting on data loss risk. They are not cleared automatically and accumulate as a historical record.

ReplicationGroupStatus

Also called replication health status. A ReplicationGroupStatus is a Kubernetes custom resource that provides an aggregated replication health summary for a Protection Group. It reports overall health (Healthy, Degraded, or Critical), per-volume sync state, and the timestamp of the last successful sync. The replication-monitor component creates and updates these resources continuously so that operators and the failover-controller have a reliable view of replication readiness.

Controllers and Agents

Site Recovery's control plane is composed of several specialized controllers, each with a narrow responsibility. Understanding which controller runs where helps you direct troubleshooting and log collection to the right cluster.

The replication-monitor is deployed automatically as part of the standard Ansible playbooks and does not require separate installation steps.

Management Interfaces

pgctl

pgctl is the primary command-line tool for Site Recovery operations. You use it to manage deployment contexts, create and inspect Protection Groups, sync VMs, validate configuration, and trigger or monitor failover operations. It is the recommended interface for day-to-day scripted and interactive cluster operations.

quorum-deployments.sh

quorum-deployments.sh is an interactive shell script that provides a menu-driven interface for more than 20 operational tasks, including deploying the quorum cluster components, triggering failovers, backing up and restoring quorum state, and running health checks. It is intended for operators who prefer a guided interface for complex multi-step procedures.

Site Manager UI

The Site Manager UI is a web-based management interface deployed on the quorum cluster. It provides dashboards for cluster health, VM protection status, Protection Group management, failover triggering, and operation monitoring. The UI is a GA component and communicates with the Site Manager API backend.

Site Manager API

The Site Manager API is the Python Flask REST API backend for the Site Manager UI. It exposes endpoints for deployments, VMs, Protection Groups, operations, health, and replication status. In addition to powering the UI, it can be used for custom integrations where a programmatic interface is needed.

Inspect a Protection Group's replication health

After protecting VMs, check the aggregated replication state from the quorum cluster:

kubectl --kubeconfig $KUBECONFIG_QUORUM \
  get replicationgroupstatus -n dr-prod -o wide

Expected output:

NAME            HEALTH    VOLUMES   LAST-SYNC
my-first-pg     Healthy   3/3       2024-01-15T10:32:00Z

A Healthy status with all volumes in sync confirms the Protection Group is ready for failover.

Check for RPO violations

Review any replication lag events that have been recorded for your Protection Groups:

kubectl --kubeconfig $KUBECONFIG_QUORUM \
  get rpoevents -n dr-prod

Expected output when no violations have occurred:

No resources found in dr-prod namespace.

If violations are present, each RPOEvent shows the affected Protection Group, the observed lag, and severity — giving you an audit trail for SLA reviews.

Inspect DRBDVolume sync progress for a protected VM

In the DRBD Operator model, each protected PVC has a corresponding DRBDVolume. Check sync progress from the quorum cluster:

kubectl --kubeconfig $KUBECONFIG_QUORUM \
  get drbdvolume -n dr-prod -o wide

Expected output:

NAME                    SYNC-PROGRESS   FRONTEND-PVC              STATUS
my-vm-disk-0-drbdvol    100%            my-vm-disk-0-frontend     Synced

A Synced status at 100% confirms that the volume is fully replicated and the VM is using its DRBD-backed frontend PVC.

Create a TestFailover to validate DR readiness

This example applies a TestFailover resource on the quorum cluster. The test-failover-controller automatically selects the correct target cluster and manages the full lifecycle:

kubectl --kubeconfig $KUBECONFIG_QUORUM apply -f - <<'EOF'
apiVersion: siterecovery.trilio.io/v1alpha1
kind: TestFailover
metadata:
  name: validate-my-pg
  namespace: dr-prod
spec:
  protectionGroupRef:
    name: my-first-pg
    namespace: default
  cleanupPolicy: Manual
  retentionTime: 2h
EOF

Monitor progress by watching the resource status:

kubectl --kubeconfig $KUBECONFIG_QUORUM \
  get testfailover validate-my-pg -n dr-prod -w

Expected progression through phases:

NAME              PHASE               TARGET-CLUSTER
validate-my-pg    CreatingSnapshots   cluster2
validate-my-pg    CreatingVolumes     cluster2
validate-my-pg    CreatingVMs         cluster2
validate-my-pg    VerifyingData       cluster2
validate-my-pg    Succeeded           cluster2

When you are done reviewing results, clean up all test resources:

kubectl --kubeconfig $KUBECONFIG_QUORUM \
  delete testfailover validate-my-pg -n dr-prod

• Prepare cluster infrastructure — Networking, port, and storage prerequisites that underpin the concepts described here, including DRBD kernel module setup and LVM thin pool configuration.
• Deploy DRBD and storage components — How to install the DRBD Operator and create DRBDReplicationPolicy resources on your primary and DR clusters.
• Configure a DR deployment — How deployments and deployment contexts (dr-<name> namespaces) are created and managed on the quorum cluster.
• Protect VMs — Step-by-step guidance for creating ProtectionRequest resources and verifying that VMs reach fully protected status with synchronized DRBDVolume resources.
• Validate DR readiness with a test failover — Detailed walkthrough of the TestFailover lifecycle, phase transitions, and cleanup options.
• Execute a planned failover — How to create a FailoverRequest for a graceful, zero-data-loss switchover.
• Execute an unplanned failover — How to trigger an emergency failover when the primary cluster is unavailable.
• Perform failback — Returning VMs to the primary cluster and restoring replication direction after a failover.
• Diagnose a degraded node or replication issue — Using ReplicationGroupStatus and RPOEvent resources to identify and resolve split-brain conditions and replication lag.