---
title: Kubectl Commands
product: trilio-site-recovery-for-kubernetes-openshift-virtualization
doc_type: cli_reference
version: feature-tsr-24
source: git2docs (code-derived, validation-filtered)
canonical: https://git2docs.com/murali-balcha/docs/trilio-site-recovery-for-kubernetes-openshift-virtualization/site-recovery/cli-reference
---

# Kubectl Commands

_Common kubectl commands for inspecting, triggering, and managing site recovery resources_

## Description

Use `kubectl` to inspect, create, update, and delete Site Recovery custom resources directly on your primary, DR, or quorum clusters. Because Site Recovery implements the Kubernetes operator pattern, `kubectl` is the authoritative interface for declaring protection intent and observing operator-driven reconciliation — every resource you create or patch triggers a controller response without requiring any additional tooling.

## Synopsis

`kubectl [--kubeconfig <path>] [--context <context>] <verb> <resource> [name] [-n <namespace>] [flags]`

All Site Recovery custom resources live under the API group `siterecovery.trilio.io`. The examples on this page use explicit `--kubeconfig` flags to make cluster targeting clear; substitute your own kubeconfig paths or contexts as appropriate.

## Flags

The flags below are standard `kubectl` flags that are particularly relevant when working across the three clusters that make up a Site Recovery deployment.

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--kubeconfig` | | `~/.kube/config` | Path to the kubeconfig file. Specify different files to target the quorum, primary, or DR cluster. |
| `--context` | | Current context | Override the active kubeconfig context without switching files. |
| `-n`, `--namespace` | `-n` | `default` | Namespace in which the resource lives. DR deployments use the `dr-<name>` namespace on the quorum cluster. |
| `-o`, `--output` | `-o` | (table) | Output format. Use `yaml` to see full resource specs, `json` for piping to `jq`, or `jsonpath` for targeted field extraction. |
| `--watch` | `-w` | `false` | Stream resource updates. Useful for monitoring failover or protection progress in real time. |
| `--for` | | | Used with `kubectl wait` to block until a specific condition is met, such as a field reaching a target value. |
| `--timeout` | | `30s` | Maximum time to wait when used with `kubectl wait`. |
| `--type` | | `strategic` | Patch strategy for `kubectl patch`. Use `merge` for simple field updates on Site Recovery resources. |
| `-p` | | | Inline patch body for `kubectl patch`. |
| `-f` | | | Path to a manifest file or `-` for stdin, used with `apply`, `create`, and `delete`. |
| `-l`, `--selector` | `-l` | | Label selector for filtering resource lists. |
| `--all-namespaces` | `-A` | `false` | List resources across all namespaces. Useful when auditing protection state cluster-wide. |

## Subcommands

The table below maps common `kubectl` verbs to their Site Recovery use cases.

| Verb | Description |
|------|-------------|
| `get` | List or describe Site Recovery resources. Add `-o yaml` for full spec and status. |
| `apply` | Create or update a resource from a manifest file. The preferred way to declare ProtectionGroups, ProtectionRequests, FailoverRequests, TestFailovers, and DRBDReplicationPolicies. |
| `patch` | Modify a specific field of an existing resource. Use `--type merge` when updating fields such as `spec.virtualMachines` or `spec.desiredState`. |
| `delete` | Remove a Site Recovery resource. Deleting a FailoverRequest or TestFailover after completion is safe; deleting a ProtectionGroup or ProtectionRequest removes protection intent and may trigger controller cleanup. |
| `describe` | Show events and a human-readable summary for a resource. The Events section reveals controller reconciliation activity and error messages. |
| `wait` | Block until a resource reaches a target condition. Use this in scripts to synchronize between steps, for example waiting for a FailoverRequest to complete. |
| `logs` | Stream controller logs. Target controller pods by label to observe reconciliation decisions. |
| `rollout restart` | Restart a controller deployment. Use this after updating CRDs or credentials to force controllers to reload. |

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `KUBECONFIG` | `~/.kube/config` | Colon-separated list of kubeconfig files. Set this to load multiple cluster configs simultaneously and reference them by context name. |
| `KUBECTL_EXTERNAL_DIFF` | | Path to a diff tool used by `kubectl diff`. Useful for previewing manifest changes before applying them to protection resources. |

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | Command succeeded. The resource was found, applied, patched, or deleted as requested. |
| `1` | General error. Includes authentication failures, API server unreachable, or invalid manifest syntax. Check `stderr` for the error message. |
| `1` | Resource not found when using `get`, `describe`, or `delete` with a specific name. |
| `1` | Timeout expired when using `kubectl wait --timeout`. The resource did not reach the expected condition within the allowed time. |

## Examples

The examples below are organized by workflow stage. Each example shows the command, the cluster it targets, and representative output. Replace `<name>`, `<namespace>`, and kubeconfig paths with values from your environment.

---

### List all Site Recovery custom resource types

Confirm that the Site Recovery CRDs are installed on the target cluster.

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  get crds | grep siterecovery.trilio.io
```

