[enterprise-4.9] RHDEVDOCS-2836: Document on when expressions and final tasks of the finally section for Pipelines 1.5

cicd/pipelines/understanding-openshift-pipelines.adoc

@@ -25,6 +25,10 @@ This guide provides a detailed view of the various pipeline concepts.
 
 //About tasks
 include::modules/op-about-tasks.adoc[leveloffset=+2]
+//About when expression
+include::modules/op-about-whenexpression.adoc[leveloffset=+2]
+//About final tasks
+include::modules/op-about-finally_tasks.adoc[leveloffset=+2]
 //About task run
 include::modules/op-about-taskrun.adoc[leveloffset=+2]
 //About pipelines

modules/op-about-finally_tasks.adoc

@@ -0,0 +1,64 @@
+// This module is included in the following assembly:
+//
+// *openshift_pipelines/understanding-openshift-pipelines.adoc
+
+[id="about-finally_tasks_{context}"]
+= Finally tasks
+
+The `finally` tasks are the final set of tasks specified using the `finally` field in the pipeline YAML file. A `finally` task always executes the tasks within the pipeline, irrespective of whether the pipeline runs are executed successfully. The `finally` tasks are executed in parallel after all the pipeline tasks are run, before the corresponding pipeline exits.
+
+You can configure a `finally` task to consume the results of any task within the same pipeline. This approach does not change the order in which this final task is run. It is executed in parallel with other final tasks after all the non-final tasks are executed.
+
+The following example shows a code snippet of the `clone-cleanup-workspace` pipeline. This code clones the repository into a shared workspace and cleans up the workspace. After executing the pipeline tasks, the `cleanup` task specified in the `finally` section of the pipeline YAML file cleans up the workspace.
+
+[source,yaml]
+----
+apiVersion: tekton.dev/v1beta1
+kind: Pipeline
+metadata:
+  name: clone-cleanup-workspace <1>
+spec:
+  workspaces:
+    - name: git-source <2>
+  tasks:
+    - name: clone-app-repo <3>
+      taskRef:
+        name: git-clone-from-catalog
+      params:
+        - name: url
+          value: https://github.com/tektoncd/community.git
+        - name: subdirectory
+          value: application
+      workspaces:
+        - name: output
+          workspace: git-source
+  finally:
+    - name: cleanup <4>
+      taskRef: <5>
+        name: cleanup-workspace 
+      workspaces: <6>
+        - name: source
+          workspace: git-source
+    - name: check-git-commit
+      params: <7>
+        - name: commit
+          value: $(tasks.clone-app-repo.results.commit)
+      taskSpec: <8>
+        params:
+          - name: commit
+        steps:
+          - name: check-commit-initialized
+            image: alpine
+            script: |
+              if [[ ! $(params.commit) ]]; then
+                exit 1
+              fi
+----
+<1> Unique name of the Pipeline.
+<2> The shared workspace where the git repository is cloned.
+<3> The task to clone the application repository to the shared workspace.
+<4> The task to clean-up the shared workspace.
+<5> A reference to the task that is to be executed in the TaskRun.
+<6> A shared storage volume that a Task in a Pipeline needs at runtime to receive input or provide output.
+<7> A list of parameters required for a task. If a parameter does not have an implicit default value, you must explicitly set its value.
+<8> Embedded task definition.

modules/op-about-whenexpression.adoc

