Skip to content

Commit 66a1443

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 66a1443

2 files changed

Lines changed: 263 additions & 1 deletion

File tree

‎docs/design/volumegroupreplication.md‎

Lines changed: 132 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,138 @@ 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.
75+
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.
76+
77+
#### Primary Status
78+
79+
**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.
80+
81+
Sample `status` of VGR when the volume group is promoted to `Primary` successfully:
82+
83+
```yaml
84+
status:
85+
conditions:
86+
- message: volume group is promoted to primary and replicating to secondary
87+
reason: Promoted
88+
status: "True"
89+
type: Completed
90+
- message: volume group is healthy
91+
reason: Healthy
92+
status: "False"
93+
type: Degraded
94+
- message: volume group is not resyncing
95+
reason: NotResyncing
96+
status: "False"
97+
type: Resyncing
98+
- message: volume group is validated and met all prerequisites
99+
reason: PrerequisiteMet
100+
status: "True"
101+
type: Validated
102+
- message: "volume group is replicating: local group is primary"
103+
reason: Replicating
104+
status: "True"
105+
type: Replicating
106+
lastCompletionTime: "2026-02-17T07:41:58Z"
107+
lastSyncBytes: 9793536
108+
lastSyncDuration: 0s
109+
lastSyncTime: "2026-02-17T07:40:01Z"
110+
message: volume group is marked primary
111+
state: Primary
112+
```
113+
114+
#### Secondary Status
115+
116+
**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.
117+
The volume group is marked as degraded because it's in secondary mode and not available for writes.
118+
119+
Sample `status` of VGR when the volume group is demoted to `Secondary`:
120+
121+
```yaml
122+
status:
123+
conditions:
124+
- message: volume group is demoted to secondary
125+
reason: Demoted
126+
status: "True"
127+
type: Completed
128+
- message: volume group is degraded
129+
reason: VolumeDegraded
130+
status: "True"
131+
type: Degraded
132+
- message: volume group is not resyncing
133+
reason: NotResyncing
134+
status: "False"
135+
type: Resyncing
136+
- message: volume group is validated and met all prerequisites
137+
reason: PrerequisiteMet
138+
status: "True"
139+
type: Validated
140+
lastCompletionTime: "2026-02-17T07:41:58Z"
141+
message: volume group is marked secondary
142+
state: Secondary
143+
```
144+
145+
#### Demoted Status
146+
147+
**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.
148+
149+
Sample `status` of VGR when the volume group is `Demoted`:
150+
151+
```yaml
152+
status:
153+
conditions:
154+
- message: volume group is demoted to secondary
155+
reason: Demoted
156+
status: "True"
157+
type: Completed
158+
- message: volume group is degraded
159+
reason: VolumeDegraded
160+
status: "True"
161+
type: Degraded
162+
- message: volume group is not resyncing
163+
reason: NotResyncing
164+
status: "False"
165+
type: Resyncing
166+
lastCompletionTime: "2026-02-17T07:42:15Z"
167+
message: volume group is marked secondary
168+
state: Secondary
169+
```
170+
171+
#### Resyncing Status
172+
173+
**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.
174+
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.
175+
176+
Sample `status` of VGR when the volume group is `Resyncing`:
177+
178+
```yaml
179+
status:
180+
conditions:
181+
- message: volume group is demoted to secondary
182+
reason: Demoted
183+
status: "True"
184+
type: Completed
185+
- message: volume group is degraded
186+
reason: VolumeDegraded
187+
status: "True"
188+
type: Degraded
189+
- message: volume group is resyncing changes from primary to secondary
190+
reason: ResyncTriggered
191+
status: "True"
192+
type: Resyncing
193+
lastCompletionTime: "2026-02-17T07:40:00Z"
194+
lastSyncBytes: 5242880
195+
lastSyncDuration: 15s
196+
lastSyncTime: "2026-02-17T07:42:30Z"
197+
message: volume group is resyncing
198+
state: Secondary
199+
```
69200

