enhance drpolicy-crd doc

Signed-off-by: rakeshgm <rakeshgm@redhat.com>

Author: rakeshgm

docs/drpolicy-crd.md

@@ -15,13 +15,12 @@ the DR relationship between two managed clusters.
 A DRPolicy specifies:
 
 - Which two clusters participate in DR
-- The replication schedule (for async DR)
+- The replication schedule for Async (Regional DR)
 - Storage class selectors for volume replication
-- Whether to use async (VolumeReplication) or sync (VolSync) replication
+- Whether to use async (Regional DR) or sync (Metro DR)
 
 **Lifecycle:** DRPolicy resources are created once during DR setup and are
-typically long-lived. Multiple DRPlacementControl resources can reference
-the same DRPolicy.
+typically long-lived.
 
 ## API Group and Version
 
@@ -36,12 +35,12 @@ the same DRPolicy.
 
 #### `drClusters` ([]string)
 
-List of exactly two managed cluster names that participate in this DR policy.
+List of exactly two DRCluster resource names that participate in this DR policy.
 
 **Requirements:**
 
-- Must contain exactly 2 cluster names
-- Cluster names must match OCM ManagedCluster resource names
+- Must contain exactly 2 DRCluster resource names
+- DRCluster resources must exist on the hub cluster (see [DRCluster](drcluster-crd.md))
 - Immutable after creation
 
 **Example:**
@@ -57,7 +56,7 @@ drClusters:
 #### `schedulingInterval` (string)
 
 Defines how frequently to replicate volume data between clusters for
-async replication.
+Async (Regional DR).
 
 **Format:** `<number><m|h|d>` where:
 
@@ -67,8 +66,8 @@ async replication.
 
 **Behavior:**
 
-- Empty string (`""`) = synchronous replication (Metro DR / VolSync)
-- Non-empty = asynchronous replication (Regional DR / VolumeReplication)
+- Empty string (`""`) = Sync (Metro DR)
+- Non-empty = Async (Regional DR)
 - Immutable after creation
 
 **Examples:**
@@ -82,16 +81,16 @@ schedulingInterval: ""     # Synchronous (no scheduling)
 
 **Typical values:**
 
-- Production async: `"1h"` or `"30m"`
+- Production Async (Regional DR): `"1h"` or `"30m"`
 - Testing: `"5m"` or `"10m"`
-- Sync DR: `""` (empty)
+- Sync (Metro DR): `""` (empty)
 
 #### `replicationClassSelector` (metav1.LabelSelector)
 
 Label selector to identify VolumeReplicationClass resources for
-async replication.
+Async (Regional DR).
 
-**When to use:** Set this for async (Regional DR) when using
+**When to use:** Set this for Async (Regional DR) when using
 VolumeReplication with schedulingInterval.
 
 **How it works:**
@@ -112,11 +111,11 @@ replicationClassSelector:
 
 #### `volumeSnapshotClassSelector` (metav1.LabelSelector)
 
-Label selector to identify VolumeSnapshotClass resources for sync
-replication.
+Label selector to identify VolumeSnapshotClass resources for
+Async (Regional DR).
 
-**When to use:** Set this for sync (Metro DR) when using VolSync
-without schedulingInterval.
+**When to use:** Set this for Async (Regional DR) when using VolSync
+with schedulingInterval.
 
 **How it works:**
 
@@ -137,9 +136,9 @@ volumeSnapshotClassSelector:
 #### `volumeGroupSnapshotClassSelector` (metav1.LabelSelector)
 
 Label selector to identify VolumeGroupSnapshotClass resources for grouped
-snapshot operations with VolSync.
+snapshot operations with VolSync in Async (Regional DR).
 
-**When to use:** For workloads with multiple PVCs that need
+**When to use:** For Async (Regional DR) workloads with multiple PVCs that need
 consistent point-in-time snapshots.
 
 **Example:**
@@ -164,23 +163,23 @@ Standard Kubernetes conditions indicating the policy validation state.
 
 ### `async` (Async)
 
