Support an eventual phase for the blueprint actions (#1297)

* Support `deferPhase` in blueprint action

Blueprints can now define `deferPhase` for every action
that would be run once all (some in case of failure) the
phases of a blueprint action are run.

* Update docs for deferPhase changes

* Handle the scenario where only deferPhase is failed

* Try to fix CI by increasing actionset wait timeout

* Refactor code and add test for utility functions

* Address review comment, modularise functions

* Fix a bug while only deferPhase was failing

* Fix bug where actionset status was being set to complete even after
one of the core phases failed

The actionset status eventually must be failed if either one of core
phases or deferphases failed but we had a problem because of which
the actionset status was being set to complete even if the one of the
core phases failed. This commit fixes that.
It was happening because we were unknowingly setting error to nil
in deferPhase because deferPhase ran successfully.

* Address review comment, reword comments and docs

* Update the wait actionset timeout to 20 seconds

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

docs/architecture.rst

@@ -71,6 +71,7 @@ The definition of a ``BlueprintAction`` is:
       InputArtifactNames []string            `json:"inputArtifactNames"`
       OutputArtifacts    map[string]Artifact `json:"outputArtifacts"`
       Phases             []BlueprintPhase    `json:"phases"`
+      DeferPhase         *BlueprintPhase     `json:"deferPhase,omitempty"`
   }
 
 - ``Kind`` represents the type of Kubernetes object this BlueprintAction is written for.
@@ -84,6 +85,10 @@ The definition of a ``BlueprintAction`` is:
   to the ``BlueprintAction``.
 - ``Phases`` is a required list of ``BlueprintPhases``. These phases are invoked
   in order when executing this Action.
+- ``DeferPhase`` is an optional ``BlueprintPhase`` invoked after the
+  execution of ``Phases`` defined above. A ``DeferPhase``, when specified,
+  is executed regardless of the statuses of the ``Phases``.
+  A ``DeferPhase`` can be used for cleanup operations at the end of an ``Action``.
 
 .. code-block:: go
   :linenos:

docs/templates.rst

@@ -25,6 +25,7 @@ The TemplateParam struct is defined as:
     Options          map[string]string
     Object           map[string]interface{}
     Phases           map[string]*Phase
+    DeferPhase       *Phase
     PodOverride      crv1alpha1.JSONMap
   }
 
@@ -609,3 +610,28 @@ Similarly, a phase can use Secrets as arguments:
 .. code-block:: go
 
   "{{ .Phases.phase-name.Secrets.secret-name.Namespace }}"
+
+DeferPhase
+----------
+
+``DeferPhase`` is used to capture information returned from the Blueprint's ``DeferPhase``
+execution. The information is stored in the ``Phase`` struct that has the below
+definition:
+
+.. code-block:: go
+  :linenos:
+
+  type Phase struct {
+    Secrets map[string]v1.Secret
+    Output  map[string]interface{}
+  }
+
+Output artifact can be set as follows:
+
+.. code-block:: go
+
+  "{{ .DeferPhase.Output.key-name }}"
+
+
+Output artifacts that are set using ``DeferPhase`` can be consumed by other actions'
+phases using the same way other output artifacts are consumed.

docs/tutorial.rst

@@ -443,6 +443,60 @@ ConfigMap.
 If you re-execute this Kanister Action, you'll be able to see the Artifact in the
 ActionSet status.
 
+If you use a ``DeferPhase``, below is how you can set the output artifact
+from the output that is being generated from ``DeferPhase`` as shown below.
+
+.. code-block:: yaml
+
+  cat <<EOF | kubectl apply -f -
+  apiVersion: cr.kanister.io/v1alpha1
+  kind: Blueprint
+  metadata:
+    name: time-log-bp
+    namespace: kanister
+  actions:
+    backup:
+      configMapNames:
+      - location
+      secretNames:
+      - aws
+      outputArtifacts:
+        timeLog:
+          keyValue:
+            path: '{{ .ConfigMaps.location.Data.path }}/time-log/'
+        deferPhaseArt:
+          keyValue:
+            time: "{{ .DeferPhase.Output.bkpCompletedTime }}"
+      phases:
+        - func: KubeExec
+          name: backupToS3
+          args:
+            namespace: "{{ .Deployment.Namespace }}"
+            pod: "{{ index .Deployment.Pods 0 }}"
+            container: test-container
+            command:
+              - sh
+              - -c
+              - |
+                echo "Main Phase"
+      deferPhase:
+        func: KubeTask
+        name: saveBackupTime
+        args:
+          image: ghcr.io/kanisterio/mysql-sidecar:0.74.0
+          namespace: "{{ .Deployment.Namespace }}"
+          command:
+          - sh
+          - -c
+          - |
+            echo "DeferPhase"
+            kando output bkpCompletedTime "10Minutes"
+  EOF
+
+
+Output from the previous phases can also be used in the ``DeferPhase`` like it
+is used in normal scenarios.
+
 Input Artifacts
 ---------------
 

pkg/apis/cr/v1alpha1/types.go

@@ -126,6 +126,9 @@ type ActionStatus struct {
 	Phases []Phase `json:"phases,omitempty"`
 	// Artifacts created by this phase.
 	Artifacts map[string]Artifact `json:"artifacts,omitempty"`
+	// DeferPhase is the phase that is executed at the end of an action
+	// irrespective of the status of other phases in the action
+	DeferPhase Phase `json:"deferPhase,omitempty"`
 }
 
 // State is the current state of a phase of execution.
@@ -194,6 +197,7 @@ type BlueprintAction struct {
 	InputArtifactNames []string            `json:"inputArtifactNames,omitempty"`
 	OutputArtifacts    map[string]Artifact `json:"outputArtifacts,omitempty"`
 	Phases             []BlueprintPhase    `json:"phases,omitempty"`
+	DeferPhase         *BlueprintPhase     `json:"deferPhase,omitempty"`
 }
 
 // BlueprintPhase is a an individual unit of execution.