70201
### Pre-Provisioned VolumeGroup
71202

‎docs/design/volumereplication.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,137 @@ 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.
49+
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.
50+
51+
#### Primary Status
52+
53+
**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.
54+
55+
Sample `status` of VR when the volume is promoted to `Primary` successfully:
56+
57+
```yaml
58+
status:
59+
conditions:
60+
- message: volume is promoted to primary and replicating to secondary
61+
reason: Promoted
62+
status: "True"
63+
type: Completed
64+
- message: volume is healthy
65+
reason: Healthy
66+
status: "False"
67+
type: Degraded
68+
- message: volume is not resyncing
69+
reason: NotResyncing
70+
status: "False"
71+
type: Resyncing
72+
- message: volume is validated and met all prerequisites
73+
reason: PrerequisiteMet
74+
status: "True"
75+
type: Validated
76+
- message: "volume is replicating: local image is primary"
77+
reason: Replicating
78+
status: "True"
79+
type: Replicating
80+
lastCompletionTime: "2026-02-17T07:41:58Z"
81+
lastSyncBytes: 9793536
82+
lastSyncDuration: 0s
83+
lastSyncTime: "2026-02-17T07:40:01Z"
84+
message: volume is marked primary
85+
state: Primary
86+
```
87+
88+
#### Secondary Status
89+
90+
**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.
91+
The volume is marked as degraded because it's in secondary mode and not available for writes.
92+
93+
Sample `status` of VR when the volume is demoted to `Secondary`:
94+
95+
```yaml
96+
status:
97+
conditions:
98+
- message: volume is demoted to secondary
99+
reason: Demoted
100+
status: "True"
101+
type: Completed
102+
- message: volume is degraded
103+
reason: VolumeDegraded
104+
status: "True"
105+
type: Degraded
106+
- message: volume is not resyncing
107+
reason: NotResyncing
108+
status: "False"
109+
type: Resyncing
110+
- message: volume is validated and met all prerequisites
111+
reason: PrerequisiteMet
112+
status: "True"
113+
type: Validated
114+
lastCompletionTime: "2026-02-17T07:41:58Z"
115+
message: volume is marked secondary
116+
state: Secondary
117+
```
118+
119+
#### Demoted Status
120+
121+
**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.
122+
123+
Sample `status` of VR when the volume is `Demoted`:
124+
125+
```yaml
126+
status:
127+
conditions:
128+
- message: volume is demoted to secondary
129+
reason: Demoted
130+
status: "True"
131+
type: Completed
132+
- message: volume is degraded
133+
reason: VolumeDegraded
134+
status: "True"
135+
type: Degraded
136+
- message: volume is not resyncing
137+
reason: NotResyncing
138+
status: "False"
139+
type: Resyncing
140+
lastCompletionTime: "2026-02-17T07:42:15Z"
141+
message: volume is marked secondary
142+
state: Secondary
143+
```
144+
145+
#### Resyncing Status
146+
147+
**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.
148+
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.
149+
150+
Sample `status` of VR when the volume is `Resyncing`:
151+
152+
```yaml
153+
status:
154+
conditions:
155+
- message: volume is demoted to secondary
156+
reason: Demoted
157+
status: "True"
158+
type: Completed
159+
- message: volume is degraded
160+
reason: VolumeDegraded
161+
status: "True"
162+
type: Degraded
163+
- message: volume is resyncing changes from primary to secondary
164+
reason: ResyncTriggered
165+
status: "True"
166+
type: Resyncing
167+
lastCompletionTime: "2026-02-17T07:40:00Z"
168+
lastSyncBytes: 5242880
169+
lastSyncDuration: 15s
170+
lastSyncTime: "2026-02-17T07:42:30Z"
171+
message: volume is resyncing
172+
state: Secondary
173+
```
174+
44175
## API definition of VolumeReplication (VR) CRD
45176

46177
- [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)