-Status of async replication details between clusters (for Regional DR).
+Status of async (Regional DR) details between clusters.
 
 **Fields:**
 
 - `peerClasses` ([]PeerClass) - List of common StorageClasses with async relationships
 
 ### `sync` (Sync)
 
-Status of sync replication details between clusters (for Metro DR).
+Status of sync (Metro DR) details between clusters.
 
 **Fields:**
 
 - `peerClasses` ([]PeerClass) - List of common StorageClasses with sync relationships
 
 ### PeerClass Structure
 
-Discovered storage class relationships between peer clusters:
+Discovered peer relationship information between peer clusters:
 
 - `storageClassName` - Common StorageClass name across peers
 - `replicationID` - Common replication ID from VolumeReplicationClass labels
@@ -192,10 +191,10 @@ Discovered storage class relationships between peer clusters:
 
 ## Examples
 
-### Example 1: Async Regional DR Policy
+### Example 1: Async (Regional DR)
 
-For asynchronous replication between geographically distributed
-clusters using Ceph RBD mirroring:
+This policy configures Async (Regional DR) between geographically distributed
+clusters:
 
 ```yaml
 apiVersion: ramendr.openshift.io/v1alpha1
@@ -211,15 +210,15 @@ spec:
     - us-east-cluster
     - us-west-cluster
 
-  # Select VolumeReplicationClass for Ceph RBD
+  # Select VolumeReplicationClass
   replicationClassSelector:
     matchLabels:
       ramendr.openshift.io/replication-class: rbd-replication
 ```
 
-### Example 2: Sync Metro DR Policy
+### Example 2: Sync (Metro DR)
 
-For synchronous replication between clusters in the same metro area using VolSync:
+This policy configures Sync (Metro DR) between clusters in the same metro area:
 
 ```yaml
 apiVersion: ramendr.openshift.io/v1alpha1
@@ -234,75 +233,38 @@ spec:
   drClusters:
     - metro-cluster-1
     - metro-cluster-2
-
-  # Select VolumeSnapshotClass for VolSync
-  volumeSnapshotClassSelector:
-    matchLabels:
-      ramendr.openshift.io/snapshot-class: csi-snapclass
 ```
 
-### Example 3: Multi-Policy Setup
-
-You can have multiple DRPolicies for different cluster pairs:
+**Note:** Sync (Metro DR) uses synchronous replication at the storage level.
+VolSync is used for Async (Regional DR) and should not be used with
+Sync (Metro DR).
 
-```yaml
-# Policy for US East <-> US West
-apiVersion: ramendr.openshift.io/v1alpha1
-kind: DRPolicy
-metadata:
-  name: us-regional-dr
-spec:
-  schedulingInterval: "1h"
-  drClusters:
-    - us-east
-    - us-west
-  replicationClassSelector:
-    matchLabels:
-      class: rbd-replication
----
-# Policy for EU clusters
-apiVersion: ramendr.openshift.io/v1alpha1
-kind: DRPolicy
-metadata:
-  name: eu-regional-dr
-spec:
-  schedulingInterval: "1h"
-  drClusters:
-    - eu-north
-    - eu-south
-  replicationClassSelector:
-    matchLabels:
-      class: rbd-replication
-```
+## Troubleshooting
 
-## Usage
+### DRPolicy Not Validated
 
-### Creating a DRPolicy
+Check the DRPolicy status:
 
-**Prerequisites:**
+```bash
+kubectl get drpolicy <name> -o yaml
+```
 
-1. Two managed clusters registered with OCM hub
-1. Storage with replication support on both clusters
-1. VolumeReplicationClass (async) or VolumeSnapshotClass (sync) configured
+**Common issues:**
 
-**Steps:**
+1. Clusters not registered in OCM
 
-1. Verify managed clusters are ready:
+   Verify managed clusters are registered:
 
    ```bash
    kubectl get managedclusters
    ```
 
-1. Create the DRPolicy:
-
-   ```bash
-   kubectl apply -f drpolicy.yaml
-   ```
+1. DRCluster resources not validated
 