@@ -0,0 +1,155 @@
+// This module is included in the following assembly:
+//
+// *openshift_pipelines/understanding-openshift-pipelines.adoc
+
+[id="about-whenexpression_{context}"]
+= When expression
+
+When expressions guard task execution by setting criteria for the execution of tasks within a pipeline. They contain a list of components that allows a task to run only when certain criteria are met. When expressions are also supported in the final set of tasks that are specified using the `finally` field in the pipeline YAML file.
+
+The key components of a when expression are as follows:
+
+* `input`: Specifies static inputs or variables such as a parameter, task result, and execution status. You must enter a valid input. If you do not enter a valid input, its value defaults to an empty string.
+* `operator`: Specifies the relationship of an input to a set of `values`. Enter `in` or `notin` as your operator values.
+* `values`: Specifies an array of string values. Enter a non-empty array of static values or variables such as parameters, results, and a bound state of a workspace.
+
+The declared when expressions are evaluated before the task is run. If the value of a when expression is `True`, the task is run. If the value of a when expression is `False`, the task is skipped.
+
+You can use the when expressions in various use cases. For example, whether:
+
+* The result of a previous task is as expected.
+* A file in a Git repository has changed in the previous commits.
+* An image exists in the registry.
+* An optional workspace is available.
+
+The following example shows the when expressions for a pipeline run. The pipeline run will execute the `create-file` task only if the following criteria are met: the `path` parameter is `README.md`,  and the `echo-file-exists` task executed only if the `exists` result from the `check-file` task is `yes`.
+
+[source,yaml]
+----
+apiVersion: tekton.dev/v1beta1
+kind: PipelineRun <1>
+metadata:
+  generateName: guarded-pr-
+spec:
+  serviceAccountName: 'pipeline'
+  pipelineSpec:
+    params:
+      - name: path
+        type: string
+        description: The path of the file to be created
+    workspaces:
+      - name: source
+        description: |
+          This workspace is shared among all the pipeline tasks to read/write common resources
+    tasks:
+      - name: create-file <2>
+        when:
+          - input: "$(params.path)"
+            operator: in
+            values: ["README.md"]
+        workspaces:
+          - name: source
+            workspace: source
+        taskSpec:
+          workspaces:
+            - name: source
+              description: The workspace to create the readme file in
+          steps:
+            - name: write-new-stuff
+              image: ubuntu
+              script: 'touch $(workspaces.source.path)/README.md'
+      - name: check-file
+        params:
+          - name: path
+            value: "$(params.path)"
+        workspaces:
+          - name: source
+            workspace: source
+        runAfter:
+          - create-file
+        taskSpec:
+          params:
+            - name: path
+          workspaces:
+            - name: source
+              description: The workspace to check for the file
+          results:
+            - name: exists
+              description: indicates whether the file exists or is missing
+          steps:
+            - name: check-file
+              image: alpine
+              script: |
+                if test -f $(workspaces.source.path)/$(params.path); then
+                  printf yes | tee /tekton/results/exists
+                else
+                  printf no | tee /tekton/results/exists
+                fi
+      - name: echo-file-exists
+        when: <3>
+          - input: "$(tasks.check-file.results.exists)"
+            operator: in
+            values: ["yes"]
+        taskSpec:
+          steps:
+            - name: echo
+              image: ubuntu
+              script: 'echo file exists'
+...
+      - name: task-should-be-skipped-1
+        when: <4>
+          - input: "$(params.path)"
+            operator: notin
+            values: ["README.md"]
+        taskSpec:
+          steps:
+            - name: echo
+              image: ubuntu
+              script: exit 1
+...
+    finally:
+      - name: finally-task-should-be-executed
+        when: <5>
+          - input: "$(tasks.echo-file-exists.status)"
+            operator: in
+            values: ["Succeeded"]
+          - input: "$(tasks.status)"
+            operator: in
+            values: ["Succeeded"]
+          - input: "$(tasks.check-file.results.exists)"
+            operator: in
+            values: ["yes"]
+          - input: "$(params.path)"
+            operator: in
+            values: ["README.md"]
+        taskSpec:
+          steps:
+            - name: echo
+              image: ubuntu
+              script: 'echo finally done'
+  params:
+    - name: path
+      value: README.md
+  workspaces:
+    - name: source
+      volumeClaimTemplate:
+        spec:
+          accessModes:
+            - ReadWriteOnce
+          resources:
+            requests:
+              storage: 16Mi
+----
+<1> Specifies the type of Kubernetes object. In this example, `PipelineRun`.
+<2> Task `create-file` used in the Pipeline.
+<3> `when` expression that specifies to execute the `echo-file-exists` task only if the `exists` result from the `check-file` task is `yes`.
+<4> `when` expression that specifies to skip the `task-should-be-skipped-1` task only if the `path` parameter is `README.md`.
+<5> `when` expression that specifies to execute the `finally-task-should-be-executed` task only if the execution status of the `echo-file-exists` task and the task status is `Succeeded`, the `exists` result from the `check-file` task is `yes`, and the `path` parameter is `README.md`.
+
+The *Pipeline Run details* page of the {product-title} web console shows the status of the tasks and when expressions as follows:
+
+* All the criteria are met: Tasks and the when expression symbol, which is represented by a diamond shape are green.
+* Any one of the criteria are not met: Task is skipped. Skipped tasks and the when expression symbol are grey.
+* None of the criteria are met: Task is skipped. Skipped tasks and the when expression symbol are grey.
+* Task run fails: Failed tasks and the when expression symbol are red.
+

