---
title: Key Concepts
product: trilio-site-recovery-for-kubernetes
doc_type: concept
version: 0.2.0
source: git2docs (code-derived, validation-filtered)
canonical: https://docs-tsr.trilio.io/trilio-site-recovery-for-kubernetes/site-recovery/key-concepts
---

# Key Concepts

_Kubernetes concepts and site-recovery-specific terminology such as recovery plans, failover, and failback_

## Overview

This page defines every term you will encounter when reading Site Recovery documentation, creating custom resources, or diagnosing a failing operation. Understanding these concepts — particularly how the TSR-Manager cluster relates to workload clusters, how DRBD replication is configured, and how failover operations are declared — is prerequisite reading before you follow any procedural guide. Each term maps to a concrete Kubernetes object, controller behavior, or infrastructure component.

## Examples

### Minimal ProtectionZone manifest

The following manifest creates a ProtectionZone pairing two OpenShift clusters in the `DRBD` backend mode. The kubeconfig Secrets (`cluster1-kubeconfig` and `cluster2-kubeconfig`) must already exist in the `dr-prod` namespace on the TSR-Manager cluster before or immediately after the zone is created.

```yaml
apiVersion: siterecovery.trilio.io/v1alpha1
kind: ProtectionZone
metadata:
  name: prod
  namespace: dr-prod
spec:
  displayName: Production DR Zone
  storageBackendMode: DRBD
  clusters:
    - name: cluster1
      clusterID: cluster1
      kubeconfigSecretRef:
        name: cluster1-kubeconfig
        key: kubeconfig
      distributionName: RHEL-CoreOS-9
    - name: cluster2
      clusterID: cluster2
      kubeconfigSecretRef:
        name: cluster2-kubeconfig
        key: kubeconfig
      distributionName: RHEL-CoreOS-9
```

### Protecting a VirtualMachine

A ProtectionRequest declares that a single KubeVirt VM running in the `vm-apps` namespace on `cluster1` should be protected. The `sourceCluster` field identifies which deployment slot currently runs the VM.

```yaml
apiVersion: siterecovery.trilio.io/v1alpha1
kind: ProtectionRequest
metadata:
  name: protect-web-server
  namespace: dr-prod
spec:
  sourceCluster: cluster1
  virtualMachine:
    name: web-server
    namespace: vm-apps
  replicationConfig:
    replicationProtocol: C
    rpo: 0
```

### Grouping VMs for coordinated failover

A ProtectionGroup groups multiple VMs for failover as a unit, with boot ordering defined per VM.

```yaml
apiVersion: siterecovery.trilio.io/v1alpha1
kind: ProtectionGroup
metadata:
  name: web-tier
  namespace: dr-prod
spec:
  desiredState: running
  virtualMachines:
    - name: web-server
      namespace: vm-apps
      bootOrder: 2
    - name: database
      namespace: vm-apps
      bootOrder: 1
  sla:
    rpoTargetSeconds: 0
    rtoTargetSeconds: 300
```

### Triggering a planned failover

A FailoverRequest moves all VMs in a ProtectionGroup from `cluster1` to `cluster2` using a graceful, planned failover.

```yaml
apiVersion: siterecovery.trilio.io/v1alpha1
kind: FailoverRequest
metadata:
  name: web-tier-failover
  namespace: dr-prod
spec:
  protectionGroupRef:
    name: web-tier
    namespace: dr-prod
  targetCluster: cluster2
  failoverType: planned
  skipHooks: false
```

### Running a test failover

A TestFailover validates DR readiness without disrupting production VMs. The test namespace and target cluster are chosen automatically by the controller.

```yaml
apiVersion: siterecovery.trilio.io/v1alpha1
kind: TestFailover
metadata:
  name: web-tier-drill
  namespace: dr-prod
spec:
  protectionGroupRef:
    name: web-tier
    namespace: dr-prod
  cleanupPolicy: Automatic
  retentionTime: 2h
  schedulingCheck: Fail
```

### Checking replication health

Query the auto-created ReplicationGroupStatus for a ProtectionGroup. Use the short name `rgs`.

```bash
kubectl get rgs web-tier-replication -n dr-prod -o yaml
```

### Listing RPO events for a ProtectionGroup

```bash
kubectl get rpoe -n dr-prod -l siterecovery.trilio.io/protection-group=web-tier
```

### Inspecting a DRBDResource on a workload cluster

DRBDResource CRs live on workload clusters, not the TSR-Manager cluster. Use the short name `dres`.

```bash
kubectl get dres -n vm-apps --context workload-cluster1
```

### Checking protected VMs with the label selector

The label `siterecovery.trilio.io/protected-vm=true` is stamped on KubeVirt VirtualMachine objects on workload clusters.

```bash
kubectl get vm -A -l siterecovery.trilio.io/protected-vm=true --context workload-cluster1
```

### Adjusting runtime log levels without a restart

Patch the `site-recovery-logging` ConfigMap in the zone namespace to enable debug logging for the control plane:

```bash
kubectl patch configmap site-recovery-logging -n dr-prod \
  --type merge \
  -p '{"data":{"level":"info","level.control-plane":"debug"}}'
```

## Related concepts

- **Install and configure the control plane** — how the ProtectionZone controller and TSR-Manager control plane are deployed via OLM and how the ProtectionZone CR drives automated stack installation
- **Provision zone credentials** — how `tsrctl zone-credential` mints and rotates the kubeconfig Secrets that allow the TSR-Manager to reach workload clusters
- **Create a ProtectionZone** — step-by-step guide to creating the ProtectionZone CR and verifying the `ClustersValidated` condition
- **Protect a virtual machine** — how to create a ProtectionRequest and monitor the VM through to the Protected phase
- **Monitor replication health** — how to read ReplicationGroupStatus and RPOEvent objects for SLA reporting
- **Run a test failover** — how to create a TestFailover CR and interpret the scheduling check and verification results
- **Execute a planned failover** — how to create a FailoverRequest and confirm the role flip on both clusters
- **Execute an unplanned failover** — how unplanned failover differs from planned and when to use it
- **Fail back to the original cluster** — how to return VMs to the original cluster after a failover by reversing the FailoverRequest direction
- **Rotate zone credentials** — how to use `tsrctl zone-credential rotate` to renew expiring kubeconfig Secrets
- **Collect a support bundle** — how to run `oc adm must-gather` with the `site-recovery-must-gather` image to collect a diagnostic archive
- **Diagnose a degraded node or stalled protection** — how to interpret DRBDResource conditions, node agent taints, and ProtectionRequest phases during troubleshooting