RHDEVDOCS-5221: Overview of Pipelines

cicd/pipelines/understanding-openshift-pipelines.adoc

@@ -19,6 +19,9 @@ toc::[]
 * You can use {pipelines-title} to build images with Kubernetes tools such as Source-to-Image (S2I), Buildah, Buildpacks, and Kaniko that are portable across any Kubernetes platform.
 * You can use the {product-title} Developer console to create Tekton resources, view logs of pipeline runs, and manage pipelines in your {product-title} namespaces.
 
+//Brief overview
+include::modules/op-components.adoc[leveloffset=+1]
+
 [id="op-detailed-concepts"]
 == {pipelines-shortname} Concepts
 This guide provides a detailed view of the various pipeline concepts.

modules/op-components.adoc

@@ -0,0 +1,120 @@
+// This module is included in the following assembly:
+//
+// *openshift_pipelines/understanding-openshift-pipelines.adoc
+
+:_content-type: CONCEPT
+[id="op-components_{context}"]
+= Components of {pipelines-title}
+
+{pipelines-title} is a comprehensive solution for automating continuous integration and continuous delivery (CI/CD) processes, such as building, testing, and deploying code, in a cloud-native way.
+
+With {pipelines-shortname}, you can configure the automation of any CI/CD process as a set of building blocks by using custom OpenShift Container Platform resources and creating your components that run in containers and pods.
+
+There are several ways to create your blocks and to access reusable blocks.
+
+[id="op-overview-stepstaskspipelines_{context}"]
+== Steps, tasks, and pipelines
+
+The smallest block of the Pipelines CI/CD process is a _step_. A step is a single operation, such as running one or several unit tests for a Python web application or a Java program compilation. {pipelines-title} performs each step in a separate container.
+
+A _task_, represented by a `Task` resource, is a collection of steps, which always run in a fixed sequential order. {pipelines-title} runs all steps of a task as containers in the same pod. This pod provides an environment that enables steps to access shared resources. For example, you can mount a volume in a task, and each step of the task can access this volume.
+
+A _pipeline_, represented by a `Pipeline` resource, is a collection of tasks. You can arrange tasks in a pipeline in a flexible order so some tasks can run in parallel or sequentially, depending on the pipeline definition. You can also control the execution of tasks in a pipeline in various ways, for example, specify a condition for a task to proceed, define an automatic retry if a task fails, and so on.
+
+.Example diagram of steps and tasks in a pipeline
+image::338_OpenShift_Pipeline_0523.png[A diagram representing a pipeline. Task A runs first and includes three steps. When task A completes, task B and task C both start; each of these tasks has two steps. Task D starts when both task B and task C complete; this task has one step.]
+
+Typically, you configure a complete CI/CD process as a pipeline, while logical parts of this process become tasks.
+
+[id="op-overview-runs_{context}"]
+== Task runs and pipeline runs
+
+`PipelineRun` and `TaskRun` custom resources (CRs) represent individual runs of a pipeline or a task.
+
+{pipelines-shortname} automatically runs a pipeline when you create a `PipelineRun` custom resource referring to an existing pipeline. {pipelines-shortname} automatically runs a task when you create a `TaskRun` custom resource referring to an existing task.
+
+The `PipelineRun` resource sets the variable parameters that the pipeline has. The `TaskRun` resource sets the variable parameters that the task has.
+
+[id="op-overview-parameters_{context}"]
+== Task and pipeline parameters
+
+You can define _parameters_ in both tasks and pipelines.
+
+When creating a `Task` resource, you can define parameters of the task and use and use the values of these parameters in steps within the task. A `Pipeline` resource that uses this task or a `TaskRun` resource that runs this task must define the values for every parameter of the task.
+
+When creating a `Pipeline` resource, you can define parameters of the pipeline and use the values of these parameters in tasks within the pipeline. A `PipelineRun` resource that runs this pipeline must define the values for every parameter of the pipeline.
+
+[id="op-overview-triggers_{context}"]
+== Triggers
+
+You can manually create `PipelineRun` and `TaskRun` resources to run pipelines and tasks. Sometimes when certain events, such as a Git repository push happens, you can run a CI/CD pipeline automatically. {pipelines-shortname} provides triggers to support this functionality.
+
+The following components implement a trigger:
+
+* A `TriggerTemplate` CR specifies a blueprint for a `PipelineRun` or `TaskRun` resource, including the parameters that must be set for the pipeline or task.
+* A `TriggerBinding` CR  extracts the fields from an event payload and stores them as parameters that are defined by a `TriggerTemplate` resource.
+* A `Trigger` CR specifies a trigger template and a trigger binding.
+* An `EventListener` Kubernetes object is an addressable sink that runs in the cluster, listens for events as a Webhook on a specified port, and specifies one or more Triggers.
+
+When an `EventListener` object receives an event, {pipelines-shortname} automatically creates a `PipelineRun` or `TaskRun` resource based on the `TriggerTemplate` CR, setting the parameters from the event payload according to the `TriggerBinding` CR specification. The creation of this resource causes the pipeline or task to run.
+
+Optionally, you can define an `Interceptor` CR. An interceptor defines the logic that runs every time an event is received through the `EventListener` object, before this event is processed using a trigger. The interceptor can verify, filter, and modify events.
+
+[id="op-overview-catalog_{context}"]
+== Pipelines Catalog, {artifact-hub}, and {tekton-hub}
+
+A _Pipelines catalog_ is a repository of pipelines and tasks. You can download these pipelines and tasks and use them in your CI/CD processes.
+
+You can use the community-sourced Pipelines catalog indexed by the {artifact-hub} and {tekton-hub} projects.
+
+[id="op-overview-resolvers_{context}"]
+== Resolvers
+
+With _resolvers_, you can retrieve tasks and pipelines from a repository by using an identifier. You can reference a task or pipeline by using a resolver instead of defining the task or pipeline in your CRs. When the task or pipeline must be run, {pipelines-shortname} retrieves and runs the task or pipeline.
+
+{pipelines-shortname} includes the following resolvers:
+
+* _Hub resolver_: Retrieves a task or pipeline from the Pipelines Catalog available on the Artifact Hub or Tekton Hub.
+
+* _Bundles resolver_: Retrieves a task or pipeline from a Tekton bundle, which is an Open Container Initiative (OCI) image available from any OCI repository including an OpenShift image registry.
+
+* _Cluster resolver_: Retrieves a task or pipeline that is already created on the same OpenShift cluster in a specific namespace.
+
+* _Git resolver_: Retrieves a task or pipeline definition from a Git repository. You must specify the repository, the branch, and the path.
+
+[id="op-overview-clustertasks_{context}"]
+== Cluster tasks and cluster trigger bindings
+
+When you install {pipelines-shortname}, the installation creates a certain number of `ClusterTask` and `ClusterTriggerBinding` CRs. These resources represent pre-arranged tasks and trigger bindings that you can use in your pipelines.
+
+Cluster tasks and cluster trigger bindings are deprecated and will be removed in a future release. Instead, you can configure the hub resolver to access a wide array of reusable components.
+
+[id="op-overview-chains_{context}"]
+== {tekton-chains}: signed storage of runs for security audit
+
+Any automatic process involving data from repositories is a potential security issue, because a repository might be compromised.
+
+To monitor and mitigate any possible security issues, {pipelines-shortname} provides {tekton-chains}, a method of storing the entire content of every task run and pipeline run, including any data (such as mounted volumes) processed in the run. The stored information is signed by a key so that any tampering with the information is evident.
+
+You can use {tekton-chains} to set up security attestation for your CI/CD processes and to help implement the link:http://slsa.dev/[SLSA] guidelines.
+
+[id="op-overview-results_{context}"]
+== Tekton Results: access to execution data
+
+:FeatureName: Tekton Results
+include::snippets/technology-preview.adoc[]
+
+The full execution data of every task run and pipeline run, including run specs and logs, is stored in the `TaskRun` and `PipelineRun` CRs and can be signed and stored in a repository with {tekton-chains}. However, you might need to access these results in a more flexible manner to enable statistics and grouping. Also, `TaskRun` and `PipelineRun` resources can be pruned, while access to execution data and results might be required after the pruning.
+
+{pipelines-shortname} provides Tekton Results, which is an API and command line interface for querying execution and result data in a flexible way.
+
+[id="op-overview-pac_{context}"]
+== {pac}: running a pipeline from Git source
+
+With the {pac} functionality, you can define your CI/CD pipeline in your Git source code repository.
+
+Inside a directory in your source code, you define a template for the `PipelineRun` resource. This template includes the pipeline with all the necessary tasks. In addition, you register the repository with {pipelines-shortname} by using a CR and configure Git event notification using a webhook. If you use a GitHub repository, the {pac} installation routine can create a GitHub application for your repository that implements the notification.
+
+When events that you define in the template happen, {pipelines-shortname} runs the CI/CD pipeline defined in the source code.
+
+You can maintain this definition in your code repository, making changes as necessary, without any modification to {pipelines-shortname} resources.