For this tutorial, you're going to create a simple application that involves a frontend and backend. This application needs to deploy in a new project (i.e. Kubernetes namespace). You can start by creating the project with:

oc new-project pipelines-tutorial

You can also deploy the same applications by applying the artifacts available in k8s directory of the respective repo.

Deploying through Web Console

If you deploy the application directly, you should be able to see the deployment in the OpenShift Web Console by switching over to the Developer perspective of the OpenShift Web Console. Change from Administrator to Developer from the drop-down as shown below:

Make sure you are on the pipelines-tutorial project by selecting it from the Project dropdown menu. Either search for pipelines-tutorial in the search bar or scroll down until you find pipelines-tutorial and click on the name of your project.

Next, we'll work on creating a sample Task that outputs to the console!

A Task defines a series of steps that run in a desired order and complete a set amount of build work. Every Task runs as a Pod on your Kubernetes cluster with each step as its own container. For example, the following Task outputs "Hello World":

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: hello
spec:
  steps:
    - name: say-hello
      image: registry.access.redhat.com/ubi8/ubi
      command:
        - /bin/bash
      args: ['-c', 'echo Hello World']

Apply this Task to your cluster just like any other Kubernetes object. Then run it using tkn, the CLI tool for Tekton.

oc apply -f tasks/hello.yaml

tkn task start --showlog hello

The output will look similar to the following:

TaskRun started: hello-run-9cp8x
Waiting for logs to be available...
[say-hello] Hello World

In the next section, you will examine the task definitions that will be needed for our pipeline.

Tasks can also take parameters. This way, you can pass various flags to be used in this Task. These params can be instrumental in making your Tasks more generic and reusable across Pipelines. For example, a Task could apply a custom Kubernetes manifest, like the example below. This will be needed for deploying an image on OpenShift in our next section. In addition, we'll cover the workspaces during our Pipeline step.

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: apply-manifests
spec:
  workspaces:
  - name: source
  params:
    - name: manifest_dir
      description: The directory in source that contains yaml manifests
      type: string
      default: "k8s"
  steps:
    - name: apply
      image: quay.io/openshift/origin-cli:latest
      workingDir: /workspace/source
      command: ["/bin/bash", "-c"]
      args:
        - |-
          echo Applying manifests in $(inputs.params.manifest_dir) directory
          oc apply -f $(inputs.params.manifest_dir)
          echo -----------------------------------

Create the apply-manifests task:

oc create -f tasks/apply_manifest_task.yaml

We'll also create a update-deployment task, which can be seen with a cat command:

oc create -f tasks/update_deployment_task.yaml

Finally, we can create a PersistentVolumeClaim to provide the filesystem for our pipeline execution, explained more in the next step:

oc create -f resources/persistent_volume_claim.yaml

You can take a look at the tasks you created using the Tekton CLI:

tkn task ls

You should see similar output to this:

NAME                DESCRIPTION   AGE
apply-manifests                   4 seconds ago
hello                             1 minute ago
update-deployment                 3 seconds ago

In the next section, you will create a pipeline that takes the source code of an application from GitHub and then builds and deploys it on OpenShift.

A Pipeline defines an ordered series of Tasks that you want to execute along with the corresponding inputs and outputs for each Task. In fact, tasks should do one single thing so you can reuse them across pipelines or even within a single pipeline.

Below is an example definition of a Pipeline, created using the following diagram:

Below is a YAML file that represents the above pipeline:

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: build-and-deploy
spec:
  workspaces:
  - name: shared-workspace
  params:
  - name: deployment-name
    type: string
    description: name of the deployment to be patched
  - name: git-url
    type: string
    description: url of the git repo for the code of deployment
  - name: git-revision
    type: string
    description: revision to be used from repo of the code for deployment
    default: "master"
  - name: IMAGE
    type: string
    description: image to be build from the code
  tasks:
  - name: fetch-repository
    taskRef:
      name: git-clone
      kind: ClusterTask
    workspaces:
    - name: output
      workspace: shared-workspace
    params:
    - name: url
      value: $(params.git-url)
    - name: subdirectory
      value: ""
    - name: deleteExisting
      value: "true"
    - name: revision
      value: $(params.git-revision)
  - name: build-image
    taskRef:
      name: buildah
      kind: ClusterTask
    params:
    - name: TLSVERIFY
      value: "false"
    - name: IMAGE
      value: $(params.IMAGE)
    workspaces:
    - name: source
      workspace: shared-workspace
    runAfter:
    - fetch-repository
  - name: apply-manifests
    taskRef:
      name: apply-manifests
    workspaces:
    - name: source
      workspace: shared-workspace
    runAfter:
    - build-image
  - name: update-deployment
    taskRef:
      name: update-deployment
    workspaces:
    - name: source
      workspace: shared-workspace
    params:
    - name: deployment
      value: $(params.deployment-name)
    - name: IMAGE
      value: $(params.IMAGE)
    runAfter:
    - apply-manifests

