Using Pipelines

The following section demonstrates how to trigger and run pipelines as well as to check on the application status.

Deploying an application to OpenShift

Prerequisites

  • You have installed OpenShift Pipelines using the OpenShift Pipeline Operator listed in the OpenShift OperatorHub. Once installed, it is applicable to the entire cluster.

  • You have installed the Tekton CLI

  • You have installed CodeReady Containers (CRC) - a recommended solution for quick deployment of OpenShift clusters locally. For more information read the documentation for CRC.

Procedure

  1. Create a local CRC virtual machine:

    $ crc start
    If you use a hosted hypervisor, see the CRC documentation.

    crc start output contains user login and password needed for logging into the cluster.

  2. Add the cached oc binary to your PATH:

    1. Run the crc oc-env command to print the command needed to add the cached oc binary to your PATH:

      $ crc oc-env
    2. Run the printed command.

  3. Log into the OpenShift cluster with the provided login and password:

    $ oc login -u <login> -p <password> https://api.crc.testing:6443
  4. Create a project for the sample application:

    $ oc new-project pipelines-tutorial
  5. Create the Kubernetes objects for deploying the PetClinic application on OpenShift:

    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/master/petclinic/manifests.yaml
  6. Navigate to HomeProjectsStatus in the OpenShift Web Console to verify the deployment. The deployment at this stage is not complete. The Pipeline you create in the next steps builds the container images for the PetClinic application and completes the deployment.

    Initiate deployment

Defining and creating pipeline tasks

Tasks are the building blocks of a Pipeline and consist of sequentially executed steps. steps are a series of commands that achieve a specific goal, for example, build an image.

Every Task runs as a pod and each step runs in its own container within the same pod. Since they run within the same pod they have access to the same volumes to cache files, configmaps, and secrets. They use inputs parameters, for example, a git , and outputs parameters, for example, an image in a registry, to interact with other tasks.

Tasks are reusable and can be used in multiple Pipeline s. For this tutorial, you create a Maven Task with a single step to build a Maven based application, and then add two reusable Tasks from the catalog repository.

Procedure

  1. To create the Maven Task:

    1. Copy the contents of the following sample Task YAML file and save it:

      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

      This Task starts a pod and runs a container inside that pod using the maven:3.6.0-jdk-8-slim image to run the specified commands. It receives an input directory called workspace-git which contains the source code of the application.

      Only the requirement for a git repository is declared on the Task and not a specific git repository to be used. This allows Tasks to be reusable for multiple Pipeline s and purposes.

    2. Create the Task within your project:

      oc create -f maven-build-task.yaml
  2. Install the s2i-java and openshift-client reusable Tasks from the catalog repository, which contains a list of reusable Tasks for Pipeline s:

    $ 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
  3. Verify the Tasks added to the Pipeline as follows:

    $ tkn task ls
    
    NAME              AGE
    maven-build       23 secs ago
    openshift-client  10 secs ago
    s2i-java          11 secs ago

Additional resources

Defining and creating pipeline resources

PipelineResources are artifacts that are used as inputs to a Task and can be output by a Task.

Procedure

After you create Task s, create PipelineResources that contain the specifics of the Git repository and the image registry to be used in the Pipeline during execution as follows:

  1. Create a PipelineResource YAML file with a PipelineResource that defines the Git repository and reference for the PetClinic application as follows:

    apiVersion: tekton.dev/v1alpha1
    kind: PipelineResource
    metadata:
      name: petclinic-git
    spec:
      type: git
      params:
      - name: url
        value: https://github.com/spring-projects/spring-petclinic
  2. Add another PipelineResource, which defines the OpenShift internal registry to which you want to push the PetClinic image, to the YAML file as shown below, and save it.

    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
  3. Create the above pipeline resources as follows:

    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/master/pipeline/02-resources.yaml
  4. Verify the resources created as follows:

    $ 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

Assembling a pipeline

A Pipeline represents a CI/CD flow and is defined by the Tasks to be executed. It specifies how the Tasks interact with each other and their order of execution using the inputs , outputs, and the run-After parameters. It is designed to be generic and reusable in multiple applications and environments.

For this tutorial, we create a Pipeline that takes the source code of the Spring PetClinic application from GitHub, builds the application, and deploys it on OpenShift as outlined below:

Pipeline

Procedure

  1. Copy the contents of the following sample Pipeline YAML file and save it:

    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 tasks:

    • Clones the source code of the application from a Git repository (app-git resource).

    • Builds the container image using the S2I task which generates a Dockerfile for the application and uses Buildah to build an image.

    • The application image is then pushed to an image registry (app-image resource).

    • The new application image is deployed on OpenShift using the OpenShift-CLI.

      Note that, the Pipeline YAML file contains no references to the PetClinic Git repository and its image in the registry. These are defined in the PipelineResources.

      Pipeline s in Tekton are designed to be generic and re-usable across environments and stages through the applications lifecycle. They abstract away the specifics of the Git source repository and image registries to be used during Pipeline execution.

      The execution order of the tasks is determined by the dependencies defined between the tasks using the inputs and outputs parameters, and the explicit orders that are defined using runAfter.

  2. Create the Pipeline:

    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/master/pipeline/01-build-deploy.yaml
  3. Verify that the Pipeline has been added to the application as follows:

    $ tkn pipeline ls
    
    NAME             AGE             LAST RUN   STARTED   DURATION   STATUS
    deploy-pipeline   8 seconds ago   ---        ---       ---        ---