**Expected output:**
```
drbdreplicationpolicies.siterecovery.trilio.io    2025-01-15T10:00:00Z
drbdvolumes.siterecovery.trilio.io                2025-01-15T10:00:00Z
failoverrequests.siterecovery.trilio.io           2025-01-15T10:00:00Z
protectiongroups.siterecovery.trilio.io           2025-01-15T10:00:00Z
protectionrequests.siterecovery.trilio.io         2025-01-15T10:00:00Z
replicationgroupstatuses.siterecovery.trilio.io   2025-01-15T10:00:00Z
rpoevents.siterecovery.trilio.io                  2025-01-15T10:00:00Z
testfailovers.siterecovery.trilio.io              2025-01-15T10:00:00Z
```

---

### Create a ProtectionGroup

A ProtectionGroup declares which VMs should fail over together as a unit on your primary cluster. Apply the manifest from the primary cluster context.

```bash
kubectl --kubeconfig ~/.kube/config-primary apply -f - <<EOF
apiVersion: siterecovery.trilio.io/v1alpha1
kind: ProtectionGroup
metadata:
  name: production-pg
  namespace: default
spec:
  desiredState: running
  virtualMachines:
    - name: prod-vm-1
    - name: prod-vm-2
EOF
```

**Expected output:**
```
protectiongroup.siterecovery.trilio.io/production-pg created
```

---

### Inspect ProtectionGroup status

After the protection-group-controller reconciles, check the aggregated replication state. Run this on whichever cluster hosts the ProtectionGroup resource.

```bash
kubectl --kubeconfig ~/.kube/config-primary \
  get protectiongroup production-pg -n default
```

**Expected output:**
```
NAME             STATE    VMS   REPLICATION   HEALTH    AGE
production-pg    Active   2     synchronous   Healthy   5m
```

For the full spec and status including per-VM replication state:

```bash
kubectl --kubeconfig ~/.kube/config-primary \
  get protectiongroup production-pg -n default -o yaml
```

**Expected output (abbreviated):**
```yaml
apiVersion: siterecovery.trilio.io/v1alpha1
kind: ProtectionGroup
metadata:
  name: production-pg
  namespace: default
status:
  state: Active
  replicationHealth: Healthy
  currentState: running
  protectedVMs:
    - name: prod-vm-1
      namespace: default
      replicationStatus: Protected
    - name: prod-vm-2
      namespace: default
      replicationStatus: Protected
```

---

### Add a VM to an existing ProtectionGroup

Use a merge patch to append a VM to the `spec.virtualMachines` list. You must supply the full list because the merge patch replaces the array.

```bash
kubectl --kubeconfig ~/.kube/config-primary \
  patch protectiongroup production-pg -n default \
  --type merge \
  -p '{
    "spec": {
      "virtualMachines": [
        {"name": "prod-vm-1"},
        {"name": "prod-vm-2"},
        {"name": "prod-vm-3"}
      ]
    }
  }'
```

**Expected output:**
```
protectiongroup.siterecovery.trilio.io/production-pg patched
```

Verify the update was accepted:

```bash
kubectl --kubeconfig ~/.kube/config-primary \
  get protectiongroup production-pg -n default \
  -o jsonpath='{.spec.virtualMachines}' | jq .
```

**Expected output:**
```json
[
  {"name": "prod-vm-1"},
  {"name": "prod-vm-2"},
  {"name": "prod-vm-3"}
]
```

---

### Create a ProtectionRequest (DRBD Operator deployments)

In the DRBD Operator deployment model, request protection for a single VM. The protection-controller on the quorum cluster validates the VM, creates DRBDVolume resources, and switches the VM to a DRBD-backed frontend PVC.

```bash
kubectl --kubeconfig ~/.kube/config-quorum apply -f - <<EOF
apiVersion: siterecovery.trilio.io/v1alpha1
kind: ProtectionRequest
metadata:
  name: protect-web-vm-1
  namespace: dr-production
spec:
  virtualMachine:
    name: web-vm-1
    namespace: default
  replicationPolicy: drbd-sync-policy
EOF
```