modules/op-interacting-with-pipelines-using-the-developer-perspective.adoc

@@ -16,28 +16,40 @@ The *Pipelines* view in the *Developer* perspective lists all the pipelines in a
 [Discrete]
 .Procedure
 . In the *Pipelines* view of the *Developer* perspective, select a project from the *Project* drop-down list to see the pipelines in that project.
-. Click the required pipeline to see the *Pipeline details* page. By default, the *Details* tab opens and provides a visual representation of all the serial and parallel tasks in the pipeline. The tasks are also listed in the lower right portion of the page. You can click the listed *Tasks* to view the task details.
+. Click the required pipeline to see the *Pipeline details* page.
++
+By default, the *Details* tab displays a visual representation of all the all the serial tasks, parallel tasks, `finally` tasks, and when expressions in the pipeline. The tasks and the `finally` tasks are listed in the lower right portion of the page. Click the listed *Tasks* and *Finally tasks* to view the task details.
 +
 .Pipeline details
 image::op-pipeline-details.png[Pipeline details]
 +
-. Optional: In the *Pipeline details* page:
-* Click the *Metrics* tab to see the following information about pipelines:
+. Optional: On the *Pipeline details* page, click the *Metrics* tab to see the following information about pipelines:
 ** *Pipeline Success Ratio*
 ** *Number of Pipeline Runs*
 ** *Pipeline Run Duration*
 ** *Task Run Duration*
 +
 You can use this information to improve the pipeline workflow and eliminate issues early in the pipeline lifecycle.
 +
-* Click the *YAML* tab to edit the YAML file for the pipeline.
-* Click the *Pipeline Runs* tab to see the completed, running, or failed runs for the pipeline.
+. Optional: Click the *YAML* tab to edit the YAML file for the pipeline.
+. Optional: Click the *Pipeline Runs* tab to see the completed, running, or failed runs for the pipeline.
++
+The *Pipeline Runs* tab provides details about the pipeline run, the status of the task, and a link to debug failed pipeline runs. Use the Options menu {kebab} to stop a running pipeline, to rerun a pipeline using the same parameters and resources as that of the previous pipeline execution, or to delete a pipeline run.
++
+* Click the required pipeline run to see the *Pipeline Run details* page. By default, the *Details* tab displays a visual representation of all the serial tasks, parallel tasks, `finally` tasks, and when expressions in the pipeline run. The results for successful runs are displayed under the *Pipeline Run results* pane at the bottom of the page.
 +
 [NOTE]
 ====
 The *Details* section of the *Pipeline Run Details* page displays a *Log Snippet* of the failed pipeline run. *Log Snippet* provides a general error message and a snippet of the log. A link to the *Logs* section provides quick access to the details about the failed run.
-The *Log Snippet* is also displayed in the *Details* section of the *Task Run Details* page.
 ====
-You can use the Options menu {kebab} to stop a running pipeline, to rerun a pipeline using the same parameters and resources as that of the previous pipeline execution, or to delete a pipeline run.
-* Click the *Parameters* tab to see the parameters defined in the pipeline. You can also add or edit additional parameters, as required.
-* Click the *Resources* tab to see the resources defined in the pipeline. You can also add or edit additional resources, as required.
+* On the *Pipeline Run details* page, click the *Task Runs* tab to see the completed, running, and failed runs for the task.
++
+The *Task Runs* tab provides information about the task run along with the links to its task and pod, and also the status and duration of the task run. Use the Options menu {kebab} to delete a task run.
+* Click the required task run to see the *Task Run details* page. The results for successful runs are displayed under the *Task Run results* pane at the bottom of the page.
++
+[NOTE]
+====
+The *Details* section of the *Task Run details* page displays a *Log Snippet* of the failed task run. *Log Snippet* provides a general error message and a snippet of the log. A link to the *Logs* section provides quick access to the details about the failed task run.
+====
+. Click the *Parameters* tab to see the parameters defined in the pipeline. You can also add or edit additional parameters, as required.
+. Click the *Resources* tab to see the resources defined in the pipeline. You can also add or edit additional resources, as required.