OpenShift Pipelines Tutorial

Welcome to the OpenShift Pipelines tutorial!

OpenShift Pipelines is a cloud-native, continuous integration and delivery (CI/CD) solution for building pipelines using Tekton. Tekton is a flexible, Kubernetes-native, open-source CI/CD framework that enables automating deployments across multiple platforms (Kubernetes, serverless, VMs, etc) by abstracting away the underlying details.

OpenShift Pipelines features:

• Standard CI/CD pipeline definition based on Tekton
• Build images with Kubernetes tools such as S2I, Buildah, Buildpacks, Kaniko, etc
• Deploy applications to multiple platforms such as Kubernetes, serverless and VMs
• Easy to extend and integrate with existing tools
• Scale pipelines on-demand
• Portable across any Kubernetes platform
• Designed for microservices and decentralized teams
• Integrated with the OpenShift Developer Console

This tutorial walks you through pipeline concepts and how to create and run a simple pipeline for building and deploying a containerized app on OpenShift.

In this tutorial you will:

• Learn about Tekton concepts
• Install OpenShift Pipelines
• Deploy a Sample Application
• Install Tasks
• Create a Pipeline
• Trigger a Pipeline

Prerequisites

You need an OpenShift 4 cluster in order to complete this tutorial. If you don't have an existing cluster, go to http://try.openshift.com and register for free in order to get an OpenShift 4 cluster up and running on AWS within minutes.

You will also use the Tekton CLI (tkn) through out this tutorial. Download the Tekton CLI by following instructions available on the CLI GitHub repository.

Concepts

Tekton defines a number of Kubernetes custom resources as building blocks in order to standardize pipeline concepts and provide a terminology that is consistent across CI/CD solutions. These custom resources are an extension of the Kubernetes API that let users create and interact with these objects using kubectl and other Kubernetes tools.

The custom resources needed to define a pipeline are listed below:

• Task: a reusable, loosely coupled number of steps that perform a specific task (e.g. building a container image)
• Pipeline: the definition of the pipeline and the Tasks that it should perform
• PipelineResource: inputs (e.g. git repository) and outputs (e.g. image registry) to and out of a pipeline or task
• TaskRun: the execution and result of running an instance of task
• PipelineRun: the execution and result of running an instance of pipeline, which includes a number of TaskRuns

In short, in order to create a pipeline, one does the following:

• Create custom or install existing reusable Tasks
• Create a Pipeline and PipelineResources to define your application's delivery pipeline
• Create a PipelineRun to instantiate and invoke the pipeline

For further details on pipeline concepts, refer to the Tekton documentation that provides an excellent guide for understanding various parameters and attributes available for defining pipelines.

In the following sections, you will go through each of the above steps to define and invoke a pipeline.

Install OpenShift Pipelines

OpenShift Pipelines is provided as an add-on on top of OpenShift that can be installed via an operator available in the OpenShift OperatorHub. Follow these instructions in order to install OpenShift Pipelines on OpenShift via the OperatorHub.

Deploy Sample Application

Create a project for the sample application that you will be using in this tutorial:

$ oc new-project pipelines-tutorial

OpenShift Pipelines automatically adds and configures a ServiceAccount named pipeline that has sufficient permissions to build and push an image. This service account will be used later in the tutorial.

Run the following command to see the pipeline service account:

$ oc get serviceaccount pipeline

You will use the Spring PetClinic sample application during this tutorial, which is a simple Spring Boot application.

Create the Kubernetes objects for deploying the PetClinic app on OpenShift. The deployment will not complete since there are no container images built for the PetClinic application yet. That you will do in the following sections through a CI/CD pipeline:

$ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/master/petclinic/manifests.yaml

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.

On the Topology view of the Developer perspective, you will be able to see the resources you just created.

Install Tasks

Tasks consist of a number of steps that are executed sequentially. Each task is executed in a separate container within the same pod. They can also have inputs and outputs in order to interact with other tasks in the pipeline.

Here is an example of a Maven task for building a Maven-based Java application:

apiVersion: tekton.dev/v1alpha1
kind: Task
metadata:
  name: maven-build
spec:
  inputs:
    resources:
    - name: workspace-git
      targetPath: /
      type: git
  steps:
  - name: build
    image: maven:3.6.0-jdk-8-slim
    command:
    - /usr/bin/mvn
    args:
    - install

When a task starts running, it starts a pod and runs each step sequentially in a separate container on the same pod. This task happens to have a single step, but tasks can have multiple steps, and, since they run within the same pod, they have access to the same volumes in order to cache files, access configmaps, secrets, etc. As mentioned previously, tasks can receive inputs (e.g. a git repository) and produce outputs (e.g. an image in a registry).

Note that only the requirement for a git repository is declared on the task and not a specific git repository to be used. That allows tasks to be reusable for multiple pipelines and purposes. You can find more examples of reusable tasks in the Tekton Catalog and OpenShift Catalog repositories.

Install the openshift-client and s2i-java tasks from the catalog repository using oc or kubectl, which you will need for creating a pipeline in the next section:

$ oc create -f https://raw.githubusercontent.com/openshift/tektoncd-catalog/release-v0.7/openshift-client/openshift-client-task.yaml
$ oc create -f https://raw.githubusercontent.com/openshift/pipelines-catalog/release-v0.7/s2i-java-8/s2i-java-8-task.yaml

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

$ tkn task ls

NAME               AGE
openshift-client   58 seconds ago
s2i-java-8         1 minute ago

Create Pipeline

