Update Kanister docs with TemplateParams.Phases (#4136)

* Add TP.Phases to docs

* Minor formatting

* Minor change

docs/architecture.rst

@@ -197,19 +197,19 @@ state, and the overall execution progress.
   }
 
 Unlike in the ActionSpec, the Artifacts in the ActionStatus are the rendered
-output artifacts from the Blueprint. These are populated as soon as they are
-rendered, but should only be considered valid once the action is complete.
+output artifacts from the Blueprint. These are rendered and populated once the action is complete.
 
 
 Each phase in the ActionStatus phases list contains the phase name of the
-Blueprint phase and its state of execution.
+Blueprint phase along with its state of execution and output.
 
 .. code-block:: go
 
   // Phase is subcomponent of an action.
   type Phase struct {
-      Name  string `json:"name"`
-      State State  `json:"state"`
+      Name   string                 `json:"name"`
+      State  State                  `json:"state"`
+      Output map[string]interface{} `json:"output"`
   }
 
 .. _profiles:

docs/functions.rst

@@ -12,7 +12,7 @@ implements the following go interface:
   // Func allows custom actions to be executed.
   type Func interface {
       Name() string
-      Exec(ctx context.Context, args ...string) error
+      Exec(ctx context.Context, args ...string) (map[string]interface{}, error)
       RequiredArgs() []string
   }
 

docs/templates.rst

@@ -21,6 +21,7 @@ The TemplateParam struct is defined as:
       Secrets      map[string]v1.Secret
       Time         string
       Options      map[string]string
+      Phases       map[string]*Phase
   }
 
 Rendering Templates
@@ -497,3 +498,34 @@ The Options can then be used in the Blueprint via templating:
 
   "{{ .Options.podName }}"
 
+Phases
+------
+
+Phases are used to capture information required or returned from Blueprint phases.
+Currently, each phase contains a map of Secrets required to execute a phase,
+or the Output map returned from the execution.
+
+The definition is as follows:
+
+.. code-block:: go
+  :linenos:
+
+  type Phase struct {
+    Secrets map[string]v1.Secret
+    Output  map[string]interface{}
+  }
+
+The phase parameters can be referenced by the phases following it,
+or as output artifacts using templating.
+
+For example, an output artifact can reference the output from a phase as follows:
+
+.. code-block:: yaml
+
+"{{ .Phases.phase-name.Output.key-name }}"
+
+Similarly, a phase can use Secrets as arguments:
+
+.. code-block:: yaml
+
+"{{ .Phases.phase-name.Secrets.secret-name.Namespace }}"