**Expected output:**
```
protectionrequest.siterecovery.trilio.io/protect-web-vm-1 created
```

Watch the lifecycle progress:

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  get protectionrequest protect-web-vm-1 -n dr-production -w
```

**Expected output:**
```
NAME               STATUS       AGE
protect-web-vm-1   Validating   5s
protect-web-vm-1   Protecting   18s
protect-web-vm-1   Protected    2m10s
```

---

### Inspect a DRBDVolume

After a ProtectionRequest is processed, the controller creates DRBDVolume resources. Check sync progress on the primary cluster.

```bash
kubectl --kubeconfig ~/.kube/config-primary \
  get drbdvolumes -n default
```

**Expected output:**
```
NAME                                      SYNC    FRONTEND-PVC            AGE
pvc-a1b2c3d4-e5f6-7890-abcd-ef1234567890  100%    web-vm-1-frontend-pvc   8m
```

For detailed sync state and frontend PVC reference:

```bash
kubectl --kubeconfig ~/.kube/config-primary \
  get drbdvolume pvc-a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -n default -o yaml
```

---

### Inspect a DRBDReplicationPolicy

A DRBDReplicationPolicy defines how volumes replicate between clusters. Inspect its storage class mappings and protocol selection.

```bash
kubectl --kubeconfig ~/.kube/config-primary \
  get drbdreplicationpolicy drbd-sync-policy -n default -o yaml
```

**Expected output (abbreviated):**
```yaml
apiVersion: siterecovery.trilio.io/v1alpha1
kind: DRBDReplicationPolicy
metadata:
  name: drbd-sync-policy
  namespace: default
spec:
  protocol: C
  storageClassMappings:
    - primary: fast-ssd
      dr: fast-ssd-dr
  replicationEndpoints:
    primary: 192.168.10.10:7000
    dr: 192.168.20.10:7000
```

---

### Check replication health with ReplicationGroupStatus

The replication-monitor writes ReplicationGroupStatus resources that provide an aggregated health view. Check this on the quorum cluster for operator-level visibility.

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  get replicationgroupstatus -n dr-production
```

**Expected output:**
```
NAME             HEALTH    LAST-SYNC              AGE
production-pg    Healthy   2025-01-15T14:23:00Z   2d
```

For per-volume sync state:

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  describe replicationgroupstatus production-pg -n dr-production
```

---

### List RPOEvents to audit replication lag violations

RPOEvent resources are written by the replication-monitor when lag thresholds are exceeded. Review them to audit data loss risk.

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  get rpoevents -n dr-production
```

**Expected output:**
```
NAME                        PROTECTION-GROUP   LAG       SEVERITY   AGE
rpoevent-20250115-142300    production-pg      45s       Warning    2h
rpoevent-20250114-091500    production-pg      120s      Critical   1d
```

Inspect a specific event for full context:

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  get rpoevent rpoevent-20250115-142300 -n dr-production -o yaml
```

---

### Trigger a planned failover

A planned (graceful) failover stops VMs on the primary cluster before promoting volumes on the DR cluster, ensuring zero data loss. Apply a FailoverRequest to the quorum cluster; the failover-controller watches for it and orchestrates the sequence.

```bash
kubectl --kubeconfig ~/.kube/config-quorum apply -f - <<EOF
apiVersion: siterecovery.trilio.io/v1alpha1
kind: FailoverRequest
metadata:
  name: planned-failover-production
  namespace: dr-production
spec:
  protectionGroup: production-pg
  failoverType: planned
  targetCluster: dr-cluster
EOF
```

**Expected output:**
```
failoverrequest.siterecovery.trilio.io/planned-failover-production created
```

Monitor progress in real time:

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  get failoverrequest planned-failover-production \
  -n dr-production -w
```

**Expected output:**
```
NAME                          TYPE      PHASE               STATUS      AGE
planned-failover-production   planned   StoppingOnSource    InProgress  15s
planned-failover-production   planned   WaitingForDRBD      InProgress  45s
planned-failover-production   planned   StartingOnTarget    InProgress  1m10s
planned-failover-production   planned   Completed           Succeeded   3m42s
```

Wait for completion in a script:

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  wait failoverrequest planned-failover-production \
  -n dr-production \
  --for=jsonpath='{.status.state}'=Completed \
  --timeout=600s
```

---

### Trigger an unplanned failover

An unplanned (emergency) failover promotes DR volumes and starts VMs without waiting for a graceful shutdown on the primary cluster. Use this when the primary cluster is unavailable.

```bash
kubectl --kubeconfig ~/.kube/config-quorum apply -f - <<EOF
apiVersion: siterecovery.trilio.io/v1alpha1
kind: FailoverRequest
metadata:
  name: emergency-failover-production
  namespace: dr-production