-1. Verify the policy is validated:
+   Verify DRCluster resources referenced in the DRPolicy are validated:
 
    ```bash
-   kubectl get drpolicy regional-dr-policy -o yaml
+   kubectl get drcluster <cluster-name> -o yaml
    ```
 
    Check for `Validated` condition in status:
@@ -314,125 +276,12 @@ spec:
          status: "True"
    ```
 
-1. Check discovered peer classes:
-
-   ```bash
-   kubectl get drpolicy regional-dr-policy -o jsonpath='{.status.async.peerClasses}' | jq
-   ```
-
-### Referencing a DRPolicy
-
-DRPlacementControl resources reference DRPolicy by name:
-
-```yaml
-apiVersion: ramendr.openshift.io/v1alpha1
-kind: DRPlacementControl
-metadata:
-  name: my-app-drpc
-  namespace: my-app
-spec:
-  drPolicyRef:
-    name: regional-dr-policy # References the DRPolicy
-  # ... other DRPC fields
-```
-
-## Validation Rules
-
-The DRPolicy has built-in validation:
-
-1. **drClusters must contain exactly 2 clusters**
-
-    - Error: "drClusters requires a list of 2 clusters"
-
-1. **Fields are immutable after creation:**
-
-    - `drClusters` - Cannot change cluster list
-    - `schedulingInterval` - Cannot switch between sync/async
-    - `replicationClassSelector` - Presence cannot change
-    - `volumeSnapshotClassSelector` - Presence cannot change
-
-1. **schedulingInterval format validation:**
-    - Must match pattern: `^\d+[mhd]$` or empty string
-    - Examples: `5m`, `1h`, `2d`, or `""`
-
-## Troubleshooting
-
-### DRPolicy Not Validated
-
-**Check:**
-
-```bash
-kubectl get drpolicy <name> -o yaml
-```
-
-**Common issues:**
-
-1. Clusters not registered in OCM
-
-   ```bash
-   kubectl get managedclusters
-   ```
-
-1. VolumeReplicationClass or VolumeSnapshotClass not found
-
-   ```bash
-   # On each managed cluster
-   kubectl get volumereplicationclass
-   kubectl get volumesnapshotclass
-   ```
-
-1. Storage classes not properly labeled
-
-   ```bash
-   kubectl get sc -o yaml | grep "ramendr.openshift.io"
-   ```
-
 ### No PeerClasses in Status
 
-**Cause:** Storage classes may not have required labels or replication isn't configured.
-
-**Check storage class labels on managed clusters:**
-
-```bash
-kubectl get sc <storage-class-name> -o yaml
-```
-
-**Required labels:**
-
-- `ramendr.openshift.io/storageid` - Storage backend identifier
-- `ramendr.openshift.io/replicationid` - Replication backend identifier (on VolumeReplicationClass)
-
-### Cannot Delete DRPolicy
-
-**Cause:** DRPlacementControl resources are still referencing it.
-
-**Check references:**
-
-```bash
-kubectl get drpc -A -o yaml | grep drPolicyRef
-```
-
-**Solution:** Delete all referencing DRPCs first, then delete the DRPolicy.
-
-## Best Practices
-
-1. **Use descriptive names** - Include location or purpose in the
-    name (e.g., `us-regional-dr`, `metro-dr-policy`)
-
-1. **Set appropriate scheduling intervals:**
-
-    - Production: 30m to 1h for most workloads
-    - High-frequency: 5m to 15m for critical workloads
-    - Low-frequency: 6h to 24h for large datasets
-
-1. **Label storage classes consistently** across clusters for peer class discovery
-
-1. **Create separate policies** for different DR requirements
-    (e.g., one for US clusters, one for EU clusters)
-
-1. **Test policies** with non-production workloads before using in production
+**Cause:** Classes available on managed clusters may not have required labels
+or annotations, or replication isn't configured.
 
-1. **Monitor policy status** regularly to ensure validation remains successful
+**For details on required labels and annotations, see [DRClusterConfig](drclusterconfig-crd.md).**
 
 ## Related Resources