volumegroup: crd and doc updates for volumegroup replication

api/replication.storage/v1alpha1/volumegroupreplication_types.go

@@ -28,9 +28,10 @@ type VolumeGroupReplicationSpec struct {
 	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="volumeGroupReplicationClassName is immutable"
 	VolumeGroupReplicationClassName string `json:"volumeGroupReplicationClassName"`
 
-	// volumeReplicationClassName is the volumeReplicationClass name for VolumeReplication object
+	// volumeReplicationClassName is the volumeReplicationClass name for the VolumeReplication object
+	// created for this volumeGroupReplication
 	// +kubebuilder:validation:Required
-	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="volumReplicationClassName is immutable"
+	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="volumeReplicationClassName is immutable"
 	VolumeReplicationClassName string `json:"volumeReplicationClassName"`
 
 	// Name of the VolumeReplication object created for this volumeGroupReplication
@@ -65,7 +66,7 @@ type VolumeGroupReplicationSpec struct {
 type VolumeGroupReplicationSource struct {
 	// Selector is a label query over persistent volume claims that are to be
 	// grouped together for replication.
-	// +optional
+	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="selector is immutable"
 	Selector *metav1.LabelSelector `json:"selector,omitempty"`
 }

api/replication.storage/v1alpha1/volumegroupreplicationcontent_types.go

@@ -27,16 +27,15 @@ type VolumeGroupReplicationContentSpec struct {
 	// VolumeGroupReplicationContent object is bound.
 	// VolumeGroupReplication.Spec.VolumeGroupReplicationContentName field must reference to
 	// this VolumeGroupReplicationContent's name for the bidirectional binding to be valid.
-	// For a pre-existing VolumeGroupReplicationContent object, name and namespace of the
-	// VolumeGroupReplication object MUST be provided for binding to happen.
-	// This field is immutable after creation.
-	// Required.
-	// +kubebuilder:validation:XValidation:rule="has(self.name) && has(self.__namespace__)",message="both volumeGroupReplicationRef.name and volumeGroupReplicationRef.namespace must be set"
-	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="volumeGroupReplicationRef is immutable"
-	VolumeGroupReplicationRef corev1.ObjectReference `json:"volumeGroupReplicationRef"`
+	// For a pre-existing VolumeGroupReplication object, MUST provide an empty/nil value for
+	// VolumeGroupReplicationRef for the auto-binding to happen.
+	// +kubebuilder:validation:Optional
+	// +kubebuilder:validation:XValidation:rule="self != null ? has(self.name) && has(self.__namespace__) && has(self.uid) : true",message="volumeGroupReplicationRef.name, volumeGroupReplicationRef.namespace and volumeGroupReplicationRef.uid must be set if volumeGroupReplicationRef is defined"
+	VolumeGroupReplicationRef *corev1.ObjectReference `json:"volumeGroupReplicationRef,omitempty"`
 
 	// VolumeGroupReplicationHandle is a unique id returned by the CSI driver
 	// to identify the VolumeGroupReplication on the storage system.
+	// +kubebuilder:validation:Optional
 	VolumeGroupReplicationHandle string `json:"volumeGroupReplicationHandle"`
 
 	// provisioner is the name of the CSI driver used to create the physical
@@ -45,30 +44,34 @@ type VolumeGroupReplicationContentSpec struct {
 	// This MUST be the same as the name returned by the CSI GetPluginName() call for
 	// that driver.
 	// Required.
+	// +kubebuilder:validation:Required
 	Provisioner string `json:"provisioner"`
 
 	// VolumeGroupReplicationClassName is the name of the VolumeGroupReplicationClass from
 	// which this group replication was (or will be) created.
-	// +optional
+	// Required.
+	// +kubebuilder:validation:Required
 	VolumeGroupReplicationClassName string `json:"volumeGroupReplicationClassName"`
 
-	// Source specifies whether the snapshot is (or should be) dynamically provisioned
-	// or already exists, and just requires a Kubernetes object representation.
-	// This field is immutable after creation.
+	// Source specifies whether the volume group is (or should be) dynamically provisioned
+	// or already exists using the volumes listed here, and just requires a
+	// Kubernetes object representation.
 	// Required.
+	// +kubebuilder:validation:Required
 	Source VolumeGroupReplicationContentSource `json:"source"`
 }
 
 // VolumeGroupReplicationContentSource represents the CSI source of a group replication.
 type VolumeGroupReplicationContentSource struct {
 	// VolumeHandles is a list of volume handles on the backend to be grouped
 	// and replicated.
+	// +kubebuilder:validation:Required
 	VolumeHandles []string `json:"volumeHandles"`
 }
 
 // VolumeGroupReplicationContentStatus defines the status of VolumeGroupReplicationContent
 type VolumeGroupReplicationContentStatus struct {
-	// PersistentVolumeRefList is the list of of PV for the group replication
+	// PersistentVolumeRefList is the list of PV for the group replication
 	// The maximum number of allowed PV in the group is 100.
 	// +optional
 	PersistentVolumeRefList []corev1.LocalObjectReference `json:"persistentVolumeRefList,omitempty"`

config/crd/bases/replication.storage.openshift.io_volumegroupreplicationcontents.yaml

@@ -52,9 +52,9 @@ spec:
                 type: string
               source:
                 description: |-
-                  Source specifies whether the snapshot is (or should be) dynamically provisioned
-                  or already exists, and just requires a Kubernetes object representation.
-                  This field is immutable after creation.
+                  Source specifies whether the volume group is (or should be) dynamically provisioned
+                  or already exists using the volumes listed here, and just requires a
+                  Kubernetes object representation.
                   Required.
                 properties:
                   volumeHandles:
@@ -71,6 +71,7 @@ spec:
                 description: |-
                   VolumeGroupReplicationClassName is the name of the VolumeGroupReplicationClass from
                   which this group replication was (or will be) created.
+                  Required.
                 type: string
               volumeGroupReplicationHandle:
                 description: |-
@@ -83,10 +84,8 @@ spec:
                   VolumeGroupReplicationContent object is bound.
                   VolumeGroupReplication.Spec.VolumeGroupReplicationContentName field must reference to
                   this VolumeGroupReplicationContent's name for the bidirectional binding to be valid.
-                  For a pre-existing VolumeGroupReplicationContent object, name and namespace of the
-                  VolumeGroupReplication object MUST be provided for binding to happen.
-                  This field is immutable after creation.
-                  Required.
+                  For a pre-existing VolumeGroupReplication object, MUST provide an empty/nil value for
+                  VolumeGroupReplicationRef for the auto-binding to happen.
                 properties:
                   apiVersion:
                     description: API version of the referent.
@@ -129,24 +128,23 @@ spec:
                 type: object
                 x-kubernetes-map-type: atomic
                 x-kubernetes-validations:
-                - message: both volumeGroupReplicationRef.name and volumeGroupReplicationRef.namespace
-                    must be set
-                  rule: has(self.name) && has(self.__namespace__)
-                - message: volumeGroupReplicationRef is immutable
-                  rule: self == oldSelf
+                - message: volumeGroupReplicationRef.name, volumeGroupReplicationRef.namespace
+                    and volumeGroupReplicationRef.uid must be set if volumeGroupReplicationRef
+                    is defined
+                  rule: 'self != null ? has(self.name) && has(self.__namespace__)
+                    && has(self.uid) : true'
             required:
             - provisioner
             - source
-            - volumeGroupReplicationHandle
-            - volumeGroupReplicationRef
+            - volumeGroupReplicationClassName
             type: object
           status:
             description: VolumeGroupReplicationContentStatus defines the status of
               VolumeGroupReplicationContent
             properties:
               persistentVolumeRefList:
                 description: |-
-                  PersistentVolumeRefList is the list of of PV for the group replication
+                  PersistentVolumeRefList is the list of PV for the group replication
                   The maximum number of allowed PV in the group is 100.
                 items:
                   description: |-

config/crd/bases/replication.storage.openshift.io_volumegroupreplications.yaml

@@ -112,6 +112,8 @@ spec:
                     x-kubernetes-validations:
                     - message: selector is immutable
                       rule: self == oldSelf
+                required:
+                - selector
                 type: object
                 x-kubernetes-validations:
                 - message: source is immutable
@@ -131,11 +133,12 @@ spec:
                 - message: volumeGroupReplicationContentName is immutable
                   rule: self == oldSelf
               volumeReplicationClassName:
-                description: volumeReplicationClassName is the volumeReplicationClass
-                  name for VolumeReplication object
+                description: |-
+                  volumeReplicationClassName is the volumeReplicationClass name for the VolumeReplication object
+                  created for this volumeGroupReplication
                 type: string
                 x-kubernetes-validations:
-                - message: volumReplicationClassName is immutable
+                - message: volumeReplicationClassName is immutable
                   rule: self == oldSelf
               volumeReplicationName:
                 description: Name of the VolumeReplication object created for this

deploy/controller/crds.yaml

@@ -1414,9 +1414,9 @@ spec:
                 type: string
               source:
                 description: |-
-                  Source specifies whether the snapshot is (or should be) dynamically provisioned
-                  or already exists, and just requires a Kubernetes object representation.
-                  This field is immutable after creation.
+                  Source specifies whether the volume group is (or should be) dynamically provisioned
+                  or already exists using the volumes listed here, and just requires a
+                  Kubernetes object representation.
                   Required.
                 properties:
                   volumeHandles:
@@ -1433,6 +1433,7 @@ spec:
                 description: |-
                   VolumeGroupReplicationClassName is the name of the VolumeGroupReplicationClass from
                   which this group replication was (or will be) created.
+                  Required.
                 type: string
               volumeGroupReplicationHandle:
                 description: |-
@@ -1445,10 +1446,8 @@ spec:
                   VolumeGroupReplicationContent object is bound.
                   VolumeGroupReplication.Spec.VolumeGroupReplicationContentName field must reference to
                   this VolumeGroupReplicationContent's name for the bidirectional binding to be valid.
-                  For a pre-existing VolumeGroupReplicationContent object, name and namespace of the
-                  VolumeGroupReplication object MUST be provided for binding to happen.
-                  This field is immutable after creation.
-                  Required.
+                  For a pre-existing VolumeGroupReplication object, MUST provide an empty/nil value for
+                  VolumeGroupReplicationRef for the auto-binding to happen.
                 properties:
                   apiVersion:
                     description: API version of the referent.
@@ -1491,24 +1490,23 @@ spec:
                 type: object
                 x-kubernetes-map-type: atomic
                 x-kubernetes-validations:
-                - message: both volumeGroupReplicationRef.name and volumeGroupReplicationRef.namespace
-                    must be set
-                  rule: has(self.name) && has(self.__namespace__)
-                - message: volumeGroupReplicationRef is immutable
-                  rule: self == oldSelf
+                - message: volumeGroupReplicationRef.name, volumeGroupReplicationRef.namespace
+                    and volumeGroupReplicationRef.uid must be set if volumeGroupReplicationRef
+                    is defined
+                  rule: 'self != null ? has(self.name) && has(self.__namespace__)
+                    && has(self.uid) : true'
             required:
             - provisioner
             - source
-            - volumeGroupReplicationHandle
-            - volumeGroupReplicationRef
+            - volumeGroupReplicationClassName
             type: object
           status:
             description: VolumeGroupReplicationContentStatus defines the status of
               VolumeGroupReplicationContent
             properties:
               persistentVolumeRefList:
                 description: |-
-                  PersistentVolumeRefList is the list of of PV for the group replication
+                  PersistentVolumeRefList is the list of PV for the group replication
                   The maximum number of allowed PV in the group is 100.
                 items:
                   description: |-
@@ -1647,6 +1645,8 @@ spec:
                     x-kubernetes-validations:
                     - message: selector is immutable
                       rule: self == oldSelf
+                required:
+                - selector
                 type: object
                 x-kubernetes-validations:
                 - message: source is immutable
@@ -1666,11 +1666,12 @@ spec:
                 - message: volumeGroupReplicationContentName is immutable
                   rule: self == oldSelf
               volumeReplicationClassName:
-                description: volumeReplicationClassName is the volumeReplicationClass
-                  name for VolumeReplication object
+                description: |-
+                  volumeReplicationClassName is the volumeReplicationClass name for the VolumeReplication object
+                  created for this volumeGroupReplication
                 type: string
                 x-kubernetes-validations:
-                - message: volumReplicationClassName is immutable
+                - message: volumeReplicationClassName is immutable
                   rule: self == oldSelf
               volumeReplicationName:
                 description: Name of the VolumeReplication object created for this

docs/volumegroupreplication.md

@@ -0,0 +1,60 @@
+# VolumeGroupReplication
+
+VolumeGroupReplication is a namespaced resource that contains references to storage object to be grouped and replicated, VolumeGroupReplicationClass corresponding to the driver providing replication, VolumeGroupReplicationContent and VolumeReplication CRs.
+
+`volumeGroupReplicationClassName` is the name of the class providing group replication.
+
+`volumeReplicationClassName` is the name of the class providing the replication for volumeReplication CR.
+
+`volumeReplicationName` is the name of the volumeReplication CR created by this volumeGroupReplication CR.
+
+`volumeGroupReplicationContentName` is the name of the volumeGroupReplicationContent CR created for this volumeGroupReplication CR.
+
+`replicationState` is the state of the volume group being referenced. Possible values are `primary`, `secondary` and `resync`.
+
+- `primary` denotes that the volume group is primary
+- `secondary` denotes that the volume group is secondary
+- `resync` denotes that the volume group needs to be resynced
+
+`source` contains the source of the volumeGroupReplication i.e, the selectors to match the PVC/PVs to be replicated.
+
+- `selector` is a label selector to filter the pvcs that are to be included in the group replication
+
+```yaml
+apiVersion: replication.storage.openshift.io/v1alpha1
+kind: VolumeGroupReplication
+metadata:
+  name: volumegroupreplication-sample
+  namespace: default
+spec:
+  volumeReplicationClassName: volumereplicationclass-sample
+  volumeGroupReplicationClassName: volumegroupreplicationclass-sample
+  replicationState: primary
+  source:
+    selector:
+      matchLabels:
+        appname: test
+  autoResync: false
+status:
+  persistentVolumeClaimsRefList:
+    - test-pvc
+  state: primary
+```
+
+Example PVC having matching labels:
+
+```yaml
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: test-pvc
+  labels:
+    appname: test
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 1Gi
+  storageClassName: rook-ceph-block
+```

docs/volumegroupreplicationcontent.md

@@ -0,0 +1,33 @@
+# VolumeGroupReplicationContent
+
+VolumeGroupReplicationContent is a cluster scoped resource that contains volume grouping related information.
+
+`volumeGroupReplicationRef` contains object reference of the volumeGroupReplication resource that created this resource.
+
+`volumeGroupReplicationHandle` (optional) is an existing (but new) group replication ID.
+
+`volumeGroupReplicationClassName` is the name of the VolumeGroupReplicationClass that contains the driver related info
+for volume grouping.
+
+`source` (optional) contains the VolumeGroupReplicationContentSource struct.
+
+- `VolumeHandles` is the list of volume handles that this resource is responsible for grouping.
+
+```yaml
+apiVersion: replication.storage.openshift.io/v1alpha1
+kind: VolumeGroupReplicationContent
+metadata:
+  name: volumegroupreplicationcontent-sample
+spec:
+  volumeGroupReplicationRef:
+    kind: VolumeGroupReplication
+    name: volumegroupreplication-sample
+    namespace: default
+  volumeGroupReplicationClassName: volumegroupreplicationclass-sample
+  provisioner: example.provisioner.io
+  source:
+    volumeHandles:
+      - myPersistentVolumeHandle
+      - myPersistentVolumeHandle1
+      - myPersistentVolumeHandle2
+```

docs/volumereplicationclass.md

@@ -1,6 +1,6 @@
 # VolumeReplicationClass
 
-`VolumeReplicationClass` is a cluster scoped resource that contains driver related configuration parameters.
+VolumeReplicationClass is a cluster scoped resource that contains driver related configuration parameters.
 
 `provisioner` is name of the storage provisioner.