Skip to content

Commit 57864b6

Browse files
Nikhil-LadhaNikhil-Ladha
committed
docs: update design doc to include VR/VGR status samples
add VR/VGR status,status.Condition samples for different states. Signed-off-by: Nikhil-Ladha <nikhilladha1999@gmail.com>
1 parent 20e5c30 commit 57864b6

2 files changed

Lines changed: 257 additions & 1 deletion

File tree

‎docs/design/volumegroupreplication.md‎

Lines changed: 129 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,135 @@ For reference, one can check the implementation of csi-addons controllers for th
6565
- [volumegroupreplication_controller](https://github.com/csi-addons/kubernetes-csi-addons/blob/main/internal/controller/replication.storage/volumegroupreplication_controller.go) - It manages the flow of VGR and necessary validations to keep the VGR as the source of truth for the user.
6666
- [volumegroupreplicationcontent_controller](https://github.com/csi-addons/kubernetes-csi-addons/blob/main/internal/controller/replication.storage/volumegroupreplicationcontent_controller.go) - It manages the group level operations for the VGR.
6767

68-
VGR has a Status field that is basically the same as that of VolumeReplication’s Status field and it can be utilized by the storage vendor to populate the current status of replication to the end user and report any errors as such at the CR level.
68+
VGR has a Status field that is basically the same as that of VolumeReplication's Status field and it can be utilized by the storage vendor to populate the current status of replication to the end user and report any errors as such at the CR level.
69+
70+
If [RamenDR](https://github.com/RamenDR/ramen) is the extension/manager being used to manage DR for the workloads then, the storage vendor needs to add the below set of `Status` and `status.Conditions` to the VGR for ramen to read the VGR status and perform failover/relocate on the workload properly.
71+
72+
### VolumeGroupReplication Status Examples
73+
74+
The following sections provide detailed examples of VolumeGroupReplication status for different replication states. Each status example includes the necessary conditions and state information that RamenDR uses to manage disaster recovery operations. The condition's `Reason`, `Status`, and `Type` and the `status.State` must match the patterns shown below for RamenDR to correctly identify and manage the replication state.
75+
76+
#### Primary Status
77+
78+
**Description:** The Primary status indicates that the volume group is actively serving I/O operations and is replicating data to a secondary cluster. This is the active state where the volume group is being written to by applications, and changes are being mirrored to the secondary site for disaster recovery purposes. The volume group is healthy and not in a degraded or resyncing state.
79+
80+
Sample `status` of VGR when the volume group is promoted to `Primary` successfully:
81+
82+
```yaml
83+
status:
84+
conditions:
85+
- message: volume group is promoted to primary and replicating to secondary
86+
reason: Promoted
87+
status: "True"
88+
type: Completed
89+
- message: volume group is healthy
90+
reason: Healthy
91+
status: "False"
92+
type: Degraded
93+
- message: volume group is not resyncing
94+
reason: NotResyncing
95+
status: "False"
96+
type: Resyncing
97+
- message: volume group is validated and met all prerequisites
98+
reason: PrerequisiteMet
99+
status: "True"
100+
type: Validated
101+
- message: 'volume group is replicating: local group is primary'
102+
reason: Replicating
103+
status: "True"
104+
type: Replicating
105+
lastCompletionTime: "2026-02-17T07:41:58Z"
106+
lastSyncBytes: 9793536
107+
lastSyncDuration: 0s
108+
lastSyncTime: "2026-02-17T07:40:01Z"
109+
message: volume group is marked primary
110+
state: Primary
111+
```
112+
113+
#### Secondary Status
114+
115+
**Description:** The Secondary status indicates that the volume group is in a read-only state and is receiving replicated data from the primary cluster. The volume group is not actively serving application I/O but is being kept in sync with the primary volume group. This state is typical for the standby cluster in a disaster recovery setup. The volume group is marked as degraded because it's in secondary mode and not available for writes.
116+
117+
Sample `status` of VGR when the volume group is demoted to `Secondary`:
118+
119+
```yaml
120+
status:
121+
conditions:
122+
- message: volume group is demoted to secondary
123+
reason: Demoted
124+
status: "True"
125+
type: Completed
126+
- message: volume group is degraded
127+
reason: VolumeDegraded
128+
status: "True"
129+
type: Degraded
130+
- message: volume group is not resyncing
131+
reason: NotResyncing
132+
status: "False"
133+
type: Resyncing
134+
- message: volume group is validated and met all prerequisites
135+
reason: PrerequisiteMet
136+
status: "True"
137+
type: Validated
138+
lastCompletionTime: "2026-02-17T07:41:58Z"
139+
message: volume group is marked secondary
140+
state: Secondary
141+
```
142+
143+
#### Demoted Status
144+
145+
**Description:** The Demoted status represents a transitional state where a volume group that was previously Primary has been demoted. This typically occurs during a planned failover or relocate operation. The volume group is no longer accepting writes and is in a degraded state. This is similar to the Secondary status but explicitly indicates the demotion operation has been completed.
146+
147+
Sample `status` of VGR when the volume group is `Demoted`:
148+
149+
```yaml
150+
status:
151+
conditions:
152+
- message: volume group is demoted to secondary
153+
reason: Demoted
154+
status: "True"
155+
type: Completed
156+
- message: volume group is degraded
157+
reason: VolumeDegraded
158+
status: "True"
159+
type: Degraded
160+
- message: volume group is not resyncing
161+
reason: NotResyncing
162+
status: "False"
163+
type: Resyncing
164+
lastCompletionTime: "2026-02-17T07:42:15Z"
165+
message: volume group is marked secondary
166+
state: Secondary
167+
```
168+
169+
#### Resyncing Status
170+
171+
**Description:** The Resyncing status indicates that the volume group is actively synchronizing data between the primary and secondary sites. This state occurs when replication has been interrupted (due to network issues, cluster downtime, or other failures) and the volume groups are now catching up. During resyncing, the volume group is marked as degraded and the Resyncing condition is set to True. The volume group may experience degraded performance as it transfers the delta of changes that occurred during the interruption.
172+
173+
Sample `status` of VGR when the volume group is `Resyncing`:
174+
175+
```yaml
176+
status:
177+
conditions:
178+
- message: volume group is demoted to secondary
179+
reason: Demoted
180+
status: "True"
181+
type: Completed
182+
- message: volume group is degraded
183+
reason: VolumeDegraded
184+
status: "True"
185+
type: Degraded
186+
- message: volume group is resyncing changes from primary to secondary
187+
reason: ResyncTriggered
188+
status: "True"
189+
type: Resyncing
190+
lastCompletionTime: "2026-02-17T07:40:00Z"
191+
lastSyncBytes: 5242880
192+
lastSyncDuration: 15s
193+
lastSyncTime: "2026-02-17T07:42:30Z"
194+
message: volume group is resyncing
195+
state: Secondary
196+
```
69197

70198
### Pre-Provisioned VolumeGroup
71199

‎docs/design/volumereplication.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,134 @@ To start with, users should create the VRC which contains the provisioner (csi d
4141
To start replication of the volume, the user needs to create a VR that contains the PVC as the dataSource which would be mirrored/replicated to a peer cluster, along with other required fields like the volumeReplicationClass (shared below) and the desired replicationState of the VR.
4242
The VR supports PVC and VolumeGroupReplication as the `dataSource` and the storage vendor is responsible for adding necessary checks to validate that if the dataSource is a single volume or a volumegroup and proceed accordingly. `replicationState` is used to determine if the VR is replicating to a secondary cluster i.e. `primary` or is on replicating end of the mirroring i.e. `secondary`.
4343

44+
If [RamenDR](https://github.com/RamenDR/ramen) is the extension/manager being used to manage DR for the workloads then, the storage vendor needs to add the below set of `Status` and `status.Conditions` to the VR for ramen to read the VR status and perform failover/relocate on the workload properly.
45+
46+
### VolumeReplication Status Examples
47+
48+
The following sections provide detailed examples of VolumeReplication status for different replication states. Each status example includes the necessary conditions and state information that RamenDR uses to manage disaster recovery operations. The condition's `Reason`, `Status`, and `Type` and the `status.State` must match the patterns shown below for RamenDR to correctly identify and manage the replication state.
49+
50+
#### Primary Status
51+
52+
**Description:** The Primary status indicates that the volume is actively serving I/O operations and is replicating data to a secondary cluster. This is the active state where the volume is being written to by applications, and changes are being mirrored to the secondary site for disaster recovery purposes. The volume is healthy and not in a degraded or resyncing state.
53+
54+
Sample `status` of VR when the volume is promoted to `Primary` successfully:
55+
56+
```yaml
57+
status:
58+
conditions:
59+
- message: volume is promoted to primary and replicating to secondary
60+
reason: Promoted
61+
status: "True"
62+
type: Completed
63+
- message: volume is healthy
64+
reason: Healthy
65+
status: "False"
66+
type: Degraded
67+
- message: volume is not resyncing
68+
reason: NotResyncing
69+
status: "False"
70+
type: Resyncing
71+
- message: volume is validated and met all prerequisites
72+
reason: PrerequisiteMet
73+
status: "True"
74+
type: Validated
75+
- message: 'volume is replicating: local image is primary'
76+
reason: Replicating
77+
status: "True"
78+
type: Replicating
79+
lastCompletionTime: "2026-02-17T07:41:58Z"
80+
lastSyncBytes: 9793536
81+
lastSyncDuration: 0s
82+
lastSyncTime: "2026-02-17T07:40:01Z"
83+
message: volume is marked primary
84+
state: Primary
85+
```
86+
87+
#### Secondary Status
88+
89+
**Description:** The Secondary status indicates that the volume is in a read-only state and is receiving replicated data from the primary cluster. The volume is not actively serving application I/O but is being kept in sync with the primary volume. This state is typical for the standby cluster in a disaster recovery setup. The volume is marked as degraded because it's in secondary mode and not available for writes.
90+
91+
Sample `status` of VR when the volume is demoted to `Secondary`:
92+
93+
```yaml
94+
status:
95+
conditions:
96+
- message: volume is demoted to secondary
97+
reason: Demoted
98+
status: "True"
99+
type: Completed
100+
- message: volume is degraded
101+
reason: VolumeDegraded
102+
status: "True"
103+
type: Degraded
104+
- message: volume is not resyncing
105+
reason: NotResyncing
106+
status: "False"
107+
type: Resyncing
108+
- message: volume is validated and met all prerequisites
109+
reason: PrerequisiteMet
110+
status: "True"
111+
type: Validated
112+
lastCompletionTime: "2026-02-17T07:41:58Z"
113+
message: volume is marked secondary
114+
state: Secondary
115+
```
116+
117+
#### Demoted Status
118+
119+
**Description:** The Demoted status represents a transitional state where a volume that was previously Primary has been demoted. This typically occurs during a planned failover or relocate operation. The volume is no longer accepting writes and is in a degraded state. This is similar to the Secondary status but explicitly indicates the demotion operation has been completed.
120+
121+
Sample `status` of VR when the volume is `Demoted`:
122+
123+
```yaml
124+
status:
125+
conditions:
126+
- message: volume is demoted to secondary
127+
reason: Demoted
128+
status: "True"
129+
type: Completed
130+
- message: volume is degraded
131+
reason: VolumeDegraded
132+
status: "True"
133+
type: Degraded
134+
- message: volume is not resyncing
135+
reason: NotResyncing
136+
status: "False"
137+
type: Resyncing
138+
lastCompletionTime: "2026-02-17T07:42:15Z"
139+
message: volume is marked secondary
140+
state: Secondary
141+
```
142+
143+
#### Resyncing Status
144+
145+
**Description:** The Resyncing status indicates that the volume is actively synchronizing data between the primary and secondary sites. This state occurs when replication has been interrupted (due to network issues, cluster downtime, or other failures) and the volumes are now catching up. During resyncing, the volume is marked as degraded and the Resyncing condition is set to True. The volume may experience degraded performance as it transfers the delta of changes that occurred during the interruption.
146+
147+
Sample `status` of VR when the volume is `Resyncing`:
148+
149+
```yaml
150+
status:
151+
conditions:
152+
- message: volume is demoted to secondary
153+
reason: Demoted
154+
status: "True"
155+
type: Completed
156+
- message: volume is degraded
157+
reason: VolumeDegraded
158+
status: "True"
159+
type: Degraded
160+
- message: volume is resyncing changes from primary to secondary
161+
reason: ResyncTriggered
162+
status: "True"
163+
type: Resyncing
164+
lastCompletionTime: "2026-02-17T07:40:00Z"
165+
lastSyncBytes: 5242880
166+
lastSyncDuration: 15s
167+
lastSyncTime: "2026-02-17T07:42:30Z"
168+
message: volume is resyncing
169+
state: Secondary
170+
```
171+
44172
## API definition of VolumeReplication (VR) CRD
45173

46174
- [VR Type Definition](https://github.com/csi-addons/kubernetes-csi-addons/blob/main/api/replication.storage/v1alpha1/volumereplication_types.go)

0 commit comments

Comments
 (0)