Key Concepts

This page defines the core terminology and Kubernetes concepts you need to understand before deploying and operating Trilio Site Recovery. Whether you are planning a new DR deployment, protecting virtual machines, running a test failover, or diagnosing a replication issue, the terms on this page appear throughout the documentation and in the custom resources you interact with daily. Reading through these definitions before following any workflow will help you make informed decisions about topology, replication mode, and recovery objectives.

Deployment topology

Trilio Site Recovery runs as a Kubernetes operator across two or three OpenShift clusters. Understanding how those clusters relate to each other is fundamental to every workflow.

Quorum cluster

The quorum cluster (also called the management cluster or Site C) is the third OpenShift cluster in a three-cluster topology. It hosts the management plane—the failover controllers, protection controllers, and the TSR web console—and does not run application VMs or relay DRBD replication traffic. All DR orchestration CRDs (FailoverRequest, ProtectionRequest, TestFailover) are applied to namespaces on the quorum cluster. Because the quorum cluster is isolated from both the primary and DR clusters, it continues to function and make decisions even when either workload cluster is unavailable.

DR deployment

A deployment (also called a DR deployment or deployment namespace) is the fundamental management unit in Site Recovery. It is a named configuration that links a primary cluster, a DR cluster, and the quorum cluster under a single management namespace of the form dr-<name> on the quorum cluster. Each deployment is independently managed and isolated from other deployments on the same quorum cluster, which enables multi-tenant DR management from a single quorum cluster.

Storage replication

Site Recovery performs disaster recovery at the storage layer, replicating VM-attached PersistentVolumeClaims block-by-block between clusters using DRBD. The two replication protocols represent different trade-offs between data safety and distance.

Protocol C — synchronous replication

Protocol C (synchronous replication) means that a write is acknowledged to the application only after it has been committed to disk on both the primary cluster and the DR cluster. This guarantees zero data loss: RPO = 0. Protocol C requires round-trip network latency below approximately 50 ms between primary and DR worker nodes. Use it when your primary and DR clusters are in the same metropolitan area or are connected by a low-latency dedicated link.

Protocol A — asynchronous replication

Protocol A (asynchronous replication) means that writes complete after the local disk commit and are transmitted to the DR cluster in the background. This allows replication over high-latency or long-distance links at the cost of a small RPO window, typically measured in seconds depending on replication lag. Use it when your clusters are geographically distant and a sub-50 ms round-trip link is not available.

Frontend PVC

A frontend PVC (also called a DRBD-backed PVC) is a PersistentVolumeClaim that replaces a VM's original PVC after protection is applied. It is the live DRBD block device that Site Recovery keeps synchronized to the DR side. From the VM's perspective, the frontend PVC is an ordinary PVC; DRBD operates transparently below the filesystem layer.

Recovery objectives

RPO — Recovery Point Objective

RPO (Recovery Point Objective) is the maximum amount of data loss, measured in time, that is acceptable if a disaster occurs. Protocol C achieves RPO = 0 because every acknowledged write exists on both clusters before the application receives confirmation. Protocol A achieves an RPO of seconds, bounded by the current replication lag. RPO violations are recorded as RPOEvent custom resources.

RTO — Recovery Time Objective

RTO (Recovery Time Objective) is the maximum acceptable time from declaring a disaster to having VMs running on the DR cluster. Site Recovery targets an automated RTO of 3–8 minutes, driven by the failover controller coordinating VM shutdown, DRBD volume promotion, and VM startup across clusters without manual intervention.

Protection model — DRBD Operator

Site Recovery currently uses the DRBD Operator deployment model, where distributed DRBD Operator instances on each workload cluster manage storage resources. Replication configuration and VM protection are expressed through the following CRDs.

DRBDReplicationPolicy

A DRBDReplicationPolicy defines how volumes replicate between clusters in a DRBD Operator deployment. Its spec encodes the storage class mappings between primary and DR (so that volumes are provisioned using the correct storage class on each side), the replication endpoints, and whether to use Protocol C or Protocol A. One policy typically covers all VMs in a deployment namespace, though you can create multiple policies for different storage tiers. Key spec fields include clusters, drbdProtocol, replicationMode, diskConfig, networkConfig, and rpo.