A pipeline defines a number of tasks that should be executed and how they interact with each other via their inputs and outputs.

In this tutorial, you will create a pipeline that takes the source code of the PetClinic application from GitHub and then builds and deploys it on OpenShift using Source-to-Image (S2I).

Here is the YAML file that represents the above pipeline:

apiVersion: tekton.dev/v1alpha1
kind: Pipeline
metadata:
  name: petclinic-deploy-pipeline
spec:
  resources:
  - name: app-git
    type: git
  - name: app-image
    type: image
  tasks:
  - name: build
    taskRef:
      name: s2i-java-8
    params:
      - name: TLSVERIFY
        value: "false"
    resources:
      inputs:
      - name: source
        resource: app-git
      outputs:
      - name: image
        resource: app-image
  - name: deploy
    taskRef:
      name: openshift-client
    runAfter:
      - build
    params:
    - name: ARGS
      value:
        - rollout
        - latest
        - spring-petclinic

This pipeline performs the following:

1. Clones the source code of the application from a git repository (app-git resource)
2. Builds the container image using the s2i-java-8 task that generates a Dockerfile for the application and uses Buildah to build the image
3. The application image is pushed to an image registry (app-image resource)
4. The new application image is deployed on OpenShift using the openshift-cli

You might have noticed that there are no references to the PetClinic git repository or the image registry it will be pushed to. That's because pipeline in Tekton are 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. When triggering a pipeline, you can provide different git repositories and image registries to be used during pipeline execution. Be patient! You will do that in a little bit in the next section.

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.

Create the pipeline by running the following:

$ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/master/pipeline/01-build-deploy.yaml

Alternatively, in the OpenShift web console, you can click on the + at the top right of the screen while you are in the pipelines-tutorial project:

Paste the YAML into the text editor and click on Create:

Upon creating the pipeline via the web console, you will be taken to a Pipeline Details page that gives an overview of the pipeline you created:

Check the list of pipelines you have created using the CLI:

$ tkn pipeline ls

NAME                       AGE              LAST RUN   STARTED   DURATION   STATUS
petclinic-deploy-pipeline  25 seconds ago   ---        ---       ---        ---

Trigger Pipeline

Now that the pipeline is created, you can trigger it to execute the tasks specified in the pipeline.

First, you should create a number of PipelineResources that contain the specifics of the git repository and image registry to be used in the pipeline during execution. Expectedly, these are also reusable across multiple pipelines.

The following PipelineResource defines the git repository for the PetClinic application:

apiVersion: tekton.dev/v1alpha1
kind: PipelineResource
metadata:
  name: petclinic-git
spec:
  type: git
  params:
  - name: url
    value: https://github.com/spring-projects/spring-petclinic

And the following defines the OpenShift internal image registry for the PetClinic image to be pushed to:

apiVersion: tekton.dev/v1alpha1
kind: PipelineResource
metadata:
  name: petclinic-image
spec:
  type: image
  params:
  - name: url
    value: image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/spring-petclinic

Create the above pipeline resources via the OpenShift web console or by running the following:

$ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/master/pipeline/02-resources.yaml

You can see the list of resources created using tkn:

$ tkn resource ls

NAME              TYPE    DETAILS
petclinic-git     git     url: https://github.com/spring-projects/spring-petclinic
petclinic-image   image   url: image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/spring-petclinic

A PipelineRun is how you can start a pipeline and tie it to the git and image resources that should be used for this specific invocation. You can start the pipeline using tkn:

$ tkn pipeline start petclinic-deploy-pipeline \
        -r app-git=petclinic-git \
        -r app-image=petclinic-image \
        -s pipeline

The -r flag specifies the pipeline resources that should be provided to the pipeline, and the -s flag specifies the service account to be used for running the pipeline.

Note: OpenShift Pipelines 0.7 does not automatically use the pipeline service account for running pipelineruns. This has been fixed in the next release (OpenShift Pipelines 0.8), but if you want to use the OpenShift web console developer perspective to start the pipeline with OpenShift Pipelines 0.7, run the following commands to elevate the permissions of the default service account, which is currently used by default for running pipelineruns that are started by the OpenShift Console:

$ oc adm policy add-role-to-user edit -z default

As soon as you start the petclinic-deploy-pipeline pipeline, a pipelinerun will be instantiated and pods will be created to execute the tasks that are defined in the pipeline.

$ tkn pipeline list
NAME                        AGE             LAST RUN                              STARTED         DURATION   STATUS
petclinic-deploy-pipeline   23 seconds ago   petclinic-deploy-pipeline-run-tsv92  23 seconds ago   ---        Running

Check out the logs of the pipelinerun as it runs using the tkn pipeline logs command which interactively allows you to pick the pipelinerun of your interest and inspect the logs:

$ tkn pipeline logs -f
? Select pipeline : petclinic-deploy-pipeline
? Select pipelinerun : petclinic-deploy-pipeline-run-tsv92 started 39 seconds ago

After a few minutes, the pipeline should finish successfully.

$ tkn pipeline list

NAME                        AGE             LAST RUN                              STARTED         DURATION    STATUS
petclinic-deploy-pipeline   7 minutes ago   petclinic-deploy-pipeline-run-tsv92   7 minutes ago   7 minutes   Succeeded

Looking back at the project, you should see that the PetClinic image is successfully built and deployed.

If you want to re-run the pipeline again, you can use the following short-hand command to rerun the last pipelinerun again that uses the same pipeline resources and service account used in the previous pipeline run:

tkn pipeline start petclinic-deploy-pipeline --last