fix: Update status design with NAR (#70)

Signed-off-by: Mateus Oliveira <[email protected]>

api/v1alpha1/nonadminbackup_types.go

@@ -45,20 +45,25 @@ type NonAdminBackupSpec struct {
 	LogLevel string `json:"logLevel,omitempty"`
 }
 
-// NonAdminBackupStatus defines the observed state of NonAdminBackup
-type NonAdminBackupStatus struct {
-	// VeleroBackupName references the VeleroBackup object by it's name.
+// VeleroBackup contains information of the related Velero backup object.
+type VeleroBackup struct {
+	// status captures the current status of the Velero backup.
 	// +optional
-	VeleroBackupName string `json:"veleroBackupName,omitempty"`
+	Status *velerov1.BackupStatus `json:"status,omitempty"`
 
-	// VeleroBackupNamespace references the Namespace
-	// in which VeleroBackupName object exists.
+	// name references the Velero backup by it's name.
 	// +optional
-	VeleroBackupNamespace string `json:"veleroBackupNamespace,omitempty"`
+	Name string `json:"name,omitempty"`
 
-	// VeleroBackupStatus captures the current status of a Velero backup.
+	// namespace references the Namespace in which Velero backup exists.
+	// +optional
+	Namespace string `json:"namespace,omitempty"`
+}
+
+// NonAdminBackupStatus defines the observed state of NonAdminBackup
+type NonAdminBackupStatus struct {
 	// +optional
-	VeleroBackupStatus *velerov1.BackupStatus `json:"veleroBackupStatus,omitempty"`
+	VeleroBackup *VeleroBackup `json:"veleroBackup,omitempty"`
 
 	Phase      NonAdminBackupPhase `json:"phase,omitempty"`
 	Conditions []metav1.Condition  `json:"conditions,omitempty"`

docs/design/nab_and_nar_status_update.md

@@ -0,0 +1,192 @@
+# Controller Workflow: NonAdminBackup and NonAdminRestore Status Update
+
+## Overview
+
+This document outlines the design around updating NonAdminBackup (NAB) and NonAdminRestore (NAR) objects' Statuses.
+
+## NonAdminBackup and NonAdminRestore Status
+
+The `status` field of NAB and NAR objects contains the following fields:
+- `phase`
+- `conditions`
+- `veleroBackup` for NAB and `veleroRestore` for NAR, which contains name, namespace and status of the related Velero object.
+
+which are updated by NAB and NAR controllers.
+
+Only one update call should be performed per reconcile of NAB and NAR objects. Controller can requeue or depend on predicates if more updates are needed in that object.
+
+### Phase
+
+The `phase` field is a simple one high-level summary of the lifecycle of the objects, that only moves forward. Once a `phase` changes, it can not return to the previous value.
+
+It is always a one well defined value, that is intended to be a comprehensive state of a NAB or NAR object.
+
+Those are are the possible values for phase:
+
+| **Value** | **Description** |
+|-----------|-----------------|
+| New | *NonAdminBackup/NonAdminRestore* resource was accepted by the NAB/NAR Controller, but it has not yet been validated by the NAB/NAR Controller |
+| BackingOff | *NonAdminBackup/NonAdminRestore* resource was invalidated by the NAB/NAR Controller, due to invalid Spec. NAB/NAR Controller will not reconcile the object further, until user updates it |
+| Created | *NonAdminBackup/NonAdminRestore* resource was validated by the NAB/NAR Controller and Velero *Backup/restore* was created. The Phase will not have additional information about the *Backup/Restore* run |
+
+### Conditions
+
+The `conditions` field is a list of conditions.
+One NAB/NAR object may have multiple conditions.
+It is more granular knowledge of the NAB/NAR object and represents the array of the conditions through which the object has or has not passed.
+
+Each `condition` data is composed by the following:
+
+| **Field name** | **Description** |
+|----------------|-----------------|
+| type | The `NonAdminCondition` of the condition |
+| status | represents the state of individual condition. One of `True`, `False` or `Unknown`. |
+| lastTransitionTime | Timestamp for when this condition was created/updated. |
+| reason | Machine-readable, UpperCamelCase text indicating details about the last status transition. |
+| message | Human-readable message indicating details about the last status transition. |
+
+Those are are the possible values for `NonAdminCondition`:
+
+| **Value** | **Description** |
+|-----------|-----------------|
+| Accepted | The NonAdminBackup/NonAdminRestore object was accepted by the controller, but the Velero Backup/Restore may have not yet been created |
+| Queued | The Velero Backup/Restore was created successfully. At this stage errors may still occur either from the Velero not accepting object or during backup/restore procedure. |
+
+### Velero object reference
+
+NonAdminBackup/NonAdminRestore `status` contains reference to the related Velero Backup/Restore.
+
+NonAdminBackup `status.veleroBackup` contains `name`, `namespace` and `status`.
+- `status.veleroBackup.name` represents the name of the `VeleroBackup` object.
+- `status.veleroBackup.namespace` represents the namespace in which the `VeleroBackup` object was created.
+- `status.veleroBackup.status` field is a copy of the `VeleroBackup` object status.
+
+The format of those fields allows to interact with that Backup using `oc` or `velero` commands as follows:
+
+```yaml
+status:
+  veleroBackup:
+    name: nab-nacproject-c3499c2729730a
+    namespace: openshift-adp
+    status:
+     ...
+```
+
+```shell
+velero backup describe -n openshift-adp nab-nacproject-c3499c2729730a
+```
+
+Similarly, NonAdminRestore `status.veleroRestore` contains `name`, `namespace` and `status`.
+- `status.veleroRestore.name` represents the name of the `veleroRestore` object.
+- `status.veleroRestore.namespace` represents the namespace in which the `veleroRestore` object was created.
+- `status.veleroRestore.status` field is a copy of the `VeleroBackup` object status.
+
+## Example
+
+Sample status field of a NonAdminBackup object.
+It is similar for a NonAdminRestore.
+
+Object passed validation and Velero `Backup` object was created, but there was an error while performing backup operation:
+
+```yaml
+status:
+  veleroBackup:
+    name: nab-nacproject-83fc04a2fd253d
+    namespace: openshift-adp
+    status:
+      expiration: '2024-05-16T08:12:11Z'
+      failureReason: >-
+        unable to get credentials: unable to get key for secret: Secret
+        "cloud-credentials" not found
+      formatVersion: 1.1.0
+      phase: Failed
+      startTimestamp: '2024-04-16T08:12:11Z'
+      version: 1
+  conditions:
+    - lastTransitionTime: '2024-04-15T20:27:35Z'
+      message: NonAdminBackup object was validated
+      reason: NonAdminBackupAccepted
+      status: 'True'
+      type: Accepted
+    - lastTransitionTime: '2024-04-15T20:27:45Z'
+      message: Created Velero Backup object
+      reason: BackupScheduled
+      status: 'True'
+      type: Queued
+  phase: Created
+```
+
+## Status Update scenarios
+
+The following graph shows the lifecycle of a NonAdminBackup.
+It is similar for a NonAdminRestore.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph
+event1{{predicate: Create event NAB}} == If event is accepted ==>
+
+reconcileStart1[/Reconcile start\] ==>
+
+phaseNew["`status.phase to **New**`"] -. Requeue: false, err .-> reconcileStart1
+phaseNew ==>
+
+reconcileExit1[\Requeue: true, nil/]
+reconcileExit1 ==> question(is NonAdminBackup Spec valid?) == yes ==> reconcileStart2
+question == no ==> reconcileStartInvalid1
+
+reconcileStart2[/Reconcile start\] ==>
+
+conditionsAcceptedTrue["`status.conditions[Accepted] to **True**`"] -. Requeue: false, err .- reconcileStart2
+conditionsAcceptedTrue ==>
+
+reconcileExit2[\Requeue: true, nil/] ==>
+
+reconcileStart3[/Reconcile start\] ==>
+
+createVeleroBackup([Create Velero Backup]) -. Requeue: false, err .- reconcileStart3
+createVeleroBackup ==>
+
+phaseCreated["`
+status.phase: **Created**
+status.conditions[Queued] to **True**
+status.conditions.veleroBackup.name
+status.conditions.veleroBackup.namespace
+`"] -. Requeue: false, err .- reconcileStart3
+phaseCreated ==>
+
+reconcileExit4[\Requeue: false, nil/]
+
+reconcileStartInvalid1[/Reconcile start\] ==>
+
+phaseBackingOff["`
+status.phase to **BackingOff**
+status.conditions[Accepted] to **False**
+`"] -. Requeue: false, err .- reconcileStartInvalid1
+phaseBackingOff ==>
+
+reconcileExitInvalid1[\Requeue: false, TerminalError/]
+
+reconcileExit4 ~~~ event2
+reconcileExitInvalid1 ~~~ event2
+
+event2{{predicate: Update event VeleroBackup}} == If event is accepted ==>
+handler1{{handler: Handle VeleroBackup update event}} ==> reconcileStart5
+
+reconcileStart5[/Reconcile start\] ==> conditionsVeleroBackupStatus
+
+conditionsVeleroBackupStatus["`status.conditions.veleroBackup.status`"] -. Requeue: false, err .- reconcileStart5
+conditionsVeleroBackupStatus ==>
+
+reconcileExit5[\Requeue: false, nil/]
+
+reconcileExit5 ~~~ event3
+
+event3{{predicate: Delete event NAB}} == If event is accepted ==>
+
+reconcileDelete1[/Reconcile start\] ==>
+
+reconcileExitDelete1[\Requeue: false, nil/] -. Requeue: false, err .-> reconcileDelete1
+
+event4{{predicate: Update event NAB}} == If event is accepted ==> question
+```

go.mod

@@ -76,4 +76,4 @@ require (
 	sigs.k8s.io/yaml v1.4.0 // indirect
 )
 
-replace github.com/vmware-tanzu/velero => github.com/openshift/velero v0.10.2-0.20240822161636-3fac5687bd46
+replace github.com/vmware-tanzu/velero => github.com/openshift/velero v0.10.2-0.20240919150610-92244630d90b

go.sum

@@ -73,8 +73,8 @@ github.com/onsi/ginkgo/v2 v2.19.0 h1:9Cnnf7UHo57Hy3k6/m5k3dRfGTMXGvxhHFvkDTCTpvA
 github.com/onsi/ginkgo/v2 v2.19.0/go.mod h1:rlwLi9PilAFJ8jCg9UE1QP6VBpd6/xj3SRC0d6TU0To=
 github.com/onsi/gomega v1.33.1 h1:dsYjIxxSR755MDmKVsaFQTE22ChNBcuuTWgkUDSubOk=
 github.com/onsi/gomega v1.33.1/go.mod h1:U4R44UsT+9eLIaYRB2a5qajjtQYn0hauxvRm16AVYg0=
-github.com/openshift/velero v0.10.2-0.20240822161636-3fac5687bd46 h1:wj9bG3qyi1RQ36Q3scsCAeI/qHFth9hOfz+FXn+h02c=
-github.com/openshift/velero v0.10.2-0.20240822161636-3fac5687bd46/go.mod h1:xzqumeJMjRgQUByty8syvsXzhn1fhcTkFaui4SNkGiY=
+github.com/openshift/velero v0.10.2-0.20240919150610-92244630d90b h1:J8LV6NzonNemUxxsr76Lhl5+CnqBuQqojaf6Y7MwF24=
+github.com/openshift/velero v0.10.2-0.20240919150610-92244630d90b/go.mod h1:1Jk51qruLY/LCG8RMy6nVLVctIlWqJ9KBNXWroHzJZg=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=