DRBDResource

A DRBDResource represents all the disks of a single VM as one replicated DRBD resource. The protection controller creates one DRBDResource CR per VM per cluster side automatically when processing a ProtectionRequest. Its status reports per-volume sync progress and DRBD connection state, making it the primary object to inspect when diagnosing replication health for a specific VM. Key spec fields include role, side, volumes (required), port (required), replicationIntent, endpoints, and paused.

ProtectionRequest

A ProtectionRequest (shortnames: pr, protect) requests block-level replication protection for a single VM in a DRBD Operator deployment. When you create a ProtectionRequest, the protection controller validates the VM, creates the DRBDResource pair covering all VM disks, and switches the VM to DRBD-backed frontend PVCs. The CR tracks progress through phases from Pending through to Protected. Required spec fields are sourceCluster and virtualMachine.

ProtectionGroup

A ProtectionGroup (shortname: pg) groups multiple VMs so they fail over together as a coordinated unit. Its status shows whether replication for the group is Syncing, Consistent, or Degraded. Required spec field: virtualMachines (array). Optional fields include desiredState, sourceCluster, sla, and resourceGroupName.

Failover operations

FailoverRequest

A FailoverRequest (shortname: fr) triggers either a planned or unplanned failover for a Protection Group. Creating this CR on the quorum cluster causes the failover controller to stop VMs on the source cluster, promote DRBD volumes on the target cluster, and start VMs there. The CR tracks operation progress from Pending through InProgress to Completed or Failed. Required spec fields are protectionGroupRef and targetCluster. Optional fields include failoverType, drainTimeoutSeconds, and batchBootTimeoutSeconds.

Planned failover

A planned failover (also called a graceful failover) is a controlled failover where VMs on the primary cluster are gracefully shut down before DRBD volumes are promoted on the DR cluster. Because all writes are flushed before promotion, planned failovers result in zero data loss and an orderly transition. Use this when you are performing scheduled maintenance or a controlled site migration.

Unplanned failover

An unplanned failover (also called an emergency or disaster failover) is triggered when the primary cluster is unavailable. DRBD volumes are force-promoted on the DR cluster without waiting for the primary to shut down gracefully. If Protocol A was in use, there may be minimal data loss corresponding to the replication lag at the time of the disaster. Use this when the primary site has failed and cannot be contacted.

Failback

Failback (also called reverse failover) is the operation that returns VM workloads from the DR cluster back to the primary cluster after the primary has been restored. Failback re-establishes the original active/standby topology, with VMs running on the primary cluster and DRBD replicating to the DR cluster. It is executed using the same FailoverRequest mechanism, with the roles of source and target reversed.

DR validation

TestFailover

A TestFailover (shortnames: tf; also called a non-disruptive DR test) validates DR readiness without impacting production workloads. The test-failover-controller creates volume snapshots of the protected VMs, provisions test PVCs from those snapshots, starts test VMs in an isolated namespace on the DR cluster, runs verification checks, and then cleans up. The CR tracks progress through phases: CreatingSnapshots → CreatingVolumes → CreatingVMs → VerifyingData → Succeeded (or Failed) → CleaningUp → Cleaned. Required spec field: protectionGroupRef. Optional fields include cleanupPolicy, retentionTime, timeout, batchBootTimeoutSeconds, and verification.

Replication health monitoring

ReplicationGroupStatus

A ReplicationGroupStatus aggregates replication health for a Protection Group into a single view: Healthy, Degraded, or Critical. It also surfaces per-volume sync state and the timestamp of the last successful synchronization. Required spec field: protectionGroupRef. Optional fields include pollingIntervalSeconds, rpoObjectiveSeconds, and replicationProtocol. Query this CR first when you need a quick health check across all volumes in a group.

RPOEvent

An RPOEvent records a replication lag violation for a Protection Group, capturing the observed lag in seconds, a severity level (warning or critical), and supporting context such as affected volumes, connection details, and violation reason. RPO events provide an audit trail for compliance reporting and can be used to trigger alerts. Required spec fields are eventType, protectionGroupRef, and timestamp. Optional fields include affectedVolumes, rpoAtEvent, violationReason, connectionDetails, outOfSyncBytesAtEvent, recoveryEstimate, and status transition fields.