spec:
  protectionGroup: production-pg
  failoverType: unplanned
  targetCluster: dr-cluster
EOF
```

**Expected output:**
```
failoverrequest.siterecovery.trilio.io/emergency-failover-production created
```

---

### Inspect a FailoverRequest after completion

After a failover completes, review the full status to confirm which phase each step reached and whether any errors were recorded.

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  describe failoverrequest planned-failover-production \
  -n dr-production
```

The Events section of the output shows the controller's step-by-step reconciliation decisions and any warnings encountered during the operation.

---

### Initiate a test failover (DRBD Operator deployments only)

A TestFailover performs a non-disruptive DR validation by snapshotting production volumes, booting test VMs on the DR cluster, running verification checks, and cleaning up — without affecting production workloads. Test failover is only supported in DRBD Operator deployment models.

```bash
kubectl --kubeconfig ~/.kube/config-primary apply -f - <<EOF
apiVersion: siterecovery.trilio.io/v1alpha1
kind: TestFailover
metadata:
  name: tf-production-pg-jan15
  namespace: default
spec:
  protectionGroup: production-pg
EOF
```

**Expected output:**
```
testfailover.siterecovery.trilio.io/tf-production-pg-jan15 created
```

Watch the test failover lifecycle:

```bash
kubectl --kubeconfig ~/.kube/config-primary \
  get testfailover tf-production-pg-jan15 -n default -w
```

**Expected output:**
```
NAME                       PHASE               STATUS      AGE
tf-production-pg-jan15     Snapshotting        InProgress  10s
tf-production-pg-jan15     ProvisioningTestVMs InProgress  40s
tf-production-pg-jan15     Verifying           InProgress  2m
tf-production-pg-jan15     CleaningUp          InProgress  4m
tf-production-pg-jan15     Completed           Succeeded   5m30s
```

---

### Watch controller logs during a failover

To observe what the failover-controller is doing during an active FailoverRequest, stream its logs from the quorum cluster. Controllers run in the `dr-<deployment-name>` namespace.

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  logs -n dr-production \
  -l app=failover-controller \
  --follow
```

For the protection-group-controller running on the primary cluster:

```bash
kubectl --kubeconfig ~/.kube/config-primary \
  logs -n default \
  -l app=protection-group-controller \
  --follow
```

---

### Watch controller logs for the test-failover-controller

The test-failover-controller runs on the primary and DR clusters. Stream its logs to observe snapshot creation and test VM provisioning.

```bash
kubectl --kubeconfig ~/.kube/config-dr \
  logs -n default \
  -l app=test-failover-controller \
  --follow
```

---

### List all Protection Groups across namespaces

When managing a multi-tenant quorum with multiple DR deployments, use `--all-namespaces` to audit protection state across every deployment namespace.

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  get protectiongroups --all-namespaces
```

**Expected output:**
```
NAMESSPACE        NAME              STATE    VMS   HEALTH    AGE
dr-production     production-pg     Active   3     Healthy   5d
dr-staging        staging-pg        Active   1     Healthy   2d
dr-analytics      analytics-pg      Active   2     Degraded  12h
```

---

### Describe a ProtectionGroup to view controller events

The Events section reveals why a ProtectionGroup entered a Degraded state and what the controller attempted.

```bash
kubectl --kubeconfig ~/.kube/config-primary \
  describe protectiongroup production-pg -n default
```

Look for lines beginning with `Warning` in the Events section to identify replication or validation errors.

---

### Delete a completed FailoverRequest

Completed FailoverRequest resources persist in the cluster as an audit record. Delete them when they are no longer needed.

```bash
kubectl --kubeconfig ~/.kube/config-quorum \
  delete failoverrequest planned-failover-production \
  -n dr-production
```

**Expected output:**
```
failoverrequest.siterecovery.trilio.io/planned-failover-production deleted
```

---

### Restart a controller after a credential or CRD update

If you update cluster credentials or apply CRD schema changes, restart the affected controller deployment so it reloads its configuration.

```bash
# Restart the failover-controller on the quorum cluster
kubectl --kubeconfig ~/.kube/config-quorum \
  rollout restart deployment/failover-controller \
  -n dr-production

# Confirm rollout completes
kubectl --kubeconfig ~/.kube/config-quorum \
  rollout status deployment/failover-controller \
  -n dr-production
```

**Expected output:**
```
deployment.apps/failover-controller successfully rolled out
```