Triggering and running a pipeline

A PipelineRun starts a Pipeline and ties it to the Git and image resources that should be used for the specific invocation.

Procedure

  1. Start the Pipeline as follows:

    $ tkn pipeline start petclinic-deploy-pipeline \
            -r app-git=petclinic-git \
            -r app-image=petclinic-image \
            -s pipeline
    
    Pipelinerun started: petclinic-deploy-pipeline-run-q62p8
    • The -r flag specifies the PipelineResource s that should be provided to the pipeline

    • 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 OpenShift Pipelines 0.8 release. If you want to use the OpenShift 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 used for running pipelineruns that are started by the OpenShift Console, as follows:

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

      Starting a pipeline instantiates the PipelineRun and creates a number of pods to execute the tasks that are defined in the pipeline. The PipelineRun automatically creates and triggers the TaskRuns for each Task in the pipeline.

  2. After a few minutes, verify that the Pipeline ran successfully by listing all the PipelineRuns as follows:

    $ tkn pipeline list
    
    NAME                        AGE             LAST RUN                              STARTED         DURATION    STATUS
    petclinic-deploy-pipeline   7 minutes ago   petclinic-deploy-pipeline-run-tsv92   5 minutes ago   4 minutes   Succeeded

Checking pipeline and application status

You can examine the logs for PipelineRuns to verify its status.

Procedure

  1. Check the PipelineRun logs as it runs using the tkn pipeline logs command, which interactively allows you to chose the required pipelinerun and inspect the logs:

    $ tkn pipeline logs -f
    ? Select pipeline : petclinic-deploy-pipeline
    ? Select pipelinerun : petclinic-deploy-pipeline-run-tsv92 started 39 seconds ago
    
    ...
    [build : nop] Build successful
    [deploy : build-step-oc] deploymentconfig.apps.openshift.io/spring-petclinic rolled out
    [deploy : nop] Build successful
  2. Check the Project Status in the OpenShift Web Console to verify that the PetClinic image is successfully built and deployed.

    Application deployed on OpenShift
  3. To rerun the last pipelinerun, using the same pipeline resources and service account used in the previous pipeline, use:

    tkn pipeline start petclinic-deploy-pipeline --last

Working with Pipelines using the OpenShift Developer Perspective

After you create Pipelines using the tkn CLI or YAML files. You can visually interact with your deployed Pipelines on the Developer Perspective of the Openshift web console.

The Pipelines view in the Developer perspective lists all the pipelines in a project; the last run of the pipeline, it’s status, and the time taken for the run; and the status of the individual tasks in a pipeline run.

Prerequisites

To view your pipelines in the Pipelines view and interact with them, ensure that:

Procedure

To visually interact with the pipelines in your project:

  1. In the Pipelines view of the Developer Perspective, select the project you created from the Project drop-down to see the pipelines listed in the Pipelines page.

    Pipelines in the Developer perspective
  2. Click on the required pipeline to see the Pipeline Details page. The pipelines Overview provides a visual representation of all the serial and parallel tasks in the pipeline.

    Pipeline overview
  3. Click:

    1. Pipeline Runs tab to see the completed, running, or failed runs for the pipeline.

    2. Parameters tab to see the parameters defined in the Pipeline and add or edit additional parameters as required.

    3. Resources tab to see the resources defined in the Pipeline and add or edit additional resources as required.

  4. Click Actions on the top-right corner and select Start to see the Start Pipeline dialog box. The resources populated in the Start Pipeline dialog box are based on the pipeline definition.

  5. Use the drop-downs in the Start Pipeline dialog box to select or create the required resources to customize them as required, and click Start to start the pipeline run.

  6. The Pipeline Run Details page displays the pipeline being executed. You can:

    • Hover over the tasks to see the time taken for each task execution.

    • Click on a task to see logs for that particular task.

    • Click the Logs tab to see the logs as per the execution sequence of the tasks.

      Pipeline run
  7. Click Pipelines Runs in the breadcrumb trail displayed at the top-left corner to see a list of pipeline runs for the pipeline in the Pipeline Runs page.

    • Use the filters to see the complete, running, or failed pipeline runs.

    • Use the Options menu adjacent to a pipeline run to stop a running pipeline, rerun a pipeline using the same parameters and resources as that of the previous pipeline execution, or delete a pipeline run.