Tooling

tsr-gather

tsr-gather (also called must-gather or support bundle) is an oc adm must-gather-compatible diagnostic tool. Run it against the quorum cluster and it collects logs, CRD state, and configuration from the quorum cluster and all associated workload clusters (primary and DR) into a single diagnostic bundle. It never captures secrets, kubeconfigs, cloud-init payloads, or DRBD shared secrets. Use tsr-gather as the first step when opening a support case or diagnosing a degraded replication link.

Inspect replication health for a Protection Group

Query the ReplicationGroupStatus CR for a Protection Group named pg-webapp in the dr-prod namespace on the quorum cluster.

kubectl --kubeconfig $KUBECONFIG_QUORUM \
  get replicationgroupstatus pg-webapp -n dr-prod -o yaml

Expected output (abbreviated):

apiVersion: siterecovery.trilio.io/v1alpha1
kind: ReplicationGroupStatus
metadata:
  name: pg-webapp
  namespace: dr-prod
spec:
  protectionGroupRef:
    name: pg-webapp
  pollingIntervalSeconds: 30
  rpoObjectiveSeconds: 0
  replicationProtocol: C
status:
  health: Healthy
  lastSyncTimestamp: "2025-11-01T14:22:05Z"
  volumes:
    - name: vm-web-os-disk
      syncState: UpToDate
    - name: vm-db-data-disk
      syncState: UpToDate

Check RPO violations for a Protection Group

List all RPOEvent records in the dr-prod namespace to review replication lag violations.

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

Expected output:

NAME                        PROTECTION-GROUP   EVENT-TYPE   SEVERITY   AGE
pg-webapp-rpo-2025110114   pg-webapp          RpoViolation   warning    3h

Describe the event for full context:

kubectl --kubeconfig $KUBECONFIG_QUORUM \
  describe rpoevent pg-webapp-rpo-2025110114 -n dr-prod

Collect a diagnostic bundle with tsr-gather

Run tsr-gather against the quorum cluster to collect a complete support bundle covering all clusters in the DR estate.

oc adm must-gather \
  --image=$DOCKER_REGISTRY/site-recovery-must-gather:<tag>

To limit the log window to the last two hours:

oc adm must-gather \
  --image=$DOCKER_REGISTRY/site-recovery-must-gather:<tag> \
  -- /usr/bin/gather --since 2h

The bundle is written to ./must-gather.local.<timestamp>/. Open SUMMARY.md first for a high-level diagnosis, then manifest.yaml to see exactly what was collected.

Watch a FailoverRequest progress through phases

kubectl --kubeconfig $KUBECONFIG_QUORUM \
  get failoverrequest pg-webapp-failover -n dr-prod -w

Expected output:

NAME                    STATUS      AGE
pg-webapp-failover      Pending     0s
pg-webapp-failover      InProgress  4s
pg-webapp-failover      Completed   4m12s

• Plan and verify infrastructure — Understand the network and storage prerequisites before deploying Site Recovery components.
• Deploy the workload control plane — Install the site-recovery-workload-control-plane Helm chart on your primary and DR clusters.
• Deploy the quorum control plane — Install the site-recovery-protectionzone-controller and site-recovery-quorum-control-plane Helm charts on the quorum cluster.
• Configure cross-cluster replication (DRBD Operator model) — Create the DRBDReplicationPolicy that maps storage classes and defines Protocol C or Protocol A replication between clusters.
• Protect virtual machines — Submit ProtectionRequest CRs and verify that DRBDResource pairs are created and synchronizing.
• Verify replication health — Use ReplicationGroupStatus and RPOEvent CRs to confirm that replication is Healthy and within your RPO objective.
• Run a test failover — Create a TestFailover CR to validate DR readiness non-disruptively.
• Execute a planned failover — Create a FailoverRequest with failoverType: planned for a controlled transition.
• Execute an unplanned failover — Create a FailoverRequest with failoverType: unplanned when the primary site is unavailable.
• Perform failback — Reverse the failover after the primary cluster is restored.
• Diagnose a degraded or failed node or replication link — Use tsr-gather and DRBDResource status to isolate and resolve replication faults.