This pipeline helps you to build and deploy backend/frontend, by configuring the right resources to the pipeline.

Pipeline Steps:

1. fetch-repository clones the source code of the application from a git repository by referring (git-url and git-revision param)
2. build-image builds the container image of the application using the buildah clustertask that uses Buildah to build the image
3. The application image is pushed to an image registry by referring (image param)
4. The new application image is deployed on OpenShift using the apply-manifests and update-deployment tasks

You might have noticed that there are no references to the git repository or the image registry it will be pushed to in the pipeline. That's because pipeline in Tekton is designed to be generic and re-usable across environments and stages through the application's lifecycle. Pipelines abstract away the specifics of the git source repository and image to be produced as PipelineResources or Params. When triggering a pipeline, you can provide different git repositories and image registries to be used during pipeline execution.

The execution order of task is determined by dependencies that are defined between the tasks via inputs and outputs as well as explicit orders that are defined via runAfter.

workspaces field allows you to specify one or more volumes that each Task in the Pipeline requires during execution. You specify one or more Workspaces in the workspaces field.

Create the pipeline by running the following:

oc create -f pipeline/pipeline.yaml

In the next section, you will focus on creating a trigger to execute the tasks specified in the pipeline.

Now that the pipeline is created, you can trigger it to execute the tasks specified in the pipeline. This is done by creating a PipelineRun via tkn.

Trigger a Pipeline via CLI

Let's start a pipeline to build and deploy our backend application using tkn. By creating a PipelineRun with the name of our applied Pipeline, we can define various arguments to our command like params that will be used in the Pipeline. For example, we can apply a request for storage with a persistentVolumeClaim, as well as define a name for our deployment, git-url repository to be cloned, and IMAGE to be created.

We'll first build and deploy our backend application using the following command, with the params already included for our specific demo:

tkn pipeline start build-and-deploy -w name=shared-workspace,claimName=source-pvc -p deployment-name=pipelines-vote-api -p git-url=https://github.com/openshift/pipelines-vote-api.git -p IMAGE=image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/vote-api --showlog

Similarly, start a pipeline to build and deploy the frontend application:

tkn pipeline start build-and-deploy -w name=shared-workspace,claimName=source-pvc -p deployment-name=pipelines-vote-ui -p git-url=https://github.com/openshift/pipelines-vote-ui.git -p IMAGE=image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/vote-ui --showlog

As soon as you start the build-and-deploy pipeline, a PipelineRun will be instantiated and pods will be created to execute the tasks that are defined in the pipeline. To display a list of Pipelines, use the following command:

tkn pipeline ls

Again, notice the reusability of pipelines, and how one generic Pipeline can be triggered with various params. We've started the build-and-deploy pipeline, with relevant pipeline resources to deploy backend/frontend application using a single pipeline. Let's list our PipelineRuns:

tkn pipelinerun ls

After a few minutes, the pipeline should finish successfully!

tkn pipelinerun ls

Access Pipeline via Web Console

To view the PipelineRun visually, visit the Pipelines section of the developer perspective. From here, you can see the details of our Pipeline, including the YAML file we've applied, the PipelineRun, input custom params, and more:

Congrats! Your Pipeline has successfully ran, and the final step will provide instructions on how to access the deployed image.

To verify a successful deployment for our application, head back out to the web console by clicking on the Console at the center top of the workshop in your browser.

Click on the Topology tab on the left side of the web console. You should see something similar to what is shown in the screenshot below:

The Topology view of the OpenShift web console helps to show what is deployed out to your OpenShift project visually. As mentioned earlier, the dark blue lining around the ui circle means that a container has started up and running the api application. By clicking on the arrow icon as shown below, you can open the URL for ui in a new tab and see the application running.

After clicking on the icon, you should see the application running in a new tab.

Accessing application via CLI

In addition, you can get the route of the application by executing the following command to access the application.

oc get route pipelines-vote-ui --template='http://{{.spec.host}}'

Congratulations! You have successfully deployed your first application using OpenShift Pipelines.