Chapter 3. Pipelines

3.1. Red Hat OpenShift Pipelines release notes

Red Hat OpenShift Pipelines is a cloud-native CI/CD experience based on the Tekton project which provides:

  • Standard Kubernetes-native pipeline definitions (CRDs).
  • Serverless pipelines with no CI server management overhead.
  • Extensibility to build images using any Kubernetes tool, such as S2I, Buildah, JIB, and Kaniko.
  • Portability across any Kubernetes distribution.
  • Powerful CLI for interacting with pipelines.
  • Integrated user experience with the Developer perspective of the OpenShift Container Platform web console.

For an overview of Red Hat OpenShift Pipelines, see Understanding OpenShift Pipelines.

3.1.1. Compatibility and support matrix

Some features in this release are currently in Technology Preview. These experimental features are not intended for production use.

In the table, features are marked with the following statuses:

TP

Technology Preview

GA

General Availability

Table 3.1. Compatibility and support matrix

Red Hat OpenShift Pipelines VersionComponent VersionOpenShift VersionSupport Status

Operator

Pipelines

Triggers

CLI

Catalog

  

1.6

0.28.x

0.16.x

0.21.x

0.28

4.9

GA

1.5

0.24.x

0.14.x

0.19.x

0.24

4.8

GA

1.4

0.22.x

0.12.x

0.17.x

0.22

4.7

GA

Note

In Red Hat OpenShift Pipelines 1.6, Triggers 0.16.x transitioned to GA status. In earlier versions, Triggers was available as a technology preview feature.

For questions and feedback, you can send an email to the product team at pipelines-interest@redhat.com.

3.1.2. Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

3.1.3. Release notes for Red Hat OpenShift Pipelines General Availability 1.6

With this update, Red Hat OpenShift Pipelines General Availability (GA) 1.6 is available on OpenShift Container Platform 4.9.

3.1.3.1. New features

In addition to the fixes and stability improvements, the following sections highlight what is new in Red Hat OpenShift Pipelines 1.6.

  • With this update, you can configure a pipeline or task start command to return a YAML or JSON-formatted string by using the --output <string>, where <string> is yaml or json. Otherwise, without the --output option, the start command returns a human-friendly message that is hard for other programs to parse. Returning a YAML or JSON-formatted string is useful for continuous integration (CI) environments. For example, after a resource is created, you can use yq or jq to parse the YAML or JSON-formatted message about the resource and wait until that resource is terminated without using the showlog option.
  • With this update, you can authenticate to a registry using the auth.json authentication file of Podman. For example, you can use tkn bundle push to push to a remote registry using Podman instead of Docker CLI.
  • With this update, if you use the tkn [taskrun | pipelinerun] delete --all command, you can preserve runs that are younger than a specified number of minutes by using the new --keep-since <minutes> option. For example, to keep runs that are less than five minutes old, you enter tkn [taskrun | pipelinerun] delete -all --keep-since 5.
  • With this update, when you delete task runs or pipeline runs, you can use the --parent-resource and --keep-since options together. For example, the tkn pipelinerun delete --pipeline pipelinename --keep-since 5 command preserves pipeline runs whose parent resource is named pipelinename and whose age is five minutes or less. The tkn tr delete -t <taskname> --keep-since 5 and tkn tr delete --clustertask <taskname> --keep-since 5 commands work similarly for task runs.
  • This update adds support for the triggers resources to work with v1beta1 resources.
  • This update adds an ignore-running option to the tkn pipelinerun delete and tkn taskrun delete commands.
  • This update adds a create subcommand to the tkn task and tkn clustertask commands.
  • With this update, when you use the tkn pipelinerun delete --all command, you can use the new --label <string> option to filter the pipeline runs by label. Optionally, you can use the --label option with = and == as equality operators, or != as an inequality operator. For example, the tkn pipelinerun delete --all --label asdf and tkn pipelinerun delete --all --label==asdf commands both delete all the pipeline runs that have the asdf label.
  • With this update, you can fetch the version of installed Tekton components from the config map or, if the config map is not present, from the deployment controller.
  • With this update, triggers support the feature-flags and config-defaults config map to configure feature flags and to set default values respectively.
  • This update adds a new metric, eventlistener_event_count, that you can use to count events received by the EventListener resource.
  • This update adds v1beta1 Go API types. With this update, triggers now support the v1beta1 API version.

    With the current release, the v1alpha1 features are now deprecated and will be removed in a future release. Begin using the v1beta1 features instead.

  • In the current release, auto-prunning of resources is enabled by default. In addition, you can configure auto-prunning of task run and pipeline run for each namespace separately, by using the following new annotations:

    • operator.tekton.dev/prune.schedule: If the value of this annotation is different from the value specified at the TektonConfig custom resource definition, a new cron job in that namespace is created.
    • operator.tekton.dev/prune.skip: When set to true, the namespace for which it is configured will not be prunned.
    • operator.tekton.dev/prune.resources: This annotation accepts a comma-separated list of resources. To prune a single resource such as a pipeline run, set this annotation to "pipelinerun". To prune multiple resources, such as task run and pipeline run, set this annotation to "taskrun, pipelinerun".
    • operator.tekton.dev/prune.keep: Use this annotation to retain a resource without prunning.
    • operator.tekton.dev/prune.keep-since: Use this annotation to retain resources based on their age. The value for this annotation must be equal to the age of the resource in minutes. For example, to retain resources which were created not more than five days ago, set keep-since to 7200.

      Note

      The keep and keep-since annotations are mutually exclusive. For any resource, you must configure only one of them.

    • operator.tekton.dev/prune.strategy: Set the value of this annotation to either keep or keep-since.
  • Administrators can disable the creation of the pipeline service account for the entire cluster, and prevent privilege escalation by misusing the associated SCC, which is very similar to anyuid.
  • You can now configure feature flags and components by using the TektonConfig custom resource, and the custom resources for individual components, such as TektonPipeline and TektonTriggers. This level of granularity is useful for customization and testing of alpha features such as the Tekton OCI bundle for individual components.
  • You can now configure optional Timeouts field for the PipelineRun resource. For example, you can configure timeouts separately for a pipeline run, each task run, and the finally tasks.
  • The pods generated by the TaskRun resource now sets the activeDeadlineSeconds field of the pods. This enables OpenShift to consider them as terminating, and allows you to use specifically scoped ResourceQuota object for the pods.
  • You can use configmaps to eliminate metrics tags or labels type on a task run, pipeline run, task, and pipeline. In addition, you can configure different types of metrics for measuring duration, such as a histogram, gauge, or last value.
  • You can define requests and limits on a pod coherently, as Tekton now fully supports the LimitRange object by considering the Min, Max, Default, and DefaultRequest fields.
  • The following alpha features are introduced:

    • A pipeline run can now stop after running the finally tasks, rather than the previous behavior of stopping the execution of all task run directly. This update adds the following spec.status values:

      • StoppedRunFinally will stop the currently running tasks after they are completed, and then run the finally tasks.
      • CancelledRunFinally will immediately cancel the running tasks, and then run the finally tasks.
      • Cancelled will retain the previous behavior provided by the PipelineRunCancelled status.

        Note

        The Cancelled status replaces the deprecated PipelineRunCancelled status, which will be removed in the v1 version.

    • You can now use the oc debug command to put a task run into debug mode, which pauses the execution and allows you to inspect specific steps in a pod.
    • When you set the onError field of a step to continue, the exit code for the step is recorded and passed on to subsequent steps. However, the task run does not fail and the execution of the rest of the steps in the task continues. To retain the existing behavior, you can set the value of the onError field to stopAndFail.
    • Tasks can now accept more parameters than are actually used. When the alpha feature flag is enabled, the parameters can implicitly propagate to inlined specs. For example, an inlined task can access parameters of its parent pipeline run, without explicitly defining each parameter for the task.
    • If you enable the flag for the alpha features, the conditions under When expressions will only apply to the task with which it is directly associated, and not the dependents of the task. To apply the When expressions to the associated task and its dependents, you must associate the expression with each dependent task separately. Note that, going forward, this will be the default behavior of the When expressions in any new API versions of Tekton. The existing default behavior will be deprecated in favor of this update.
  • The current release enables you to configure node selection by specifying the nodeSelector and tolerations values in the TektonConfig custom resource (CR). The Operator adds these values to all the deployments that it creates.

    • To configure node selection for the Operator’s controller and webhook deployment, you edit the config.nodeSelector and config.tolerations fields in the specification for the Subscription CR, after installing the Operator.
    • To deploy the rest of the control plane pods of OpenShift Pipelines on an infrastructure node, update the TektonConfig CR with the nodeSelector and tolerations fields. The modifications are then applied to all the pods created by Operator.

3.1.3.2. Deprecated features

  • In CLI 0.21.0, support for all v1alpha1 resources for clustertask, task, taskrun, pipeline, and pipelinerun commands are deprecated. These resources are now deprecated and will be removed in a future release.
  • In Tekton Triggers v0.16.0, the redundant status label is removed from the metrics for the EventListener resource.

    Important

    Breaking change: The status label has been removed from the eventlistener_http_duration_seconds_* metric. Remove queries that are based on the status label.

  • With the current release, the v1alpha1 features are now deprecated and will be removed in a future release. With this update, you can begin using the v1beta1 Go API types instead. Triggers now supports the v1beta1 API version.
  • With the current release, the EventListener resource sends a response before the triggers finish processing.

    Important

    Breaking change: With this change, the EventListener resource stops responding with a 201 Created status code when it creates resources. Instead, it responds with a 202 Accepted response code.

  • The current release removes the podTemplate field from the EventListener resource.

    Important

    Breaking change: The podTemplate field, which was deprecated as part of #1100, has been removed.

  • The current release removes the deprecated replicas field from the specification for the EventListener resource.

    Important

    Breaking change: The deprecated replicas field has been removed.

  • In Red Hat OpenShift Pipelines 1.6, the values of HOME="/tekton/home" and workingDir="/workspace" are removed from the specification of the Step objects.

    Instead, Red Hat OpenShift Pipelines sets HOME and workingDir to the values defined by the containers running the Step objects. You can override these values in the specification of your Step objects.

    To use the older behavior, you can change the disable-working-directory-overwrite and disable-home-env-overwrite fields in the TektonConfig CR to false:

    apiVersion: operator.tekton.dev/v1alpha1
      kind: TektonConfig
      metadata:
        name: config
      spec:
        pipeline:
          disable-working-directory-overwrite: false
          disable-home-env-overwrite: false
      ...
    Important

    The disable-working-directory-overwrite and disable-home-env-overwrite fields in the TektonConfig CR are now deprecated and will be removed in a future release.

3.1.3.3. Known issues

  • When you run Maven and Jib-Maven cluster tasks, the default container image is supported only on Intel (x86) architecture. Therefore, tasks will fail on IBM Power Systems (ppc64le), IBM Z, and LinuxONE (s390x) clusters. As a workaround, you can specify a custom image by setting the MAVEN_IMAGE parameter value to maven:3.6.3-adoptopenjdk-11.
  • On IBM Power Systems, IBM Z, and LinuxONE, the s2i-dotnet cluster task is unsupported.
  • Before you install tasks based on the Tekton Catalog on IBM Power Systems (ppc64le), IBM Z, and LinuxONE (s390x) using tkn hub, verify if the task can be executed on these platforms. To check if ppc64le and s390x are listed in the "Platforms" section of the task information, you can run the following command: tkn hub info task <name>
  • You cannot use the nodejs:14-ubi8-minimal image stream because doing so generates the following errors:

    STEP 7: RUN /usr/libexec/s2i/assemble
    /bin/sh: /usr/libexec/s2i/assemble: No such file or directory
    subprocess exited with status 127
    subprocess exited with status 127
    error building at STEP "RUN /usr/libexec/s2i/assemble": exit status 127
    time="2021-11-04T13:05:26Z" level=error msg="exit status 127"

3.1.3.4. Fixed issues

  • The tkn hub command is now supported on IBM Power Systems, IBM Z, and LinuxONE.
  • Before this update, the terminal was not available after the user ran a tkn command, and the pipeline run was done, even if retries were specified. Specifying a timeout in the task run or pipeline run had no effect. This update fixes the issue so that the terminal is available after running the command.
  • Before this update, running tkn pipelinerun delete --all would delete all resources. This update prevents the resources in the running state from getting deleted.
  • Before this update, using the tkn version --component=<component> command did not return the component version. This update fixes the issue so that this command returns the component version.
  • Before this update, when you used the tkn pr logs command, it displayed the pipelines output logs in the wrong task order. This update resolves the issue so that logs of completed PipelineRuns are listed in the appropriate TaskRun execution order.
  • Before this update, editing the specification of a running pipeline might prevent the pipeline run from stopping when it was complete. This update fixes the issue by fetching the definition only once and then using the specification stored in the status for verification. This change reduces the probability of a race condition when a PipelineRun or a TaskRun refers to a Pipeline or Task that changes while it is running.
  • When expression values can now have array parameter references, such as: values: [$(params.arrayParam[*])].

3.1.3.5. Release notes for Red Hat OpenShift Pipelines General Availability 1.6.1

3.1.3.5.1. Known issues
  • After upgrading to Red Hat OpenShift Pipelines 1.6.1 from an older version, Pipelines might enter an inconsistent state where you are unable to perform any operations (create/delete/apply) on Tekton resources (tasks and pipelines). For example, while deleting a resource, you might encounter the following error:

    Error from server (InternalError): Internal error occurred: failed calling webhook "validation.webhook.pipeline.tekton.dev": Post "https://tekton-pipelines-webhook.openshift-pipelines.svc:443/resource-validation?timeout=10s": service "tekton-pipelines-webhook" not found.
3.1.3.5.2. Fixed issues
  • The SSL_CERT_DIR environment variable (/tekton-custom-certs) set by Red Hat OpenShift Pipelines will not override the following default system directories with certificate files:

    • /etc/pki/tls/certs
    • /etc/ssl/certs
    • /system/etc/security/cacerts
  • The Horizontal Pod Autoscaler can manage the replica count of deployments controlled by the Red Hat OpenShift Pipelines Operator. From this release onward, if the count is changed by an end user or an on-cluster agent, the Red Hat OpenShift Pipelines Operator will not reset the replica count of deployments managed by it. However, the replicas will be reset when you upgrade the Red Hat OpenShift Pipelines Operator.
  • The pod serving the tkn CLI will now be scheduled on nodes, based on the node selector and toleration limits specified in the TektonConfig custom resource.

3.1.4. Release notes for Red Hat OpenShift Pipelines General Availability 1.5

Red Hat OpenShift Pipelines General Availability (GA) 1.5 is now available on OpenShift Container Platform 4.9.

3.1.4.1. Compatibility and support matrix

Some features in this release are currently in Technology Preview. These experimental features are not intended for production use.

In the table, features are marked with the following statuses:

TP

Technology Preview

GA

General Availability

Note the following scope of support on the Red Hat Customer Portal for these features:

Table 3.2. Compatibility and support matrix

FeatureVersionSupport Status

Pipelines

0.24

GA

CLI

0.19

GA

Catalog

0.24

GA

Triggers

0.14

TP

Pipeline resources

-

TP

For questions and feedback, you can send an email to the product team at pipelines-interest@redhat.com.

3.1.4.2. New features

In addition to the fixes and stability improvements, the following sections highlight what is new in Red Hat OpenShift Pipelines 1.5.

  • Pipeline run and task runs will be automatically pruned by a cron job in the target namespace. The cron job uses the IMAGE_JOB_PRUNER_TKN environment variable to get the value of tkn image. With this enhancement, the following fields are introduced to the TektonConfig custom resource:

    ...
    pruner:
      resources:
        - pipelinerun
        - taskrun
      schedule: "*/5 * * * *" # cron schedule
      keep: 2 # delete all keeping n
    ...
  • In OpenShift Container Platform, you can customize the installation of the Tekton Add-ons component by modifying the values of the new parameters clusterTasks and pipelinesTemplates in the TektonConfig custom resource:

    apiVersion: operator.tekton.dev/v1alpha1
    kind: TektonConfig
    metadata:
      name: config
    spec:
      profile: all
      targetNamespace: openshift-pipelines
      addon:
        params:
        - name: clusterTasks
          value: "true"
        - name: pipelineTemplates
          value: "true"
    ...

    The customization is allowed if you create the add-on using TektonConfig, or directly by using Tekton Add-ons. However, if the parameters are not passed, the controller adds parameters with default values.

    Note
    • If add-on is created using the TektonConfig custom resource, and you change the parameter values later in the Addon custom resource, then the values in the TektonConfig custom resource overwrites the changes.
    • You can set the value of the pipelinesTemplates parameter to true only when the value of the clusterTasks parameter is true.
  • The enableMetrics parameter is added to the TektonConfig custom resource. You can use it to disable the service monitor, which is part of Tekton Pipelines for OpenShift Container Platform.

    apiVersion: operator.tekton.dev/v1alpha1
    kind: TektonConfig
    metadata:
      name: config
    spec:
      profile: all
      targetNamespace: openshift-pipelines
      pipeline:
        params:
        - name: enableMetrics
          value: "true"
    ...
  • Eventlistener OpenCensus metrics, which captures metrics at process level, is added.
  • Triggers now has label selector; you can configure triggers for an event listener using labels.
  • The ClusterInterceptor custom resource definition for registering interceptors is added, which allows you to register new Interceptor types that you can plug in. In addition, the following relevant changes are made:

    • In the trigger specifications, you can configure interceptors using a new API that includes a ref field to refer to a cluster interceptor. In addition, you can use the params field to add parameters that pass on to the interceptors for processing.
    • The bundled interceptors CEL, GitHub, GitLab, and BitBucket, have been migrated. They are implemented using the new ClusterInterceptor custom resource definition.
    • Core interceptors are migrated to the new format, and any new triggers created using the old syntax automatically switch to the new ref or params based syntax.
  • To disable prefixing the name of the task or step while displaying logs, use the --prefix option for log commands.
  • To display the version of a specific component, use the new --component flag in the tkn version command.
  • The tkn hub check-upgrade command is added, and other commands are revised to be based on the pipeline version. In addition, catalog names are displayed in the search command output.
  • Support for optional workspaces are added to the start command.
  • If the plugins are not present in the plugins directory, they are searched in the current path.
  • The tkn start [task | clustertask | pipeline] command starts interactively and ask for the params value, even when you specify the default parameters are specified. To stop the interactive prompts, pass the --use-param-defaults flag at the time of invoking the command. For example:

    $ tkn pipeline start build-and-deploy \
        -w name=shared-workspace,volumeClaimTemplateFile=https://raw.githubusercontent.com/openshift/pipelines-tutorial/pipelines-1.6/01_pipeline/03_persistent_volume_claim.yaml \
        -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/pipelines-vote-api \
        --use-param-defaults
  • The version field is added in the tkn task describe command.
  • The option to automatically select resources such as TriggerTemplate, or TriggerBinding, or ClusterTriggerBinding, or Eventlistener, is added in the describe command, if only one is present.
  • In the tkn pr describe command, a section for skipped tasks is added.
  • Support for the tkn clustertask logs is added.
  • The YAML merge and variable from config.yaml is removed. In addition, the release.yaml file can now be more easily consumed by tools such as kustomize and ytt.
  • The support for resource names to contain the dot character (".") is added.
  • The hostAliases array in the PodTemplate specification is added to the pod-level override of hostname resolution. It is achieved by modifying the /etc/hosts file.
  • A variable $(tasks.status) is introduced to access the aggregate execution status of tasks.
  • An entry-point binary build for Windows is added.

3.1.4.3. Deprecated features

  • In the when expressions, support for fields written is PascalCase is removed. The when expressions only support fields written in lowercase.

    Note

    If you had applied a pipeline with when expressions in Tekton Pipelines v0.16 (Operator v1.2.x), you have to reapply it.

  • When you upgrade the Red Hat OpenShift Pipelines Operator to v1.5, the openshift-client and the openshift-client-v-1-5-0 cluster tasks have the SCRIPT parameter. However, the ARGS parameter and the git resource are removed from the specification of the openshift-client cluster task. This is a breaking change, and only those cluster tasks that do not have a specific version in the name field of the ClusterTask resource upgrade seamlessly.

    To prevent the pipeline runs from breaking, use the SCRIPT parameter after the upgrade because it moves the values previously specified in the ARGS parameter into the SCRIPT parameter of the cluster task. For example:

    ...
    - name: deploy
      params:
      - name: SCRIPT
        value: oc rollout status <deployment-name>
      runAfter:
        - build
      taskRef:
        kind: ClusterTask
        name: openshift-client
    ...
  • When you upgrade from Red Hat OpenShift Pipelines Operator v1.4 to v1.5, the profile names in which the TektonConfig custom resource is installed now change.

    Table 3.3. Profiles for TektonConfig custom resource

    Profiles in Pipelines 1.5Corresponding profile in Pipelines 1.4Installed Tekton components

    All (default profile)

    All (default profile)

    Pipelines, Triggers, Add-ons

    Basic

    Default

    Pipelines, Triggers

    Lite

    Basic

    Pipelines

    Note

    If you used profile: all in the config instance of the TektonConfig custom resource, no change is necessary in the resource specification.

    However, if the installed Operator is either in the Default or the Basic profile before the upgrade, you must edit the config instance of the TektonConfig custom resource after the upgrade. For example, if the configuration was profile: basic before the upgrade, ensure that it is profile: lite after upgrading to Pipelines 1.5.

  • The disable-home-env-overwrite and disable-working-dir-overwrite fields are now deprecated and will be removed in a future release. For this release, the default value of these flags is set to true for backward compatibility.

    Note

    In the next release (Red Hat OpenShift Pipelines 1.6), the HOME environment variable will not be automatically set to /tekton/home, and the default working directory will not be set to /workspace for task runs. These defaults collide with any value set by image Dockerfile of the step.

  • The ServiceType and podTemplate fields are removed from the EventListener spec.
  • The controller service account no longer requests cluster-wide permission to list and watch namespaces.
  • The status of the EventListener resource has a new condition called Ready.

    Note

    In the future, the other status conditions for the EventListener resource will be deprecated in favor of the Ready status condition.

  • The eventListener and namespace fields in the EventListener response are deprecated. Use the eventListenerUID field instead.
  • The replicas field is deprecated from the EventListener spec. Instead, the spec.replicas field is moved to spec.resources.kubernetesResource.replicas in the KubernetesResource spec.

    Note

    The replicas field will be removed in a future release.

  • The old method of configuring the core interceptors is deprecated. However, it continues to work until it is removed in a future release. Instead, interceptors in a Trigger resource are now configured using a new ref and params based syntax. The resulting default webhook automatically switch the usages of the old syntax to the new syntax for new triggers.
  • Use rbac.authorization.k8s.io/v1 instead of the deprecated rbac.authorization.k8s.io/v1beta1 for the ClusterRoleBinding resource.
  • In cluster roles, the cluster-wide write access to resources such as serviceaccounts, secrets, configmaps, and limitranges are removed. In addition, cluster-wide access to resources such as deployments, statefulsets, and deployment/finalizers are removed.
  • The image custom resource definition in the caching.internal.knative.dev group is not used by Tekton anymore, and is excluded in this release.

3.1.4.4. Known issues

  • The git-cli cluster task is built off the alpine/git base image, which expects /root as the user’s home directory. However, this is not explicitly set in the git-cli cluster task.

    In Tekton, the default home directory is overwritten with /tekton/home for every step of a task, unless otherwise specified. This overwriting of the $HOME environment variable of the base image causes the git-cli cluster task to fail.

    This issue is expected to be fixed in the upcoming releases. For Red Hat OpenShift Pipelines 1.5 and earlier versions, you can use any one of the following workarounds to avoid the failure of the git-cli cluster task:

    • Set the $HOME environment variable in the steps, so that it is not overwritten.

      1. [OPTIONAL] If you installed Red Hat OpenShift Pipelines using the Operator, then clone the git-cli cluster task into a separate task. This approach ensures that the Operator does not overwrite the changes made to the cluster task.
      2. Execute the oc edit clustertasks git-cli command.
      3. Add the expected HOME environment variable to the YAML of the step:

        ...
        steps:
          - name: git
            env:
            - name: HOME
              value: /root
            image: $(params.BASE_IMAGE)
            workingDir: $(workspaces.source.path)
        ...
        Warning

        For Red Hat OpenShift Pipelines installed by the Operator, if you do not clone the git-cli cluster task into a separate task before changing the HOME environment variable, then the changes are overwritten during Operator reconciliation.

    • Disable overwriting the HOME environment variable in the feature-flags config map.

      1. Execute the oc edit -n openshift-pipelines configmap feature-flags command.
      2. Set the value of the disable-home-env-overwrite flag to true.

        Warning
        • If you installed Red Hat OpenShift Pipelines using the Operator, then the changes are overwritten during Operator reconciliation.
        • Modifying the default value of the disable-home-env-overwrite flag can break other tasks and cluster tasks, as it changes the default behavior for all tasks.
    • Use a different service account for the git-cli cluster task, as the overwriting of the HOME environment variable happens when the default service account for pipelines is used.

      1. Create a new service account.
      2. Link your Git secret to the service account you just created.
      3. Use the service account while executing a task or a pipeline.
  • On IBM Power Systems, IBM Z, and LinuxONE, the s2i-dotnet cluster task and the tkn hub command are unsupported.
  • When you run Maven and Jib-Maven cluster tasks, the default container image is supported only on Intel (x86) architecture. Therefore, tasks will fail on IBM Power Systems (ppc64le), IBM Z, and LinuxONE (s390x) clusters. As a workaround, you can specify a custom image by setting the MAVEN_IMAGE parameter value to maven:3.6.3-adoptopenjdk-11.

3.1.4.5. Fixed issues

  • The when expressions in dag tasks are not allowed to specify the context variable accessing the execution status ($(tasks.<pipelineTask>.status)) of any other task.
  • Use Owner UIDs instead of Owner names, as it helps avoid race conditions created by deleting a volumeClaimTemplate PVC, in situations where a PipelineRun resource is quickly deleted and then recreated.
  • A new Dockerfile is added for pullrequest-init for build-base image triggered by non-root users.
  • When a pipeline or task is executed with the -f option and the param in its definition does not have a type defined, a validation error is generated instead of the pipeline or task run failing silently.
  • For the tkn start [task | pipeline | clustertask] commands, the description of the --workspace flag is now consistent.
  • While parsing the parameters, if an empty array is encountered, the corresponding interactive help is displayed as an empty string now.

3.1.5. Release notes for Red Hat OpenShift Pipelines General Availability 1.4

Red Hat OpenShift Pipelines General Availability (GA) 1.4 is now available on OpenShift Container Platform 4.7.

Note

In addition to the stable and preview Operator channels, the Red Hat OpenShift Pipelines Operator 1.4.0 comes with the ocp-4.6, ocp-4.5, and ocp-4.4 deprecated channels. These deprecated channels and support for them will be removed in the following release of Red Hat OpenShift Pipelines.

3.1.5.1. Compatibility and support matrix

Some features in this release are currently in Technology Preview. These experimental features are not intended for production use.

In the table, features are marked with the following statuses:

TP

Technology Preview

GA

General Availability

Note the following scope of support on the Red Hat Customer Portal for these features:

Table 3.4. Compatibility and support matrix

FeatureVersionSupport Status

Pipelines

0.22

GA

CLI

0.17

GA

Catalog

0.22

GA

Triggers

0.12

TP

Pipeline resources

-

TP

For questions and feedback, you can send an email to the product team at pipelines-interest@redhat.com.

3.1.5.2. New features

In addition to the fixes and stability improvements, the following sections highlight what is new in Red Hat OpenShift Pipelines 1.4.

  • The custom tasks have the following enhancements:

    • Pipeline results can now refer to results produced by custom tasks.
    • Custom tasks can now use workspaces, service accounts, and pod templates to build more complex custom tasks.
  • The finally task has the following enhancements:

    • The when expressions are supported in finally tasks, which provides efficient guarded execution and improved reusability of tasks.
    • A finally task can be configured to consume the results of any task within the same pipeline.

      Note

      Support for when expressions and finally tasks are unavailable in the OpenShift Container Platform 4.7 web console.

  • Support for multiple secrets of the type dockercfg or dockerconfigjson is added for authentication at runtime.
  • Functionality to support sparse-checkout with the git-clone task is added. This enables you to clone only a subset of the repository as your local copy, and helps you to restrict the size of the cloned repositories.
  • You can create pipeline runs in a pending state without actually starting them. In clusters that are under heavy load, this allows Operators to have control over the start time of the pipeline runs.
  • Ensure that you set the SYSTEM_NAMESPACE environment variable manually for the controller; this was previously set by default.
  • A non-root user is now added to the build-base image of pipelines so that git-init can clone repositories as a non-root user.
  • Support to validate dependencies between resolved resources before a pipeline run starts is added. All result variables in the pipeline must be valid, and optional workspaces from a pipeline can only be passed to tasks expecting it for the pipeline to start running.
  • The controller and webhook runs as a non-root group, and their superfluous capabilities have been removed to make them more secure.
  • You can use the tkn pr logs command to see the log streams for retried task runs.
  • You can use the --clustertask option in the tkn tr delete command to delete all the task runs associated with a particular cluster task.
  • Support for using Knative service with the EventListener resource is added by introducing a new customResource field.
  • An error message is displayed when an event payload does not use the JSON format.
  • The source control interceptors such as GitLab, BitBucket, and GitHub, now use the new InterceptorRequest or InterceptorResponse type interface.
  • A new CEL function marshalJSON is implemented so that you can encode a JSON object or an array to a string.
  • An HTTP handler for serving the CEL and the source control core interceptors is added. It packages four core interceptors into a single HTTP server that is deployed in the tekton-pipelines namespace. The EventListener object forwards events over the HTTP server to the interceptor. Each interceptor is available at a different path. For example, the CEL interceptor is available on the /cel path.
  • The pipelines-scc Security Context Constraint (SCC) is used with the default pipeline service account for pipelines. This new service account is similar to anyuid, but with a minor difference as defined in the YAML for SCC of OpenShift Container Platform 4.7:

    fsGroup:
      type: MustRunAs

3.1.5.3. Deprecated features

  • The build-gcs sub-type in the pipeline resource storage, and the gcs-fetcher image, are not supported.
  • In the taskRun field of cluster tasks, the label tekton.dev/task is removed.
  • For webhooks, the value v1beta1 corresponding to the field admissionReviewVersions is removed.
  • The creds-init helper image for building and deploying is removed.
  • In the triggers spec and binding, the deprecated field template.name is removed in favor of template.ref. You should update all eventListener definitions to use the ref field.

    Note

    Upgrade from Pipelines 1.3.x and earlier versions to Pipelines 1.4.0 breaks event listeners because of the unavailability of the template.name field. For such cases, use Pipelines 1.4.1 to avail the restored template.name field.

  • For EventListener custom resources/objects, the fields PodTemplate and ServiceType are deprecated in favor of Resource.
  • The deprecated spec style embedded bindings is removed.
  • The spec field is removed from the triggerSpecBinding.
  • The event ID representation is changed from a five-character random string to a UUID.

3.1.5.4. Known issues

  • In the Developer perspective, the pipeline metrics and triggers features are available only on OpenShift Container Platform 4.7.6 or later versions.
  • On IBM Power Systems, IBM Z, and LinuxONE, the tkn hub command is not supported.
  • When you run Maven and Jib Maven cluster tasks on an IBM Power Systems (ppc64le), IBM Z, and LinuxONE (s390x) clusters, set the MAVEN_IMAGE parameter value to maven:3.6.3-adoptopenjdk-11.
  • Triggers throw error resulting from bad handling of the JSON format, if you have the following configuration in the trigger binding:

    params:
      - name: github_json
        value: $(body)

    To resolve the issue:

    • If you are using triggers v0.11.0 and above, use the marshalJSON CEL function, which takes a JSON object or array and returns the JSON encoding of that object or array as a string.
    • If you are using older triggers version, add the following annotation in the trigger template:

      annotations:
        triggers.tekton.dev/old-escape-quotes: "true"
  • When upgrading from Pipelines 1.3.x to 1.4.x, you must recreate the routes.

3.1.5.5. Fixed issues

  • Previously, the tekton.dev/task label was removed from the task runs of cluster tasks, and the tekton.dev/clusterTask label was introduced. The problems resulting from that change is resolved by fixing the clustertask describe and delete commands. In addition, the lastrun function for tasks is modified, to fix the issue of the tekton.dev/task label being applied to the task runs of both tasks and cluster tasks in older versions of pipelines.
  • When doing an interactive tkn pipeline start pipelinename, a PipelineResource is created interactively. The tkn p start command prints the resource status if the resource status is not nil.
  • Previously, the tekton.dev/task=name label was removed from the task runs created from cluster tasks. This fix modifies the tkn clustertask start command with the --last flag to check for the tekton.dev/task=name label in the created task runs.
  • When a task uses an inline task specification, the corresponding task run now gets embedded in the pipeline when you run the tkn pipeline describe command, and the task name is returned as embedded.
  • The tkn version command is fixed to display the version of the installed Tekton CLI tool, without a configured kubeConfiguration namespace or access to a cluster.
  • If an argument is unexpected or more than one arguments are used, the tkn completion command gives an error.
  • Previously, pipeline runs with the finally tasks nested in a pipeline specification would lose those finally tasks, when converted to the v1alpha1 version and restored back to the v1beta1 version. This error occurring during conversion is fixed to avoid potential data loss. Pipeline runs with the finally tasks nested in a pipeline specification is now serialized and stored on the alpha version, only to be deserialized later.
  • Previously, there was an error in the pod generation when a service account had the secrets field as {}. The task runs failed with CouldntGetTask because the GET request with an empty secret name returned an error, indicating that the resource name may not be empty. This issue is fixed by avoiding an empty secret name in the kubeclient GET request.
  • Pipelines with the v1beta1 API versions can now be requested along with the v1alpha1 version, without losing the finally tasks. Applying the returned v1alpha1 version will store the resource as v1beta1, with the finally section restored to its original state.
  • Previously, an unset selfLink field in the controller caused an error in the Kubernetes v1.20 clusters. As a temporary fix, the CloudEvent source field is set to a value that matches the current source URI, without the value of the auto-populated selfLink field.
  • Previously, a secret name with dots such as gcr.io led to a task run creation failure. This happened because of the secret name being used internally as part of a volume mount name. The volume mount name conforms to the RFC1123 DNS label and disallows dots as part of the name. This issue is fixed by replacing the dot with a dash that results in a readable name.
  • Context variables are now validated in the finally tasks.
  • Previously, when the task run reconciler was passed a task run that did not have a previous status update containing the name of the pod it created, the task run reconciler listed the pods associated with the task run. The task run reconciler used the labels of the task run, which were propagated to the pod, to find the pod. Changing these labels while the task run was running, caused the code to not find the existing pod. As a result, duplicate pods were created. This issue is fixed by changing the task run reconciler to only use the tekton.dev/taskRun Tekton-controlled label when finding the pod.
  • Previously, when a pipeline accepted an optional workspace and passed it to a pipeline task, the pipeline run reconciler stopped with an error if the workspace was not provided, even if a missing workspace binding is a valid state for an optional workspace. This issue is fixed by ensuring that the pipeline run reconciler does not fail to create a task run, even if an optional workspace is not provided.
  • The sorted order of step statuses matches the order of step containers.
  • Previously, the task run status was set to unknown when a pod encountered the CreateContainerConfigError reason, which meant that the task and the pipeline ran until the pod timed out. This issue is fixed by setting the task run status to false, so that the task is set as failed when the pod encounters the CreateContainerConfigError reason.
  • Previously, pipeline results were resolved on the first reconciliation, after a pipeline run was completed. This could fail the resolution resulting in the Succeeded condition of the pipeline run being overwritten. As a result, the final status information was lost, potentially confusing any services watching the pipeline run conditions. This issue is fixed by moving the resolution of pipeline results to the end of a reconciliation, when the pipeline run is put into a Succeeded or True condition.
  • Execution status variable is now validated. This avoids validating task results while validating context variables to access execution status.
  • Previously, a pipeline result that contained an invalid variable would be added to the pipeline run with the literal expression of the variable intact. Therefore, it was difficult to assess whether the results were populated correctly. This issue is fixed by filtering out the pipeline run results that reference failed task runs. Now, a pipeline result that contains an invalid variable will not be emitted by the pipeline run at all.
  • The tkn eventlistener describe command is fixed to avoid crashing without a template. It also displays the details about trigger references.
  • Upgrades from Pipelines 1.3.x and earlier versions to Pipelines 1.4.0 breaks event listeners because of the unavailability of template.name. In Pipelines 1.4.1, the template.name has been restored to avoid breaking event listeners in triggers.
  • In Pipelines 1.4.1, the ConsoleQuickStart custom resource has been updated to align with OpenShift Container Platform 4.7 capabilities and behavior.

3.1.6. Release notes for Red Hat OpenShift Pipelines Technology Preview 1.3

3.1.6.1. New features

Red Hat OpenShift Pipelines Technology Preview (TP) 1.3 is now available on OpenShift Container Platform 4.7. Red Hat OpenShift Pipelines TP 1.3 is updated to support:

  • Tekton Pipelines 0.19.0
  • Tekton tkn CLI 0.15.0
  • Tekton Triggers 0.10.2
  • cluster tasks based on Tekton Catalog 0.19.0
  • IBM Power Systems on OpenShift Container Platform 4.7
  • IBM Z and LinuxONE on OpenShift Container Platform 4.7

In addition to the fixes and stability improvements, the following sections highlight what is new in Red Hat OpenShift Pipelines 1.3.

3.1.6.1.1. Pipelines
  • Tasks that build images, such as S2I and Buildah tasks, now emit a URL of the image built that includes the image SHA.
  • Conditions in pipeline tasks that reference custom tasks are disallowed because the Condition custom resource definition (CRD) has been deprecated.
  • Variable expansion is now added in the Task CRD for the following fields: spec.steps[].imagePullPolicy and spec.sidecar[].imagePullPolicy.
  • You can disable the built-in credential mechanism in Tekton by setting the disable-creds-init feature-flag to true.
  • Resolved when expressions are now listed in the Skipped Tasks and the Task Runs sections in the Status field of the PipelineRun configuration.
  • The git init command can now clone recursive submodules.
  • A Task CR author can now specify a timeout for a step in the Task spec.
  • You can now base the entry point image on the distroless/static:nonroot image and give it a mode to copy itself to the destination, without relying on the cp command being present in the base image.
  • You can now use the configuration flag require-git-ssh-secret-known-hosts to disallow omitting known hosts in the Git SSH secret. When the flag value is set to true, you must include the known_host field in the Git SSH secret. The default value for the flag is false.
  • The concept of optional workspaces is now introduced. A task or pipeline might declare a workspace optional and conditionally change their behavior based on its presence. A task run or pipeline run might also omit that workspace, thereby modifying the task or pipeline behavior. The default task run workspaces are not added in place of an omitted optional workspace.
  • Credentials initialization in Tekton now detects an SSH credential that is used with a non-SSH URL, and vice versa in Git pipeline resources, and logs a warning in the step containers.
  • The task run controller emits a warning event if the affinity specified by the pod template is overwritten by the affinity assistant.
  • The task run reconciler now records metrics for cloud events that are emitted once a task run is completed. This includes retries.
3.1.6.1.2. Pipelines CLI
  • Support for --no-headers flag is now added to the following commands: tkn condition list,tkn triggerbinding list,tkn eventlistener list,tkn clustertask list, tkn clustertriggerbinding list.
  • When used together, the --last or --use options override the --prefix-name and --timeout options.
  • The tkn eventlistener logs command is now added to view the EventListener logs.
  • The tekton hub commands are now integrated into the tkn CLI.
  • The --nocolour option is now changed to --no-color.
  • The --all-namespaces flag is added to the following commands: tkn triggertemplate list, tkn condition list, tkn triggerbinding list, tkn eventlistener list.
3.1.6.1.3. Triggers
  • You can now specify your resource information in the EventListener template.
  • It is now mandatory for EventListener service accounts to have the list and watch verbs, in addition to the get verb for all the triggers resources. This enables you to use Listers to fetch data from EventListener, Trigger, TriggerBinding, TriggerTemplate, and ClusterTriggerBinding resources. You can use this feature to create a Sink object rather than specifying multiple informers, and directly make calls to the API server.
  • A new Interceptor interface is added to support immutable input event bodies. Interceptors can now add data or fields to a new extensions field, and cannot modify the input bodies making them immutable. The CEL interceptor uses this new Interceptor interface.
  • A namespaceSelector field is added to the EventListener resource. Use it to specify the namespaces from where the EventListener resource can fetch the Trigger object for processing events. To use the namespaceSelector field, the service account for the EventListener resource must have a cluster role.
  • The triggers EventListener resource now supports end-to-end secure connection to the eventlistener pod.
  • The escaping parameters behavior in the TriggerTemplates resource by replacing " with \" is now removed.
  • A new resources field, supporting Kubernetes resources, is introduced as part of the EventListener spec.
  • A new functionality for the CEL interceptor, with support for upper and lower-casing of ASCII strings, is added.
  • You can embed TriggerBinding resources by using the name and value fields in a trigger, or an event listener.
  • The PodSecurityPolicy configuration is updated to run in restricted environments. It ensures that containers must run as non-root. In addition, the role-based access control for using the pod security policy is moved from cluster-scoped to namespace-scoped. This ensures that the triggers cannot use other pod security policies that are unrelated to a namespace.
  • Support for embedded trigger templates is now added. You can either use the name field to refer to an embedded template or embed the template inside the spec field.

3.1.6.2. Deprecated features

  • Pipeline templates that use PipelineResources CRDs are now deprecated and will be removed in a future release.
  • The template.name field is deprecated in favor of the template.ref field and will be removed in a future release.
  • The -c shorthand for the --check command has been removed. In addition, global tkn flags are added to the version command.

3.1.6.3. Known issues

  • CEL overlays add fields to a new top-level extensions function, instead of modifying the incoming event body. TriggerBinding resources can access values within this new extensions function using the $(extensions.<key>) syntax. Update your binding to use the $(extensions.<key>) syntax instead of the $(body.<overlay-key>) syntax.
  • The escaping parameters behavior by replacing " with \" is now removed. If you need to retain the old escaping parameters behavior add the tekton.dev/old-escape-quotes: true" annotation to your TriggerTemplate specification.
  • You can embed TriggerBinding resources by using the name and value fields inside a trigger or an event listener. However, you cannot specify both name and ref fields for a single binding. Use the ref field to refer to a TriggerBinding resource and the name field for embedded bindings.
  • An interceptor cannot attempt to reference a secret outside the namespace of an EventListener resource. You must include secrets in the namespace of the `EventListener`resource.
  • In Triggers 0.9.0 and later, if a body or header based TriggerBinding parameter is missing or malformed in an event payload, the default values are used instead of displaying an error.
  • Tasks and pipelines created with WhenExpression objects using Tekton Pipelines 0.16.x must be reapplied to fix their JSON annotations.
  • When a pipeline accepts an optional workspace and gives it to a task, the pipeline run stalls if the workspace is not provided.
  • To use the Buildah cluster task in a disconnected environment, ensure that the Dockerfile uses an internal image stream as the base image, and then use it in the same manner as any S2I cluster task.

3.1.6.4. Fixed issues

  • Extensions added by a CEL Interceptor are passed on to webhook interceptors by adding the Extensions field within the event body.
  • The activity timeout for log readers is now configurable using the LogOptions field. However, the default behavior of timeout in 10 seconds is retained.
  • The log command ignores the --follow flag when a task run or pipeline run is complete, and reads available logs instead of live logs.
  • References to the following Tekton resources: EventListener, TriggerBinding, ClusterTriggerBinding, Condition, and TriggerTemplate are now standardized and made consistent across all user-facing messages in tkn commands.
  • Previously, if you started a canceled task run or pipeline run with the --use-taskrun <canceled-task-run-name>, --use-pipelinerun <canceled-pipeline-run-name> or --last flags, the new run would be canceled. This bug is now fixed.
  • The tkn pr desc command is now enhanced to ensure that it does not fail in case of pipeline runs with conditions.
  • When you delete a task run using the tkn tr delete command with the --task option, and a cluster task exists with the same name, the task runs for the cluster task also get deleted. As a workaround, filter the task runs by using the TaskRefKind field.
  • The tkn triggertemplate describe command would display only part of the apiVersion value in the output. For example, only triggers.tekton.dev was displayed instead of triggers.tekton.dev/v1alpha1. This bug is now fixed.
  • The webhook, under certain conditions, would fail to acquire a lease and not function correctly. This bug is now fixed.
  • Pipelines with when expressions created in v0.16.3 can now be run in v0.17.1 and later. After an upgrade, you do not need to reapply pipeline definitions created in previous versions because both the uppercase and lowercase first letters for the annotations are now supported.
  • By default, the leader-election-ha field is now enabled for high availability. When the disable-ha controller flag is set to true, it disables high availability support.
  • Issues with duplicate cloud events are now fixed. Cloud events are now sent only when a condition changes the state, reason, or message.
  • When a service account name is missing from a PipelineRun or TaskRun spec, the controller uses the service account name from the config-defaults config map. If the service account name is also missing in the config-defaults config map, the controller now sets it to default in the spec.
  • Validation for compatibility with the affinity assistant is now supported when the same persistent volume claim is used for multiple workspaces, but with different subpaths.

3.1.7. Release notes for Red Hat OpenShift Pipelines Technology Preview 1.2

3.1.7.1. New features

Red Hat OpenShift Pipelines Technology Preview (TP) 1.2 is now available on OpenShift Container Platform 4.6. Red Hat OpenShift Pipelines TP 1.2 is updated to support:

  • Tekton Pipelines 0.16.3
  • Tekton tkn CLI 0.13.1
  • Tekton Triggers 0.8.1
  • cluster tasks based on Tekton Catalog 0.16
  • IBM Power Systems on OpenShift Container Platform 4.6
  • IBM Z and LinuxONE on OpenShift Container Platform 4.6

In addition to the fixes and stability improvements, the following sections highlight what is new in Red Hat OpenShift Pipelines 1.2.

3.1.7.1.1. Pipelines
  • This release of Red Hat OpenShift Pipelines adds support for a disconnected installation.

    Note

    Installations in restricted environments are currently not supported on IBM Power Systems, IBM Z, and LinuxONE.

  • You can now use the when field, instead of conditions resource, to run a task only when certain criteria are met. The key components of WhenExpression resources are Input, Operator, and Values. If all the when expressions evaluate to True, then the task is run. If any of the when expressions evaluate to False, the task is skipped.
  • Step statuses are now updated if a task run is canceled or times out.
  • Support for Git Large File Storage (LFS) is now available to build the base image used by git-init.
  • You can now use the taskSpec field to specify metadata, such as labels and annotations, when a task is embedded in a pipeline.
  • Cloud events are now supported by pipeline runs. Retries with backoff are now enabled for cloud events sent by the cloud event pipeline resource.
  • You can now set a default Workspace configuration for any workspace that a Task resource declares, but that a TaskRun resource does not explicitly provide.
  • Support is available for namespace variable interpolation for the PipelineRun namespace and TaskRun namespace.
  • Validation for TaskRun objects is now added to check that not more than one persistent volume claim workspace is used when a TaskRun resource is associated with an Affinity Assistant. If more than one persistent volume claim workspace is used, the task run fails with a TaskRunValidationFailed condition. Note that by default, the Affinity Assistant is disabled in Red Hat OpenShift Pipelines, so you will need to enable the assistant to use it.
3.1.7.1.2. Pipelines CLI
  • The tkn task describe, tkn taskrun describe, tkn clustertask describe, tkn pipeline describe, and tkn pipelinerun describe commands now:

    • Automatically select the Task, TaskRun, ClusterTask, Pipeline and PipelineRun resource, respectively, if only one of them is present.
    • Display the results of the Task, TaskRun, ClusterTask, Pipeline and PipelineRun resource in their outputs, respectively.
    • Display workspaces declared in the Task, TaskRun, ClusterTask, Pipeline and PipelineRun resource in their outputs, respectively.
  • You can now use the --prefix-name option with the tkn clustertask start command to specify a prefix for the name of a task run.
  • Interactive mode support has now been provided to the tkn clustertask start command.
  • You can now specify PodTemplate properties supported by pipelines using local or remote file definitions for TaskRun and PipelineRun objects.
  • You can now use the --use-params-defaults option with the tkn clustertask start command to use the default values set in the ClusterTask configuration and create the task run.
  • The --use-param-defaults flag for the tkn pipeline start command now prompts the interactive mode if the default values have not been specified for some of the parameters.
3.1.7.1.3. Triggers
  • The Common Expression Language (CEL) function named parseYAML has been added to parse a YAML string into a map of strings.
  • Error messages for parsing CEL expressions have been improved to make them more granular while evaluating expressions and when parsing the hook body for creating the evaluation environment.
  • Support is now available for marshaling boolean values and maps if they are used as the values of expressions in a CEL overlay mechanism.
  • The following fields have been added to the EventListener object:

    • The replicas field enables the event listener to run more than one pod by specifying the number of replicas in the YAML file.
    • The NodeSelector field enables the EventListener object to schedule the event listener pod to a specific node.
  • Webhook interceptors can now parse the EventListener-Request-URL header to extract parameters from the original request URL being handled by the event listener.
  • Annotations from the event listener can now be propagated to the deployment, services, and other pods. Note that custom annotations on services or deployment are overwritten, and hence, must be added to the event listener annotations so that they are propagated.
  • Proper validation for replicas in the EventListener specification is now available for cases when a user specifies the spec.replicas values as negative or zero.
  • You can now specify the TriggerCRD object inside the EventListener spec as a reference using the TriggerRef field to create the TriggerCRD object separately and then bind it inside the EventListener spec.
  • Validation and defaults for the TriggerCRD object are now available.

3.1.7.2. Deprecated features

  • $(params) parameters are now removed from the triggertemplate resource and replaced by $(tt.params) to avoid confusion between the resourcetemplate and triggertemplate resource parameters.
  • The ServiceAccount reference of the optional EventListenerTrigger-based authentication level has changed from an object reference to a ServiceAccountName string. This ensures that the ServiceAccount reference is in the same namespace as the EventListenerTrigger object.
  • The Conditions custom resource definition (CRD) is now deprecated; use the WhenExpressions CRD instead.
  • The PipelineRun.Spec.ServiceAccountNames object is being deprecated and replaced by the PipelineRun.Spec.TaskRunSpec[].ServiceAccountName object.

3.1.7.3. Known issues

  • This release of Red Hat OpenShift Pipelines adds support for a disconnected installation. However, some images used by the cluster tasks must be mirrored for them to work in disconnected clusters.
  • Pipelines in the openshift namespace are not deleted after you uninstall the Red Hat OpenShift Pipelines Operator. Use the oc delete pipelines -n openshift --all command to delete the pipelines.
  • Uninstalling the Red Hat OpenShift Pipelines Operator does not remove the event listeners.

    As a workaround, to remove the EventListener and Pod CRDs:

    1. Edit the EventListener object with the foregroundDeletion finalizers:

      $ oc patch el/<eventlistener_name> -p '{"metadata":{"finalizers":["foregroundDeletion"]}}' --type=merge

      For example:

      $ oc patch el/github-listener-interceptor -p '{"metadata":{"finalizers":["foregroundDeletion"]}}' --type=merge
    2. Delete the EventListener CRD:

      $ oc patch crd/eventlisteners.triggers.tekton.dev -p '{"metadata":{"finalizers":[]}}' --type=merge
  • When you run a multi-arch container image task without command specification on an IBM Power Systems (ppc64le) or IBM Z (s390x) cluster, the TaskRun resource fails with the following error:

    Error executing command: fork/exec /bin/bash: exec format error

    As a workaround, use an architecture specific container image or specify the sha256 digest to point to the correct architecture. To get the sha256 digest enter:

    $ skopeo inspect --raw <image_name>| jq '.manifests[] | select(.platform.architecture == "<architecture>") | .digest'

3.1.7.4. Fixed issues

  • A simple syntax validation to check the CEL filter, overlays in the Webhook validator, and the expressions in the interceptor has now been added.
  • Triggers no longer overwrite annotations set on the underlying deployment and service objects.
  • Previously, an event listener would stop accepting events. This fix adds an idle timeout of 120 seconds for the EventListener sink to resolve this issue.
  • Previously, canceling a pipeline run with a Failed(Canceled) state gave a success message. This has been fixed to display an error instead.
  • The tkn eventlistener list command now provides the status of the listed event listeners, thus enabling you to easily identify the available ones.
  • Consistent error messages are now displayed for the triggers list and triggers describe commands when triggers are not installed or when a resource cannot be found.
  • Previously, a large number of idle connections would build up during cloud event delivery. The DisableKeepAlives: true parameter was added to the cloudeventclient config to fix this issue. Thus, a new connection is set up for every cloud event.
  • Previously, the creds-init code would write empty files to the disk even if credentials of a given type were not provided. This fix modifies the creds-init code to write files for only those credentials that have actually been mounted from correctly annotated secrets.

3.1.8. Release notes for Red Hat OpenShift Pipelines Technology Preview 1.1

3.1.8.1. New features

Red Hat OpenShift Pipelines Technology Preview (TP) 1.1 is now available on OpenShift Container Platform 4.5. Red Hat OpenShift Pipelines TP 1.1 is updated to support:

  • Tekton Pipelines 0.14.3
  • Tekton tkn CLI 0.11.0
  • Tekton Triggers 0.6.1
  • cluster tasks based on Tekton Catalog 0.14

In addition to the fixes and stability improvements, the following sections highlight what is new in Red Hat OpenShift Pipelines 1.1.

3.1.8.1.1. Pipelines
  • Workspaces can now be used instead of pipeline resources. It is recommended that you use workspaces in OpenShift Pipelines, as pipeline resources are difficult to debug, limited in scope, and make tasks less reusable. For more details on workspaces, see the Understanding OpenShift Pipelines section.
  • Workspace support for volume claim templates has been added:

    • The volume claim template for a pipeline run and task run can now be added as a volume source for workspaces. The tekton-controller then creates a persistent volume claim (PVC) using the template that is seen as a PVC for all task runs in the pipeline. Thus you do not need to define the PVC configuration every time it binds a workspace that spans multiple tasks.
    • Support to find the name of the PVC when a volume claim template is used as a volume source is now available using variable substitution.
  • Support for improving audits:

    • The PipelineRun.Status field now contains the status of every task run in the pipeline and the pipeline specification used to instantiate a pipeline run to monitor the progress of the pipeline run.
    • Pipeline results have been added to the pipeline specification and PipelineRun status.
    • The TaskRun.Status field now contains the exact task specification used to instantiate the TaskRun resource.
  • Support to apply the default parameter to conditions.
  • A task run created by referencing a cluster task now adds the tekton.dev/clusterTask label instead of the tekton.dev/task label.
  • The kube config writer now adds the ClientKeyData and the ClientCertificateData configurations in the resource structure to enable replacement of the pipeline resource type cluster with the kubeconfig-creator task.
  • The names of the feature-flags and the config-defaults config maps are now customizable.
  • Support for the host network in the pod template used by the task run is now available.
  • An Affinity Assistant is now available to support node affinity in task runs that share workspace volume. By default, this is disabled on OpenShift Pipelines.
  • The pod template has been updated to specify imagePullSecrets to identify secrets that the container runtime should use to authorize container image pulls when starting a pod.
  • Support for emitting warning events from the task run controller if the controller fails to update the task run.
  • Standard or recommended k8s labels have been added to all resources to identify resources belonging to an application or component.
  • The Entrypoint process is now notified for signals and these signals are then propagated using a dedicated PID Group of the Entrypoint process.
  • The pod template can now be set on a task level at runtime using task run specs.
  • Support for emitting Kubernetes events:

    • The controller now emits events for additional task run lifecycle events - taskrun started and taskrun running.
    • The pipeline run controller now emits an event every time a pipeline starts.
  • In addition to the default Kubernetes events, support for cloud events for task runs is now available. The controller can be configured to send any task run events, such as create, started, and failed, as cloud events.
  • Support for using the $context.<task|taskRun|pipeline|pipelineRun>.name variable to reference the appropriate name when in pipeline runs and task runs.
  • Validation for pipeline run parameters is now available to ensure that all the parameters required by the pipeline are provided by the pipeline run. This also allows pipeline runs to provide extra parameters in addition to the required parameters.
  • You can now specify tasks within a pipeline that will always execute before the pipeline exits, either after finishing all tasks successfully or after a task in the pipeline failed, using the finally field in the pipeline YAML file.
  • The git-clone cluster task is now available.
3.1.8.1.2. Pipelines CLI
  • Support for embedded trigger binding is now available to the tkn evenlistener describe command.
  • Support to recommend subcommands and make suggestions if an incorrect subcommand is used.
  • The tkn task describe command now auto selects the task if only one task is present in the pipeline.
  • You can now start a task using default parameter values by specifying the --use-param-defaults flag in the tkn task start command.
  • You can now specify a volume claim template for pipeline runs or task runs using the --workspace option with the tkn pipeline start or tkn task start commands.
  • The tkn pipelinerun logs command now displays logs for the final tasks listed in the finally section.
  • Interactive mode support has now been provided to the tkn task start command and the describe subcommand for the following tkn resources: pipeline, pipelinerun, task, taskrun, clustertask, and pipelineresource.
  • The tkn version command now displays the version of the triggers installed in the cluster.
  • The tkn pipeline describe command now displays parameter values and timeouts specified for tasks used in the pipeline.
  • Support added for the --last option for the tkn pipelinerun describe and the tkn taskrun describe commands to describe the most recent pipeline run or task run, respectively.
  • The tkn pipeline describe command now displays the conditions applicable to the tasks in the pipeline.
  • You can now use the --no-headers and --all-namespaces flags with the tkn resource list command.
3.1.8.1.3. Triggers
  • The following Common Expression Language (CEL) functions are now available:

    • parseURL to parse and extract portions of a URL
    • parseJSON to parse JSON value types embedded in a string in the payload field of the deployment webhook
  • A new interceptor for webhooks from Bitbucket has been added.
  • Event listeners now display the Address URL and the Available status as additional fields when listed with the kubectl get command.
  • trigger template params now use the $(tt.params.<paramName>) syntax instead of $(params.<paramName>) to reduce the confusion between trigger template and resource templates params.
  • You can now add tolerations in the EventListener CRD to ensure that event listeners are deployed with the same configuration even if all nodes are tainted due to security or management issues.
  • You can now add a Readiness Probe for event listener Deployment at URL/live.
  • Support for embedding TriggerBinding specifications in event listener triggers is now added.
  • Trigger resources are now annotated with the recommended app.kubernetes.io labels.

3.1.8.2. Deprecated features

The following items are deprecated in this release:

  • The --namespace or -n flags for all cluster-wide commands, including the clustertask and clustertriggerbinding commands, are deprecated. It will be removed in a future release.
  • The name field in triggers.bindings within an event listener has been deprecated in favor of the ref field and will be removed in a future release.
  • Variable interpolation in trigger templates using $(params) has been deprecated in favor of using $(tt.params) to reduce confusion with the pipeline variable interpolation syntax. The $(params.<paramName>) syntax will be removed in a future release.
  • The tekton.dev/task label is deprecated on cluster tasks.
  • The TaskRun.Status.ResourceResults.ResourceRef field is deprecated and will be removed.
  • The tkn pipeline create, tkn task create, and tkn resource create -f subcommands have been removed.
  • Namespace validation has been removed from tkn commands.
  • The default timeout of 1h and the -t flag for the tkn ct start command have been removed.
  • The s2i cluster task has been deprecated.

3.1.8.3. Known issues

  • Conditions do not support workspaces.
  • The --workspace option and the interactive mode is not supported for the tkn clustertask start command.
  • Support of backward compatibility for $(params.<paramName>) syntax forces you to use trigger templates with pipeline specific params as the trigger s webhook is unable to differentiate trigger params from pipelines params.
  • Pipeline metrics report incorrect values when you run a promQL query for tekton_taskrun_count and tekton_taskrun_duration_seconds_count.
  • pipeline runs and task runs continue to be in the Running and Running(Pending) states respectively even when a non existing PVC name is given to a workspace.

3.1.8.4. Fixed issues

  • Previously, the tkn task delete <name> --trs command would delete both the task and cluster task if the name of the task and cluster task were the same. With this fix, the command deletes only the task runs that are created by the task <name>.
  • Previously the tkn pr delete -p <name> --keep 2 command would disregard the -p flag when used with the --keep flag and would delete all the pipeline runs except the latest two. With this fix, the command deletes only the pipeline runs that are created by the pipeline <name>, except for the latest two.
  • The tkn triggertemplate describe output now displays resource templates in a table format instead of YAML format.
  • Previously the buildah cluster task failed when a new user was added to a container. With this fix, the issue has been resolved.

3.1.9. Release notes for Red Hat OpenShift Pipelines Technology Preview 1.0

3.1.9.1. New features

Red Hat OpenShift Pipelines Technology Preview (TP) 1.0 is now available on OpenShift Container Platform 4.4. Red Hat OpenShift Pipelines TP 1.0 is updated to support:

  • Tekton Pipelines 0.11.3
  • Tekton tkn CLI 0.9.0
  • Tekton Triggers 0.4.0
  • cluster tasks based on Tekton Catalog 0.11

In addition to the fixes and stability improvements, the following sections highlight what is new in Red Hat OpenShift Pipelines 1.0.

3.1.9.1.1. Pipelines
  • Support for v1beta1 API Version.
  • Support for an improved limit range. Previously, limit range was specified exclusively for the task run and the pipeline run. Now there is no need to explicitly specify the limit range. The minimum limit range across the namespace is used.
  • Support for sharing data between tasks using task results and task params.
  • Pipelines can now be configured to not overwrite the HOME environment variable and the working directory of steps.
  • Similar to task steps, sidecars now support script mode.
  • You can now specify a different scheduler name in task run podTemplate resource.
  • Support for variable substitution using Star Array Notation.
  • Tekton controller can now be configured to monitor an individual namespace.
  • A new description field is now added to the specification of pipelines, tasks, cluster tasks, resources, and conditions.
  • Addition of proxy parameters to Git pipeline resources.
3.1.9.1.2. Pipelines CLI
  • The describe subcommand is now added for the following tkn resources: EventListener, Condition, TriggerTemplate, ClusterTask, and TriggerSBinding.
  • Support added for v1beta1 to the following resources along with backward compatibility for v1alpha1: ClusterTask, Task, Pipeline, PipelineRun, and TaskRun.
  • The following commands can now list output from all namespaces using the --all-namespaces flag option: tkn task list, tkn pipeline list, tkn taskrun list, tkn pipelinerun list

    The output of these commands is also enhanced to display information without headers using the --no-headers flag option.

  • You can now start a pipeline using default parameter values by specifying --use-param-defaults flag in the tkn pipelines start command.
  • Support for workspace is now added to tkn pipeline start and tkn task start commands.
  • A new clustertriggerbinding command is now added with the following subcommands: describe, delete, and list.
  • You can now directly start a pipeline run using a local or remote yaml file.
  • The describe subcommand now displays an enhanced and detailed output. With the addition of new fields, such as description, timeout, param description, and sidecar status, the command output now provides more detailed information about a specific tkn resource.
  • The tkn task log command now displays logs directly if only one task is present in the namespace.
3.1.9.1.3. Triggers
  • Triggers can now create both v1alpha1 and v1beta1 pipeline resources.
  • Support for new Common Expression Language (CEL) interceptor function - compareSecret. This function securely compares strings to secrets in CEL expressions.
  • Support for authentication and authorization at the event listener trigger level.

3.1.9.2. Deprecated features

The following items are deprecated in this release:

  • The environment variable $HOME, and variable workingDir in the Steps specification are deprecated and might be changed in a future release. Currently in a Step container, the HOME and workingDir variables are overwritten to /tekton/home and /workspace variables, respectively.

    In a later release, these two fields will not be modified, and will be set to values defined in the container image and the Task YAML. For this release, use the disable-home-env-overwrite and disable-working-directory-overwrite flags to disable overwriting of the HOME and workingDir variables.

  • The following commands are deprecated and might be removed in the future release: tkn pipeline create, tkn task create.
  • The -f flag with the tkn resource create command is now deprecated. It might be removed in the future release.
  • The -t flag and the --timeout flag (with seconds format) for the tkn clustertask create command are now deprecated. Only duration timeout format is now supported, for example 1h30s. These deprecated flags might be removed in the future release.

3.1.9.3. Known issues

  • If you are upgrading from an older version of Red Hat OpenShift Pipelines, you must delete your existing deployments before upgrading to Red Hat OpenShift Pipelines version 1.0. To delete an existing deployment, you must first delete Custom Resources and then uninstall the Red Hat OpenShift Pipelines Operator. For more details, see the uninstalling Red Hat OpenShift Pipelines section.
  • Submitting the same v1alpha1 tasks more than once results in an error. Use the oc replace command instead of oc apply when re-submitting a v1alpha1 task.
  • The buildah cluster task does not work when a new user is added to a container.

    When the Operator is installed, the --storage-driver flag for the buildah cluster task is not specified, therefore the flag is set to its default value. In some cases, this causes the storage driver to be set incorrectly. When a new user is added, the incorrect storage-driver results in the failure of the buildah cluster task with the following error:

    useradd: /etc/passwd.8: lock file already used
    useradd: cannot lock /etc/passwd; try again later.

    As a workaround, manually set the --storage-driver flag value to overlay in the buildah-task.yaml file:

    1. Login to your cluster as a cluster-admin:

      $ oc login -u <login> -p <password> https://openshift.example.com:6443
    2. Use the oc edit command to edit buildah cluster task:

      $ oc edit clustertask buildah

      The current version of the buildah clustertask YAML file opens in the editor set by your EDITOR environment variable.

    3. Under the Steps field, locate the following command field:

       command: ['buildah', 'bud', '--format=$(params.FORMAT)', '--tls-verify=$(params.TLSVERIFY)', '--layers', '-f', '$(params.DOCKERFILE)', '-t', '$(resources.outputs.image.url)', '$(params.CONTEXT)']
    4. Replace the command field with the following:

       command: ['buildah', '--storage-driver=overlay', 'bud', '--format=$(params.FORMAT)', '--tls-verify=$(params.TLSVERIFY)', '--no-cache', '-f', '$(params.DOCKERFILE)', '-t', '$(params.IMAGE)', '$(params.CONTEXT)']
    5. Save the file and exit.

    Alternatively, you can also modify the buildah cluster task YAML file directly on the web console by navigating to PipelinesCluster Tasksbuildah. Select Edit Cluster Task from the Actions menu and replace the command field as shown in the previous procedure.

3.1.9.4. Fixed issues

  • Previously, the DeploymentConfig task triggered a new deployment build even when an image build was already in progress. This caused the deployment of the pipeline to fail. With this fix, the deploy task command is now replaced with the oc rollout status command which waits for the in-progress deployment to finish.
  • Support for APP_NAME parameter is now added in pipeline templates.
  • Previously, the pipeline template for Java S2I failed to look up the image in the registry. With this fix, the image is looked up using the existing image pipeline resources instead of the user provided IMAGE_NAME parameter.
  • All the OpenShift Pipelines images are now based on the Red Hat Universal Base Images (UBI).
  • Previously, when the pipeline was installed in a namespace other than tekton-pipelines, the tkn version command displayed the pipeline version as unknown. With this fix, the tkn version command now displays the correct pipeline version in any namespace.
  • The -c flag is no longer supported for the tkn version command.
  • Non-admin users can now list the cluster trigger bindings.
  • The event listener CompareSecret function is now fixed for the CEL Interceptor.
  • The list, describe, and start subcommands for tasks and cluster tasks now correctly display the output in case a task and cluster task have the same name.
  • Previously, the OpenShift Pipelines Operator modified the privileged security context constraints (SCCs), which caused an error during cluster upgrade. This error is now fixed.
  • In the tekton-pipelines namespace, the timeouts of all task runs and pipeline runs are now set to the value of default-timeout-minutes field using the config map.
  • Previously, the pipelines section in the web console was not displayed for non-admin users. This issue is now resolved.

3.2. Understanding OpenShift Pipelines

Red Hat OpenShift Pipelines is a cloud-native, continuous integration and continuous delivery (CI/CD) solution based on Kubernetes resources. It uses Tekton building blocks to automate deployments across multiple platforms by abstracting away the underlying implementation details. Tekton introduces a number of standard custom resource definitions (CRDs) for defining CI/CD pipelines that are portable across Kubernetes distributions.

3.2.1. Key features

  • Red Hat OpenShift Pipelines is a serverless CI/CD system that runs pipelines with all the required dependencies in isolated containers.
  • Red Hat OpenShift Pipelines are designed for decentralized teams that work on microservice-based architecture.
  • Red Hat OpenShift Pipelines use standard CI/CD pipeline definitions that are easy to extend and integrate with the existing Kubernetes tools, enabling you to scale on-demand.
  • You can use Red Hat OpenShift Pipelines 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 OpenShift Container Platform Developer console to create Tekton resources, view logs of pipeline runs, and manage pipelines in your OpenShift Container Platform namespaces.

3.2.2. OpenShift Pipeline Concepts

This guide provides a detailed view of the various pipeline concepts.

3.2.2.1. Tasks

Tasks are the building blocks of a pipeline and consists of sequentially executed steps. It is essentially a function of inputs and outputs. A task can run individually or as a part of the pipeline. Tasks are reusable and can be used in multiple Pipelines.

Steps are a series of commands that are sequentially executed by the task and achieve a specific goal, such as building an image. Every task runs as a pod, and each step runs as a container within that pod. Because steps run within the same pod, they can access the same volumes for caching files, config maps, and secrets.

The following example shows the apply-manifests task.

apiVersion: tekton.dev/v1beta1 1
kind: Task 2
metadata:
  name: apply-manifests 3
spec: 4
  workspaces:
  - name: source
  params:
    - name: manifest_dir
      description: The directory in source that contains yaml manifests
      type: string
      default: "k8s"
  steps:
    - name: apply
      image: image-registry.openshift-image-registry.svc:5000/openshift/cli:latest
      workingDir: /workspace/source
      command: ["/bin/bash", "-c"]
      args:
        - |-
          echo Applying manifests in $(params.manifest_dir) directory
          oc apply -f $(params.manifest_dir)
          echo -----------------------------------
1
The task API version, v1beta1.
2
The type of Kubernetes object, Task.
3
The unique name of this task.
4
The list of parameters and steps in the task and the workspace used by the task.

This task starts the pod and runs a container inside that pod using the specified image to run the specified commands.

Note

Starting with Pipelines 1.6, the following defaults from the step YAML file are removed:

  • The HOME environment variable does not default to the /tekton/home directory
  • The workingDir field does not default to the /workspace directory

Instead, the container for the step defines the HOME environment variable and the workingDir field. However, you can override the default values by specifying the custom values in the YAML file for the step.

As a temporary measure, to maintain backward compatibility with the older Pipelines versions, you can set the following fields in the TektonConfig custom resource definition to false:

spec:
  pipeline:
    disable-working-directory-overwrite: false
    disable-home-env-overwrite: false

3.2.2.2. 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.

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 OpenShift Container Platform 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.

3.2.2.3. 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.

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.

3.2.2.4. TaskRun

A TaskRun instantiates a Task for execution with specific inputs, outputs, and execution parameters on a cluster. It can be invoked on its own or as part of a PipelineRun for each Task in a pipeline.

A Task consists of one or more Steps that execute container images, and each container image performs a specific piece of build work. A TaskRun executes the Steps in a Task in the specified order, until all Steps execute successfully or a failure occurs. A TaskRun is automatically created by a PipelineRun for each Task in a Pipeline.

The following example shows a TaskRun that runs the apply-manifests Task with the relevant input parameters:

apiVersion: tekton.dev/v1beta1 1
kind: TaskRun 2
metadata:
  name: apply-manifests-taskrun 3
spec: 4
  serviceAccountName: pipeline
  taskRef: 5
    kind: Task
    name: apply-manifests
  workspaces: 6
  - name: source
    persistentVolumeClaim:
      claimName: source-pvc
1
TaskRun API version v1beta1.
2
Specifies the type of Kubernetes object. In this example, TaskRun.
3
Unique name to identify this TaskRun.
4
Definition of the TaskRun. For this TaskRun, the Task and the required workspace are specified.
5
Name of the Task reference used for this TaskRun. This TaskRun executes the apply-manifests Task.
6
Workspace used by the TaskRun.

3.2.2.5. Pipelines

A Pipeline is a collection of Task resources arranged in a specific order of execution. They are executed to construct complex workflows that automate the build, deployment and delivery of applications. You can define a CI/CD workflow for your application using pipelines containing one or more tasks.

A Pipeline resource definition consists of a number of fields or attributes, which together enable the pipeline to accomplish a specific goal. Each Pipeline resource definition must contain at least one Task resource, which ingests specific inputs and produces specific outputs. The pipeline definition can also optionally include Conditions, Workspaces, Parameters, or Resources depending on the application requirements.

The following example shows the build-and-deploy pipeline, which builds an application image from a Git repository using the buildah ClusterTask resource:

apiVersion: tekton.dev/v1beta1 1
kind: Pipeline 2
metadata:
  name: build-and-deploy 3
spec: 4
  workspaces: 5
  - name: shared-workspace
  params: 6
  - 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: "pipelines-1.6"
  - name: IMAGE
    type: string
    description: image to be built from the code
  tasks: 7
  - 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 8
    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 9
    taskRef:
      name: apply-manifests
    workspaces:
    - name: source
      workspace: shared-workspace
    runAfter: 10
    - 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
1
Pipeline API version v1beta1.
2
Specifies the type of Kubernetes object. In this example, Pipeline.
3
Unique name of this Pipeline.
4
Specifies the definition and structure of the Pipeline.
5
Workspaces used across all the Tasks in the Pipeline.
6
Parameters used across all the Tasks in the Pipeline.
7
Specifies the list of Tasks used in the Pipeline.
8
Task build-image, which uses the buildah ClusterTask to build application images from a given Git repository.
9
Task apply-manifests, which uses a user-defined Task with the same name.
10
Specifies the sequence in which Tasks are run in a Pipeline. In this example, the apply-manifests Task is run only after the build-image Task is completed.

3.2.2.6. PipelineRun

A PipelineRun is a type of resource that binds a pipeline, workspaces, credentials, and a set of parameter values specific to a scenario to run the CI/CD workflow.

A pipeline run is the running instance of a pipeline. It instantiates a pipeline for execution with specific inputs, outputs, and execution parameters on a cluster. It also creates a task run for each task in the pipeline run.

The pipeline runs the tasks sequentially until they are complete or a task fails. The status field tracks and the progress of each task run and stores it for monitoring and auditing purposes.

The following example runs the build-and-deploy pipeline with relevant resources and parameters:

apiVersion: tekton.dev/v1beta1 1
kind: PipelineRun 2
metadata:
  name: build-deploy-api-pipelinerun 3
spec:
  pipelineRef:
    name: build-and-deploy 4
  params: 5
  - name: deployment-name
    value: vote-api
  - name: git-url
    value: https://github.com/openshift-pipelines/vote-api.git
  - name: IMAGE
    value: image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/vote-api
  workspaces: 6
  - name: shared-workspace
    volumeClaimTemplate:
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 500Mi
1
Pipeline run API version v1beta1.
2
The type of Kubernetes object. In this example, PipelineRun.
3
Unique name to identify this pipeline run.
4
Name of the pipeline to be run. In this example, build-and-deploy.
5
The list of parameters required to run the pipeline.
6
Workspace used by the pipeline run.

3.2.2.7. Workspaces

Note

It is recommended that you use Workspaces instead of PipelineResources in OpenShift Pipelines, as PipelineResources are difficult to debug, limited in scope, and make Tasks less reusable.

Workspaces declare shared storage volumes that a Task in a Pipeline needs at runtime to receive input or provide output. Instead of specifying the actual location of the volumes, Workspaces enable you to declare the filesystem or parts of the filesystem that would be required at runtime. A Task or Pipeline declares the Workspace and you must provide the specific location details of the volume. It is then mounted into that Workspace in a TaskRun or a PipelineRun. This separation of volume declaration from runtime storage volumes makes the Tasks reusable, flexible, and independent of the user environment.

With Workspaces, you can:

  • Store Task inputs and outputs
  • Share data among Tasks
  • Use it as a mount point for credentials held in Secrets
  • Use it as a mount point for configurations held in ConfigMaps
  • Use it as a mount point for common tools shared by an organization
  • Create a cache of build artifacts that speed up jobs

You can specify Workspaces in the TaskRun or PipelineRun using:

  • A read-only ConfigMaps or Secret
  • An existing PersistentVolumeClaim shared with other Tasks
  • A PersistentVolumeClaim from a provided VolumeClaimTemplate
  • An emptyDir that is discarded when the TaskRun completes

The following example shows a code snippet of the build-and-deploy Pipeline, which declares a shared-workspace Workspace for the build-image and apply-manifests Tasks as defined in the Pipeline.

apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: build-and-deploy
spec:
  workspaces: 1
  - name: shared-workspace
  params:
...
  tasks: 2
  - name: build-image
    taskRef:
      name: buildah
      kind: ClusterTask
    params:
    - name: TLSVERIFY
      value: "false"
    - name: IMAGE
      value: $(params.IMAGE)
    workspaces: 3
    - name: source 4
      workspace: shared-workspace 5
    runAfter:
    - fetch-repository
  - name: apply-manifests
    taskRef:
      name: apply-manifests
    workspaces: 6
    - name: source
      workspace: shared-workspace
    runAfter:
      - build-image
...
1
List of Workspaces shared between the Tasks defined in the Pipeline. A Pipeline can define as many Workspaces as required. In this example, only one Workspace named shared-workspace is declared.
2
Definition of Tasks used in the Pipeline. This snippet defines two Tasks, build-image and apply-manifests, which share a common Workspace.
3
List of Workspaces used in the build-image Task. A Task definition can include as many Workspaces as it requires. However, it is recommended that a Task uses at most one writable Workspace.
4
Name that uniquely identifies the Workspace used in the Task. This Task uses one Workspace named source.
5
Name of the Pipeline Workspace used by the Task. Note that the Workspace source in turn uses the Pipeline Workspace named shared-workspace.
6
List of Workspaces used in the apply-manifests Task. Note that this Task shares the source Workspace with the build-image Task.

Workspaces help tasks share data, and allow you to specify one or more volumes that each task in the pipeline requires during execution. You can create a persistent volume claim or provide a volume claim template that creates a persistent volume claim for you.

The following code snippet of the build-deploy-api-pipelinerun PipelineRun uses a volume claim template to create a persistent volume claim for defining the storage volume for the shared-workspace Workspace used in the build-and-deploy Pipeline.

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: build-deploy-api-pipelinerun
spec:
  pipelineRef:
    name: build-and-deploy
  params:
...

  workspaces: 1
  - name: shared-workspace 2
    volumeClaimTemplate: 3
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 500Mi
1
Specifies the list of Pipeline Workspaces for which volume binding will be provided in the PipelineRun.
2
The name of the Workspace in the Pipeline for which the volume is being provided.
3
Specifies a volume claim template that creates a persistent volume claim to define the storage volume for the workspace.

3.2.2.8. Triggers

Use Triggers in conjunction with pipelines to create a full-fledged CI/CD system where Kubernetes resources define the entire CI/CD execution. Triggers capture the external events, such as a Git pull request, and process them to extract key pieces of information. Mapping this event data to a set of predefined parameters triggers a series of tasks that can then create and deploy Kubernetes resources and instantiate the pipeline.

For example, you define a CI/CD workflow using Red Hat OpenShift Pipelines for your application. The pipeline must start for any new changes to take effect in the application repository. Triggers automate this process by capturing and processing any change event and by triggering a pipeline run that deploys the new image with the latest changes.

Triggers consist of the following main resources that work together to form a reusable, decoupled, and self-sustaining CI/CD system:

  • The TriggerBinding resource extracts the fields from an event payload and stores them as parameters.

    The following example shows a code snippet of the TriggerBinding resource, which extracts the Git repository information from the received event payload:

    apiVersion: triggers.tekton.dev/v1beta1 1
    kind: TriggerBinding 2
    metadata:
      name: vote-app 3
    spec:
      params: 4
      - name: git-repo-url
        value: $(body.repository.url)
      - name: git-repo-name
        value: $(body.repository.name)
      - name: git-revision
        value: $(body.head_commit.id)
    1
    The API version of the TriggerBinding resource. In this example, v1beta1.
    2
    Specifies the type of Kubernetes object. In this example, TriggerBinding.
    3
    Unique name to identify the TriggerBinding resource.
    4
    List of parameters which will be extracted from the received event payload and passed to the TriggerTemplate resource. In this example, the Git repository URL, name, and revision are extracted from the body of the event payload.
  • The TriggerTemplate resource acts as a standard for the way resources must be created. It specifies the way parameterized data from the TriggerBinding resource should be used. A trigger template receives input from the trigger binding, and then performs a series of actions that results in creation of new pipeline resources, and initiation of a new pipeline run.

    The following example shows a code snippet of a TriggerTemplate resource, which creates a pipeline run using the Git repository information received from the TriggerBinding resource you just created:

    apiVersion: triggers.tekton.dev/v1beta1 1
    kind: TriggerTemplate 2
    metadata:
      name: vote-app 3
    spec:
      params: 4
      - name: git-repo-url
        description: The git repository url
      - name: git-revision
        description: The git revision
        default: pipelines-1.6
      - name: git-repo-name
        description: The name of the deployment to be created / patched
    
      resourcetemplates: 5
      - apiVersion: tekton.dev/v1beta1
        kind: PipelineRun
        metadata:
          name: build-deploy-$(tt.params.git-repo-name)-$(uid)
        spec:
          serviceAccountName: pipeline
          pipelineRef:
            name: build-and-deploy
          params:
          - name: deployment-name
            value: $(tt.params.git-repo-name)
          - name: git-url
            value: $(tt.params.git-repo-url)
          - name: git-revision
            value: $(tt.params.git-revision)
          - name: IMAGE
            value: image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/$(tt.params.git-repo-name)
          workspaces:
          - name: shared-workspace
            volumeClaimTemplate:
             spec:
              accessModes:
               - ReadWriteOnce
              resources:
                requests:
                  storage: 500Mi
    1
    The API version of the TriggerTemplate resource. In this example, v1beta1.
    2
    Specifies the type of Kubernetes object. In this example, TriggerTemplate.
    3
    Unique name to identify the TriggerTemplate resource.
    4
    Parameters supplied by the TriggerBinding resource.
    5
    List of templates that specify the way resources must be created using the parameters received through the TriggerBinding or EventListener resources.
  • The Trigger resource combines the TriggerBinding and TriggerTemplate resources, and optionally, the interceptors event processor.

    Interceptors process all the events for a specific platform that runs before the TriggerBinding resource. You can use interceptors to filter the payload, verify events, define and test trigger conditions, and implement other useful processing. Interceptors use secret for event verification. Once the event data passes through an interceptor, it then goes to the trigger before you pass the payload data to the trigger binding. You can also use an interceptor to modify the behavior of the associated trigger referenced in the EventListener specification.

    The following example shows a code snippet of a Trigger resource, named vote-trigger that connects the TriggerBinding and TriggerTemplate resources, and the interceptors event processor.

    apiVersion: triggers.tekton.dev/v1beta1 1
    kind: Trigger 2
    metadata:
      name: vote-trigger 3
    spec:
      serviceAccountName: pipeline 4
      interceptors:
        - ref:
            name: "github" 5
          params: 6
            - name: "secretRef"
              value:
                secretName: github-secret
                secretKey: secretToken
            - name: "eventTypes"
              value: ["push"]
      bindings:
        - ref: vote-app 7
      template: 8
         ref: vote-app
    ---
    apiVersion: v1
    kind: Secret 9
    metadata:
      name: github-secret
    type: Opaque
    stringData:
      secretToken: "1234567"
    1
    The API version of the Trigger resource. In this example, v1beta1.
    2
    Specifies the type of Kubernetes object. In this example, Trigger.
    3
    Unique name to identify the Trigger resource.
    4
    Service account name to be used.
    5
    Interceptor name to be referenced. In this example, github.
    6
    Desired parameters to be specified.
    7
    Name of the TriggerBinding resource to be connected to the TriggerTemplate resource.
    8
    Name of the TriggerTemplate resource to be connected to the TriggerBinding resource.
    9
    Secret to be used to verify events.
  • The EventListener resource provides an endpoint, or an event sink, that listens for incoming HTTP-based events with a JSON payload. It extracts event parameters from each TriggerBinding resource, and then processes this data to create Kubernetes resources as specified by the corresponding TriggerTemplate resource. The EventListener resource also performs lightweight event processing or basic filtering on the payload using event interceptors, which identify the type of payload and optionally modify it. Currently, pipeline triggers support five types of interceptors: Webhook Interceptors, GitHub Interceptors, GitLab Interceptors, Bitbucket Interceptors, and Common Expression Language (CEL) Interceptors.

    The following example shows an EventListener resource, which references the Trigger resource named vote-trigger.

    apiVersion: triggers.tekton.dev/v1beta1 1
    kind: EventListener 2
    metadata:
      name: vote-app 3
    spec:
      serviceAccountName: pipeline 4
      triggers:
        - triggerRef: vote-trigger 5
    1
    The API version of the EventListener resource. In this example, v1beta1.
    2
    Specifies the type of Kubernetes object. In this example, EventListener.
    3
    Unique name to identify the EventListener resource.
    4
    Service account name to be used.
    5
    Name of the Trigger resource referenced by the EventListener resource.

3.2.3. Additional resources

3.3. Installing OpenShift Pipelines

This guide walks cluster administrators through the process of installing the Red Hat OpenShift Pipelines Operator to an OpenShift Container Platform cluster.

Prerequisites

  • You have access to an OpenShift Container Platform cluster using an account with cluster-admin permissions.
  • You have installed oc CLI.
  • You have installed OpenShift Pipelines (tkn) CLI on your local system.

3.3.1. Installing the Red Hat OpenShift Pipelines Operator in web console

You can install Red Hat OpenShift Pipelines using the Operator listed in the OpenShift Container Platform OperatorHub. When you install the Red Hat OpenShift Pipelines Operator, the custom resources (CRs) required for the pipelines configuration are automatically installed along with the Operator.

The default Operator custom resource definition (CRD) config.operator.tekton.dev is now replaced by tektonconfigs.operator.tekton.dev. In addition, the Operator provides the following additional CRDs to individually manage OpenShift Pipelines components: tektonpipelines.operator.tekton.dev, tektontriggers.operator.tekton.dev and tektonaddons.operator.tekton.dev.

If you have OpenShift Pipelines already installed on your cluster, the existing installation is seamlessly upgraded. The Operator will replace the instance of config.operator.tekton.dev on your cluster with an instance of tektonconfigs.operator.tekton.dev and additional objects of the other CRDs as necessary.

Warning

If you manually changed your existing installation, such as, changing the target namespace in the config.operator.tekton.dev CRD instance by making changes to the resource name - cluster field, then the upgrade path is not smooth. In such cases, the recommended workflow is to uninstall your installation and reinstall the Red Hat OpenShift Pipelines Operator.

The Red Hat OpenShift Pipelines Operator now provides the option to choose the components that you want to install by specifying profiles as part of the TektonConfig CR. The TektonConfig CR is automatically installed when the Operator is installed. The supported profiles are:

  • Lite: This installs only Tekton Pipelines.
  • Basic: This installs Tekton Pipelines and Tekton Triggers.
  • All: This is the default profile used when the TektonConfig CR is installed. This profile installs all of the Tekton components: Tekton Pipelines, Tekton Triggers, Tekton Addons (which include ClusterTasks, ClusterTriggerBindings, ConsoleCLIDownload, ConsoleQuickStart and ConsoleYAMLSample resources).

Procedure

  1. In the Administrator perspective of the web console, navigate to OperatorsOperatorHub.
  2. Use the Filter by keyword box to search for Red Hat OpenShift Pipelines Operator in the catalog. Click the Red Hat OpenShift Pipelines Operator tile.
  3. Read the brief description about the Operator on the Red Hat OpenShift Pipelines Operator page. Click Install.
  4. On the Install Operator page:

    1. Select All namespaces on the cluster (default) for the Installation Mode. This mode installs the Operator in the default openshift-operators namespace, which enables the Operator to watch and be made available to all namespaces in the cluster.
    2. Select Automatic for the Approval Strategy. This ensures that the future upgrades to the Operator are handled automatically by the Operator Lifecycle Manager (OLM). If you select the Manual approval strategy, OLM creates an update request. As a cluster administrator, you must then manually approve the OLM update request to update the Operator to the new version.
    3. Select an Update Channel.

      • The stable channel enables installation of the latest stable and supported release of the Red Hat OpenShift Pipelines Operator.
      • The preview channel enables installation of the latest preview version of the Red Hat OpenShift Pipelines Operator, which may contain features that are not yet available from the stable channel and is not supported.
  5. Click Install. You will see the Operator listed on the Installed Operators page.

    Note

    The Operator is installed automatically into the openshift-operators namespace.

  6. Verify that the Status is set to Succeeded Up to date to confirm successful installation of Red Hat OpenShift Pipelines Operator.

3.3.2. Installing the OpenShift Pipelines Operator using the CLI

You can install Red Hat OpenShift Pipelines Operator from the OperatorHub using the CLI.

Procedure

  1. Create a Subscription object YAML file to subscribe a namespace to the Red Hat OpenShift Pipelines Operator, for example, sub.yaml:

    Example Subscription

    apiVersion: operators.coreos.com/v1alpha1
    kind: Subscription
    metadata:
      name: openshift-pipelines-operator
      namespace: openshift-operators
    spec:
      channel:  <channel name> 1
      name: openshift-pipelines-operator-rh 2
      source: redhat-operators 3
      sourceNamespace: openshift-marketplace 4

    1
    Specify the channel name from where you want to subscribe the Operator
    2
    Name of the Operator to subscribe to.
    3
    Name of the CatalogSource that provides the Operator.
    4
    Namespace of the CatalogSource. Use openshift-marketplace for the default OperatorHub CatalogSources.
  2. Create the Subscription object:

    $ oc apply -f sub.yaml

    The Red Hat OpenShift Pipelines Operator is now installed in the default target namespace openshift-operators.

3.3.3. Red Hat OpenShift Pipelines Operator in a restricted environment

The Red Hat OpenShift Pipelines Operator enables support for installation of pipelines in a restricted network environment.

The Operator installs a proxy webhook that sets the proxy environment variables in the containers of the pod created by tekton-controllers based on the cluster proxy object. It also sets the proxy environment variables in the TektonPipelines, TektonTriggers, Controllers, Webhooks, and Operator Proxy Webhook resources.

By default, the proxy webhook is disabled for the openshift-pipelines namespace. To disable it for any other namespace, you can add the operator.tekton.dev/disable-proxy: true label to the namespace object.

3.3.4. Additional Resources

3.4. Uninstalling OpenShift Pipelines

Uninstalling the Red Hat OpenShift Pipelines Operator is a two-step process:

  1. Delete the Custom Resources (CRs) that were added by default when you installed the Red Hat OpenShift Pipelines Operator.
  2. Uninstall the Red Hat OpenShift Pipelines Operator.

Uninstalling only the Operator will not remove the Red Hat OpenShift Pipelines components created by default when the Operator is installed.

3.4.1. Deleting the Red Hat OpenShift Pipelines components and Custom Resources

Delete the Custom Resources (CRs) created by default during installation of the Red Hat OpenShift Pipelines Operator.

Procedure

  1. In the Administrator perspective of the web console, navigate to AdministrationCustom Resource Definition.
  2. Type config.operator.tekton.dev in the Filter by name box to search for the Red Hat OpenShift Pipelines Operator CRs.
  3. Click CRD Config to see the Custom Resource Definition Details page.
  4. Click the Actions drop-down menu and select Delete Custom Resource Definition.

    Note

    Deleting the CRs will delete the Red Hat OpenShift Pipelines components, and all the Tasks and Pipelines on the cluster will be lost.

  5. Click Delete to confirm the deletion of the CRs.

3.4.2. Uninstalling the Red Hat OpenShift Pipelines Operator

Procedure

  1. From the OperatorsOperatorHub page, use the Filter by keyword box to search for Red Hat OpenShift Pipelines Operator.
  2. Click the OpenShift Pipelines Operator tile. The Operator tile indicates it is installed.
  3. In the OpenShift Pipelines Operator descriptor page, click Uninstall.

Additional Resources

3.5. Creating CI/CD solutions for applications using OpenShift Pipelines

With Red Hat OpenShift Pipelines, you can create a customized CI/CD solution to build, test, and deploy your application.

To create a full-fledged, self-serving CI/CD pipeline for an application, perform the following tasks:

  • Create custom tasks, or install existing reusable tasks.
  • Create and define the delivery pipeline for your application.
  • Provide a storage volume or filesystem that is attached to a workspace for the pipeline execution, using one of the following approaches:

    • Specify a volume claim template that creates a persistent volume claim
    • Specify a persistent volume claim
  • Create a PipelineRun object to instantiate and invoke the pipeline.
  • Add triggers to capture events in the source repository.

This section uses the pipelines-tutorial example to demonstrate the preceding tasks. The example uses a simple application which consists of:

  • A front-end interface, pipelines-vote-ui, with the source code in the pipelines-vote-ui Git repository.
  • A back-end interface, pipelines-vote-api, with the source code in the pipelines-vote-api Git repository.
  • The apply-manifests and update-deployment tasks in the pipelines-tutorial Git repository.

3.5.1. Prerequisites

  • You have access to an OpenShift Container Platform cluster.
  • You have installed OpenShift Pipelines using the Red Hat OpenShift Pipelines Operator listed in the OpenShift OperatorHub. After it is installed, it is applicable to the entire cluster.
  • You have installed OpenShift Pipelines CLI.
  • You have forked the front-end pipelines-vote-ui and back-end pipelines-vote-api Git repositories using your GitHub ID, and have administrator access to these repositories.
  • Optional: You have cloned the pipelines-tutorial Git repository.

3.5.2. Creating a project and checking your pipeline service account

Procedure

  1. Log in to your OpenShift Container Platform cluster:

    $ oc login -u <login> -p <password> https://openshift.example.com:6443
  2. Create a project for the sample application. For this example workflow, create the pipelines-tutorial project:

    $ oc new-project pipelines-tutorial
    Note

    If you create a project with a different name, be sure to update the resource URLs used in the example with your project name.

  3. View the pipeline service account:

    Red Hat OpenShift Pipelines Operator adds and configures a service account named pipeline that has sufficient permissions to build and push an image. This service account is used by the PipelineRun object.

    $ oc get serviceaccount pipeline

3.5.3. Creating pipeline tasks

Procedure

  1. Install the apply-manifests and update-deployment task resources from the pipelines-tutorial repository, which contains a list of reusable tasks for pipelines:

    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/pipelines-1.6/01_pipeline/01_apply_manifest_task.yaml
    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/pipelines-1.6/01_pipeline/02_update_deployment_task.yaml
  2. Use the tkn task list command to list the tasks you created:

    $ tkn task list

    The output verifies that the apply-manifests and update-deployment task resources were created:

    NAME                DESCRIPTION   AGE
    apply-manifests                   1 minute ago
    update-deployment                 48 seconds ago
  3. Use the tkn clustertasks list command to list the Operator-installed additional cluster tasks such as buildah and s2i-python:

    Note

    To use the buildah cluster task in a restricted environment, you must ensure that the Dockerfile uses an internal image stream as the base image.

    $ tkn clustertasks list

    The output lists the Operator-installed ClusterTask resources:

    NAME                       DESCRIPTION   AGE
    buildah                                  1 day ago
    git-clone                                1 day ago
    s2i-python                               1 day ago
    tkn                                      1 day ago

3.5.4. Assembling a pipeline

A pipeline represents a CI/CD flow and is defined by the tasks to be executed. It is designed to be generic and reusable in multiple applications and environments.

A pipeline specifies how the tasks interact with each other and their order of execution using the from and runAfter parameters. It uses the workspaces field to specify one or more volumes that each task in the pipeline requires during execution.

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

The pipeline performs the following tasks for the back-end application pipelines-vote-api and front-end application pipelines-vote-ui:

  • Clones the source code of the application from the Git repository by referring to the git-url and git-revision parameters.
  • Builds the container image using the buildah cluster task.
  • Pushes the image to the internal image registry by referring to the image parameter.
  • Deploys the new image on OpenShift Container Platform by using the apply-manifests and update-deployment tasks.

Procedure

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

    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: "pipelines-1.6"
      - name: IMAGE
        type: string
        description: image to be built 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: 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
        params:
        - name: deployment
          value: $(params.deployment-name)
        - name: IMAGE
          value: $(params.IMAGE)
        runAfter:
        - apply-manifests

    The pipeline definition abstracts away the specifics of the Git source repository and image registries. These details are added as params when a pipeline is triggered and executed.

  2. Create the pipeline:

    $ oc create -f <pipeline-yaml-file-name.yaml>

    Alternatively, you can also execute the YAML file directly from the Git repository:

    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/pipelines-1.6/01_pipeline/04_pipeline.yaml
  3. Use the tkn pipeline list command to verify that the pipeline is added to the application:

    $ tkn pipeline list

    The output verifies that the build-and-deploy pipeline was created:

    NAME               AGE            LAST RUN   STARTED   DURATION   STATUS
    build-and-deploy   1 minute ago   ---        ---       ---        ---

3.5.5. Mirroring images to run pipelines in a restricted environment

To run OpenShift Pipelines in a disconnected cluster or a cluster provisioned in a restricted environment, ensure that either the Samples Operator is configured for a restricted network, or a cluster administrator has created a cluster with a mirrored registry.

The following procedure uses the pipelines-tutorial example to create a pipeline for an application in a restricted environment using a cluster with a mirrored registry. To ensure that the pipelines-tutorial example works in a restricted environment, you must mirror the respective builder images from the mirror registry for the front-end interface, pipelines-vote-ui; back-end interface, pipelines-vote-api; and the cli.

Procedure

  1. Mirror the builder image from the mirror registry for the front-end interface, pipelines-vote-ui.

    1. Verify that the required images tag is not imported:

      $ oc describe imagestream python -n openshift

      Example output

      Name:			python
      Namespace:		openshift
      [...]
      
      3.8-ubi8 (latest)
        tagged from registry.redhat.io/ubi8/python-38:latest
          prefer registry pullthrough when referencing this tag
      
        Build and run Python 3.8 applications on UBI 8. For more information about using this builder image, including OpenShift considerations, see https://github.com/sclorg/s2i-python-container/blob/master/3.8/README.md.
        Tags: builder, python
        Supports: python:3.8, python
        Example Repo: https://github.com/sclorg/django-ex.git
      
      [...]

    2. Mirror the supported image tag to the private registry:

      $ oc image mirror registry.redhat.io/ubi8/python-38:latest <mirror-registry>:<port>/ubi8/python-38
    3. Import the image:

      $ oc tag <mirror-registry>:<port>/ubi8/python-38 python:latest --scheduled -n openshift

      You must periodically re-import the image. The --scheduled flag enables automatic re-import of the image.

    4. Verify that the images with the given tag have been imported:

      $ oc describe imagestream python -n openshift

      Example output

      Name:			python
      Namespace:		openshift
      [...]
      
      latest
        updates automatically from registry <mirror-registry>:<port>/ubi8/python-38
      
        * <mirror-registry>:<port>/ubi8/python-38@sha256:3ee3c2e70251e75bfeac25c0c33356add9cc4abcbc9c51d858f39e4dc29c5f58
      
      [...]

  2. Mirror the builder image from the mirror registry for the back-end interface, pipelines-vote-api.

    1. Verify that the required images tag is not imported:

      $ oc describe imagestream golang -n openshift

      Example output

      Name:			golang
      Namespace:		openshift
      [...]
      
      1.14.7-ubi8 (latest)
        tagged from registry.redhat.io/ubi8/go-toolset:1.14.7
          prefer registry pullthrough when referencing this tag
      
        Build and run Go applications on UBI 8. For more information about using this builder image, including OpenShift considerations, see https://github.com/sclorg/golang-container/blob/master/README.md.
        Tags: builder, golang, go
        Supports: golang
        Example Repo: https://github.com/sclorg/golang-ex.git
      
      [...]

    2. Mirror the supported image tag to the private registry:

      $ oc image mirror registry.redhat.io/ubi8/go-toolset:1.14.7 <mirror-registry>:<port>/ubi8/go-toolset
    3. Import the image:

      $ oc tag <mirror-registry>:<port>/ubi8/go-toolset golang:latest --scheduled -n openshift

      You must periodically re-import the image. The --scheduled flag enables automatic re-import of the image.

    4. Verify that the images with the given tag have been imported:

      $ oc describe imagestream golang -n openshift

      Example output

      Name:			golang
      Namespace:		openshift
      [...]
      
      latest
        updates automatically from registry <mirror-registry>:<port>/ubi8/go-toolset
      
        * <mirror-registry>:<port>/ubi8/go-toolset@sha256:59a74d581df3a2bd63ab55f7ac106677694bf612a1fe9e7e3e1487f55c421b37
      
      [...]

  3. Mirror the builder image from the mirror registry for the cli.

    1. Verify that the required images tag is not imported:

      $ oc describe imagestream cli -n openshift

      Example output

      Name:                   cli
      Namespace:              openshift
      [...]
      
      latest
        updates automatically from registry quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:65c68e8c22487375c4c6ce6f18ed5485915f2bf612e41fef6d41cbfcdb143551
      
        * quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:65c68e8c22487375c4c6ce6f18ed5485915f2bf612e41fef6d41cbfcdb143551
      
      [...]

    2. Mirror the supported image tag to the private registry:

      $ oc image mirror quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:65c68e8c22487375c4c6ce6f18ed5485915f2bf612e41fef6d41cbfcdb143551 <mirror-registry>:<port>/openshift-release-dev/ocp-v4.0-art-dev:latest
    3. Import the image:

      $ oc tag <mirror-registry>:<port>/openshift-release-dev/ocp-v4.0-art-dev cli:latest --scheduled -n openshift

      You must periodically re-import the image. The --scheduled flag enables automatic re-import of the image.

    4. Verify that the images with the given tag have been imported:

      $ oc describe imagestream cli -n openshift

      Example output

      Name:                   cli
      Namespace:              openshift
      [...]
      
      latest
        updates automatically from registry <mirror-registry>:<port>/openshift-release-dev/ocp-v4.0-art-dev
      
        * <mirror-registry>:<port>/openshift-release-dev/ocp-v4.0-art-dev@sha256:65c68e8c22487375c4c6ce6f18ed5485915f2bf612e41fef6d41cbfcdb143551
      
      [...]

3.5.6. Running a pipeline

A PipelineRun resource starts a pipeline and ties it to the Git and image resources that should be used for the specific invocation. It automatically creates and starts the TaskRun resources for each task in the pipeline.

Procedure

  1. Start the pipeline for the back-end application:

    $ tkn pipeline start build-and-deploy \
        -w name=shared-workspace,volumeClaimTemplateFile=https://raw.githubusercontent.com/openshift/pipelines-tutorial/pipelines-1.6/01_pipeline/03_persistent_volume_claim.yaml \
        -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/pipelines-vote-api \
        --use-param-defaults

    The previous command uses a volume claim template, which creates a persistent volume claim for the pipeline execution.

  2. To track the progress of the pipeline run, enter the following command::

    $ tkn pipelinerun logs <pipelinerun_id> -f

    The <pipelinerun_id> in the above command is the ID for the PipelineRun that was returned in the output of the previous command.

  3. Start the pipeline for the front-end application:

    $ tkn pipeline start build-and-deploy \
        -w name=shared-workspace,volumeClaimTemplateFile=https://raw.githubusercontent.com/openshift/pipelines-tutorial/pipelines-1.6/01_pipeline/03_persistent_volume_claim.yaml \
        -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/pipelines-vote-ui \
        --use-param-defaults
  4. To track the progress of the pipeline run, enter the following command:

    $ tkn pipelinerun logs <pipelinerun_id> -f

    The <pipelinerun_id> in the above command is the ID for the PipelineRun that was returned in the output of the previous command.

  5. After a few minutes, use tkn pipelinerun list command to verify that the pipeline ran successfully by listing all the pipeline runs:

    $ tkn pipelinerun list

    The output lists the pipeline runs:

     NAME                         STARTED      DURATION     STATUS
     build-and-deploy-run-xy7rw   1 hour ago   2 minutes    Succeeded
     build-and-deploy-run-z2rz8   1 hour ago   19 minutes   Succeeded
  6. Get the application route:

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

    Note the output of the previous command. You can access the application using this route.

  7. To rerun the last pipeline run, using the pipeline resources and service account of the previous pipeline, run:

    $ tkn pipeline start build-and-deploy --last

3.5.7. Adding triggers to a pipeline

Triggers enable pipelines to respond to external GitHub events, such as push events and pull requests. After you assemble and start a pipeline for the application, add the TriggerBinding, TriggerTemplate, Trigger, and EventListener resources to capture the GitHub events.

Procedure

  1. Copy the content of the following sample TriggerBinding YAML file and save it:

    apiVersion: triggers.tekton.dev/v1beta1
    kind: TriggerBinding
    metadata:
      name: vote-app
    spec:
      params:
      - name: git-repo-url
        value: $(body.repository.url)
      - name: git-repo-name
        value: $(body.repository.name)
      - name: git-revision
        value: $(body.head_commit.id)
  2. Create the TriggerBinding resource:

    $ oc create -f <triggerbinding-yaml-file-name.yaml>

    Alternatively, you can create the TriggerBinding resource directly from the pipelines-tutorial Git repository:

    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/pipelines-1.6/03_triggers/01_binding.yaml
  3. Copy the content of the following sample TriggerTemplate YAML file and save it:

    apiVersion: triggers.tekton.dev/v1beta1
    kind: TriggerTemplate
    metadata:
      name: vote-app
    spec:
      params:
      - name: git-repo-url
        description: The git repository url
      - name: git-revision
        description: The git revision
        default: pipelines-1.6
      - name: git-repo-name
        description: The name of the deployment to be created / patched
    
      resourcetemplates:
      - apiVersion: tekton.dev/v1beta1
        kind: PipelineRun
        metadata:
          generateName: build-deploy-$(tt.params.git-repo-name)-
        spec:
          serviceAccountName: pipeline
          pipelineRef:
            name: build-and-deploy
          params:
          - name: deployment-name
            value: $(tt.params.git-repo-name)
          - name: git-url
            value: $(tt.params.git-repo-url)
          - name: git-revision
            value: $(tt.params.git-revision)
          - name: IMAGE
            value: image-registry.openshift-image-registry.svc:5000/pipelines-tutorial/$(tt.params.git-repo-name)
          workspaces:
          - name: shared-workspace
            volumeClaimTemplate:
              spec:
                accessModes:
                  - ReadWriteOnce
                resources:
                  requests:
                    storage: 500Mi

    The template specifies a volume claim template to create a persistent volume claim for defining the storage volume for the workspace. Therefore, you do not need to create a persistent volume claim to provide data storage.

  4. Create the TriggerTemplate resource:

    $ oc create -f <triggertemplate-yaml-file-name.yaml>

    Alternatively, you can create the TriggerTemplate resource directly from the pipelines-tutorial Git repository:

    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/pipelines-1.6/03_triggers/02_template.yaml
  5. Copy the contents of the following sample Trigger YAML file and save it:

    apiVersion: triggers.tekton.dev/v1beta1
    kind: Trigger
    metadata:
      name: vote-trigger
    spec:
      serviceAccountName: pipeline
      bindings:
        - ref: vote-app
      template:
        ref: vote-app
  6. Create the Trigger resource:

    $ oc create -f <trigger-yaml-file-name.yaml>

    Alternatively, you can create the Trigger resource directly from the pipelines-tutorial Git repository:

    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/pipelines-1.6/03_triggers/03_trigger.yaml
  7. Copy the contents of the following sample EventListener YAML file and save it:

    apiVersion: triggers.tekton.dev/v1beta1
    kind: EventListener
    metadata:
      name: vote-app
    spec:
      serviceAccountName: pipeline
      triggers:
        - triggerRef: vote-trigger

    Alternatively, if you have not defined a trigger custom resource, add the binding and template spec to the EventListener YAML file, instead of referring to the name of the trigger:

    apiVersion: triggers.tekton.dev/v1beta1
    kind: EventListener
    metadata:
      name: vote-app
    spec:
      serviceAccountName: pipeline
      triggers:
      - bindings:
        - ref: vote-app
        template:
          ref: vote-app
  8. Create the EventListener resource by performing the following steps:

    • To create an EventListener resource using a secure HTTPS connection:

      1. Add a label to enable the secure HTTPS connection to the Eventlistener resource:

        $ oc label namespace <ns-name> operator.tekton.dev/enable-annotation=enabled
      2. Create the EventListener resource:

        $ oc create -f <eventlistener-yaml-file-name.yaml>

        Alternatively, you can create the EvenListener resource directly from the pipelines-tutorial Git repository:

        $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/pipelines-1.6/03_triggers/04_event_listener.yaml
      3. Create a route with the re-encrypt TLS termination:

        $ oc create route reencrypt --service=<svc-name> --cert=tls.crt --key=tls.key --ca-cert=ca.crt --hostname=<hostname>

        Alternatively, you can create a re-encrypt TLS termination YAML file to create a secured route.

        Example Re-encrypt TLS Termination YAML of the Secured Route

        apiVersion: v1
        kind: Route
        metadata:
          name: route-passthrough-secured 1
        spec:
          host: <hostname>
          to:
            kind: Service
            name: frontend 2
          tls:
            termination: reencrypt         3
            key: [as in edge termination]
            certificate: [as in edge termination]
            caCertificate: [as in edge termination]
            destinationCACertificate: |-   4
              -----BEGIN CERTIFICATE-----
              [...]
              -----END CERTIFICATE-----

        1 2
        The name of the object, which is limited to 63 characters.
        3
        The termination field is set to reencrypt. This is the only required tls field.
        4
        Required for re-encryption. destinationCACertificate specifies a CA certificate to validate the endpoint certificate, securing the connection from the router to the destination pods. If the service is using a service signing certificate, or the administrator has specified a default CA certificate for the router and the service has a certificate signed by that CA, this field can be omitted.

        See oc create route reencrypt --help for more options.

    • To create an EventListener resource using an insecure HTTP connection:

      1. Create the EventListener resource.
      2. Expose the EventListener service as an OpenShift Container Platform route to make it publicly accessible:

        $ oc expose svc el-vote-app

3.5.8. Creating webhooks

Webhooks are HTTP POST messages that are received by the event listeners whenever a configured event occurs in your repository. The event payload is then mapped to trigger bindings, and processed by trigger templates. The trigger templates eventually start one or more pipeline runs, leading to the creation and deployment of Kubernetes resources.

In this section, you will configure a webhook URL on your forked Git repositories pipelines-vote-ui and pipelines-vote-api. This URL points to the publicly accessible EventListener service route.

Note

Adding webhooks requires administrative privileges to the repository. If you do not have administrative access to your repository, contact your system administrator for adding webhooks.

Procedure

  1. Get the webhook URL:

    • For a secure HTTPS connection:

      $ echo "URL: $(oc  get route el-vote-app --template='https://{{.spec.host}}')"
    • For an HTTP (insecure) connection:

      $ echo "URL: $(oc  get route el-vote-app --template='http://{{.spec.host}}')"

      Note the URL obtained in the output.

  2. Configure webhooks manually on the front-end repository:

    1. Open the front-end Git repository pipelines-vote-ui in your browser.
    2. Click SettingsWebhooksAdd Webhook
    3. On the Webhooks/Add Webhook page:

      1. Enter the webhook URL from step 1 in Payload URL field
      2. Select application/json for the Content type
      3. Specify the secret in the Secret field
      4. Ensure that the Just the push event is selected
      5. Select Active
      6. Click Add Webhook
  3. Repeat step 2 for the back-end repository pipelines-vote-api.

3.5.9. Triggering a pipeline run

Whenever a push event occurs in the Git repository, the configured webhook sends an event payload to the publicly exposed EventListener service route. The EventListener service of the application processes the payload, and passes it to the relevant TriggerBinding and TriggerTemplate resource pairs. The TriggerBinding resource extracts the parameters, and the TriggerTemplate resource uses these parameters and specifies the way the resources must be created. This may rebuild and redeploy the application.

In this section, you push an empty commit to the front-end pipelines-vote-ui repository, which then triggers the pipeline run.

Procedure

  1. From the terminal, clone your forked Git repository pipelines-vote-ui:

    $ git clone git@github.com:<your GitHub ID>/pipelines-vote-ui.git -b pipelines-1.6
  2. Push an empty commit:

    $ git commit -m "empty-commit" --allow-empty && git push origin pipelines-1.6
  3. Check if the pipeline run was triggered:

    $ tkn pipelinerun list

    Notice that a new pipeline run was initiated.

3.5.10. Additional resources

3.6. Working with Red Hat OpenShift Pipelines using the Developer perspective

You can use the Developer perspective of the OpenShift Container Platform web console to create CI/CD pipelines for your software delivery process.

In the Developer perspective:

  • Use the AddPipelinePipeline Builder option to create customized pipelines for your application.
  • Use the AddFrom Git option to create pipelines using operator-installed pipeline templates and resources while creating an application on OpenShift Container Platform.

After you create the pipelines for your application, you can view and visually interact with the deployed pipelines in the Pipelines view. You can also use the Topology view to interact with the pipelines created using the From Git option. You need to apply custom labels to a pipeline created using the Pipeline Builder to see it in the Topology view.

Prerequisites

  • You have access to an OpenShift Container Platform cluster and have switched to the Developer perspective in the web console.
  • You have the OpenShift Pipelines Operator installed in your cluster.
  • You are a cluster administrator or a user with create and edit permissions.
  • You have created a project.

3.6.1. Constructing Pipelines using the Pipeline Builder

In the Developer perspective of the console, you can use the +AddPipelinePipeline builder option to:

  • Configure pipelines using either the Pipeline builder or the YAML view.
  • Construct a pipeline flow using existing tasks and cluster tasks. When you install the OpenShift Pipelines Operator, it adds reusable pipeline cluster tasks to your cluster.
  • Specify the type of resources required for the pipeline run, and if required, add additional parameters to the pipeline.
  • Reference these pipeline resources in each of the tasks in the pipeline as input and output resources.
  • If required, reference any additional parameters added to the pipeline in the task. The parameters for a task are prepopulated based on the specifications of the task.
  • Use the Operator-installed, reusable snippets and samples to create detailed pipelines.

Procedure

  1. In the +Add view of the Developer perspective, click the Pipeline tile to see the Pipeline builder page.
  2. Configure the pipeline using either the Pipeline builder view or the YAML view.

    Note

    The Pipeline builder view supports a limited number of fields whereas the YAML view supports all available fields. Optionally, you can also use the Operator-installed, reusable snippets and samples to create detailed Pipelines.

    Figure 3.1. YAML view

    op pipeline yaml

    Configure your pipeline using the Pipeline Builder:

    1. In the Name field, enter a unique name for the pipeline.
    2. In the Tasks section:

      1. Click Add task.
      2. Search for a task using the quick search field and select the required task from the displayed list.
      3. Click Add or Install and add. In this example, use the s2i-nodejs task.

        Note

        The search list contains all the Tekton Hub tasks and tasks available in the cluster. Also, if a task is already installed it will show Add to add the task whereas it will show Install and add to install and add the task. It will show Update and add when you add the same task with an updated version.

        • To add sequential tasks to the pipeline:

          • Click the plus icon to the right or left of the task → click Add task.
          • Search for a task using the quick search field and select the required task from the displayed list.
          • Click Add or Install and add.

            Figure 3.2. Pipeline Builder

            op pipeline builder
        • To add a final task:

          • Click the Add finally task → Click Add task.
          • Search for a task using the quick search field and select the required task from the displayed list.
          • Click Add or Install and add.
    3. In the Resources section, click Add Resources to specify the name and type of resources for the pipeline run. These resources are then used by the tasks in the pipeline as inputs and outputs. For this example:

      1. Add an input resource. In the Name field, enter Source, and then from the Resource Type drop-down list, select Git.
      2. Add an output resource. In the Name field, enter Img, and then from the Resource Type drop-down list, select Image.

        Note

        A red icon appears next to the task if a resource is missing.

    4. Optional: The Parameters for a task are pre-populated based on the specifications of the task. If required, use the Add Parameters link in the Parameters section to add additional parameters.
    5. In the Workspaces section, click Add workspace and enter a unique workspace name in the Name field. You can add multiple workspaces to the pipeline.
    6. In the Tasks section, click the s2i-nodejs task to see the side panel with details for the task. In the task side panel, specify the resources and parameters for the s2i-nodejs task:

      1. If required, in the Parameters section, add more parameters to the default ones, by using the $(params.<param-name>) syntax.
      2. In the Image section, enter Img as specified in the Resources section.
      3. Select a workspace from the source drop-down under Workspaces section.
    7. Add resources, parameters, and workspaces to the openshift-client task.
  3. Click Create to create and view the pipeline in the Pipeline Details page.
  4. Click the Actions drop-down menu then click Start, to see the Start Pipeline page.
  5. The Workspaces section lists the workspaces you created earlier. Use the respective drop-down to specify the volume source for your workspace. You have the following options: Empty Directory, Config Map, Secret, PersistentVolumeClaim, or VolumeClaimTemplate.

3.6.2. Creating applications with OpenShift Pipelines

To create pipelines along with applications, use the From Git option in the Add view of the Developer perspective. For more information, see Creating applications using the Developer perspective.

3.6.3. Interacting with pipelines using the Developer perspective

The Pipelines view in the Developer perspective lists all the pipelines in a project, along with the following details:

  • The namespace in which the pipeline was created
  • The last pipeline run
  • The status of the tasks in the pipeline run
  • The status of the pipeline run
  • The creation time of the last pipeline run

Procedure

  1. In the Pipelines view of the Developer perspective, select a project from the Project drop-down list to see the pipelines in that project.
  2. 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.

    Figure 3.3. Pipeline details

    Pipeline details
  3. 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.

  4. Optional: Click the YAML tab to edit the YAML file for the pipeline.
  5. 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.

    • 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.

  6. Click the Parameters tab to see the parameters defined in the pipeline. You can also add or edit additional parameters, as required.
  7. Click the Resources tab to see the resources defined in the pipeline. You can also add or edit additional resources, as required.

3.6.4. Using a custom pipeline template for creating and deploying an application from a Git repository

As a cluster administrator, to create and deploy an application from a Git repository, you can use custom pipeline templates that override the default pipeline templates provided by Red Hat OpenShift Pipelines 1.5 and later.

Note

This feature is unavailable in Red Hat OpenShift Pipelines 1.4 and earlier versions.

Prerequisites

Ensure that the Red Hat OpenShift Pipelines 1.5 or later is installed and available in all namespaces.

Procedure

  1. Log in to the OpenShift Container Platform web console as a cluster administrator.
  2. In the Administrator perspective, use the left navigation panel to go to the Pipelines section.

    1. From the Project drop-down, select the openshift project. This ensures that the subsequent steps are performed in the openshift namespace.
    2. From the list of available pipelines, select a pipeline that is appropriate for building and deploying your application. For example, if your application requires a node.js runtime environment, select the s2i-nodejs pipeline.

      Note

      Do not edit the default pipeline template. It may become incompatible with the UI and the back-end.

    3. Under the YAML tab of the selected pipeline, click Download and save the YAML file to your local machine. If your custom configuration file fails, you can use this copy to restore a working configuration.
  3. Disable (delete) the default pipeline templates:

    1. Use the left navigation panel to go to OperatorsInstalled Operators.
    2. Click Red Hat OpenShift PipelinesTekton Configuration tab → configYAML tab.
    3. To disable (delete) the default pipeline templates in the openshift namespace, set the pipelineTemplates parameter to false in the TektonConfig custom resource YAML, and save it.

      apiVersion: operator.tekton.dev/v1alpha1
      kind: TektonConfig
      metadata:
        name: config
      spec:
      profile: all
      targetNamespace: openshift-pipelines
      addon:
        params:
        - name: clusterTasks
          value: "true"
        - name: pipelineTemplates
          value: "false"
      ...
      Note

      If you manually delete the default pipeline templates, the operator will restore the defaults during an upgrade.

      Warning

      As a cluster admin, you can disable installation of the default pipeline templates in the operator configuration. However, such a configuration will disable (delete) all default pipeline templates, and not only the one you want to customize.

  4. Create a custom pipeline template:

    1. Use the left navigation panel to go to the Pipelines section.
    2. From the Create drop-down, select Pipeline.
    3. Create the required pipeline in the openshift namespace. Give it a different name than the default one (for example, custom-nodejs). You can use the downloaded default pipeline template as a starting point and customize it.

      Note

      Because openshift is the default namespace used by the operator-installed pipeline templates, you must create the custom pipeline template in the openshift namespace. When an application uses a pipeline template, the template is automatically copied to the respective project’s namespace.

    4. Under the Details tab of the created pipeline, ensure that the Labels in the custom template match the labels in the default pipeline. The custom pipeline template must have the correct labels for the runtime, type, and strategy of the application. For example, the required labels for a node.js application deployed on OpenShift Container Platform are as follows:

      ...
      pipeline.openshift.io/runtime: nodejs
      pipeline.openshift.io/type: openshift
      ...
      Note

      You can use only one pipeline template for each combination of runtime environment and deployment type.

  5. In the Developer perspective, use the +AddGit RepositoryFrom Git option to select the kind of application you want to create and deploy. Based on the required runtime and type of the application, your custom template is automatically selected.

3.6.5. Starting pipelines

After you create a pipeline, you need to start it to execute the included tasks in the defined sequence. You can start a pipeline from the Pipelines view, the Pipeline Details page, or the Topology view.

Procedure

To start a pipeline using the Pipelines view:

  1. In the Pipelines view of the Developer perspective, click the Options kebab menu adjoining a pipeline, and select Start.
  2. The Start Pipeline dialog box displays the Git Resources and the Image Resources based on the pipeline definition.

    Note

    For pipelines created using the From Git option, the Start Pipeline dialog box also displays an APP_NAME field in the Parameters section, and all the fields in the dialog box are prepopulated by the pipeline template.

    1. If you have resources in your namespace, the Git Resources and the Image Resources fields are prepopulated with those resources. If required, use the drop-downs to select or create the required resources and customize the pipeline run instance.
  3. Optional: Modify the Advanced Options to add the credentials that authenticate the specified private Git server or the image registry.

    1. Under Advanced Options, click Show Credentials Options and select Add Secret.
    2. In the Create Source Secret section, specify the following:

      1. A unique Secret Name for the secret.
      2. In the Designated provider to be authenticated section, specify the provider to be authenticated in the Access to field, and the base Server URL.
      3. Select the Authentication Type and provide the credentials:

        • For the Authentication Type Image Registry Credentials, specify the Registry Server Address that you want to authenticate, and provide your credentials in the Username, Password, and Email fields.

          Select Add Credentials if you want to specify an additional Registry Server Address.

        • For the Authentication Type Basic Authentication, specify the values for the UserName and Password or Token fields.
        • For the Authentication Type SSH Keys, specify the value of the SSH Private Key field.

          Note

          For basic authentication and SSH authentication, you can use annotations such as:

      4. Select the check mark to add the secret.

    You can add multiple secrets based upon the number of resources in your pipeline.

  4. Click Start to start the pipeline.
  5. The Pipeline Run Details page displays the pipeline being executed. After the pipeline starts, the tasks and steps within each task are executed. You can:

    • Hover over the tasks to see the time taken to execute each step.
    • Click on a task to see the logs for each step in the task.
    • Click the Logs tab to see the logs relating to the execution sequence of the tasks. You can also expand the pane and download the logs individually or in bulk, by using the relevant button.
    • Click the Events tab to see the stream of events generated by a pipeline run.

      You can use the Task Runs, Logs, and Events tabs to assist in debugging a failed pipeline run or a failed task run.

      Figure 3.4. Pipeline run details

      Pipeline run details
  6. For pipelines created using the From Git option, you can use the Topology view to interact with pipelines after you start them:

    Note

    To see the pipelines created using the Pipeline Builder in the Topology view, customize the pipeline labels to link the pipeline with the application workload.

    1. On the left navigation panel, click Topology, and click on the application to see the pipeline runs listed in the side panel.
    2. In the Pipeline Runs section, click Start Last Run to start a new pipeline run with the same parameters and resources as the previous one. This option is disabled if a pipeline run has not been initiated.

      Figure 3.5. Pipelines in Topology view

      Pipelines in Topology view
    3. In the Topology page, hover to the left of the application to see the status of the pipeline run for the application.

      Note

      The side panel of the application node in the Topology page displays a Log Snippet when a pipeline run fails on a specific task run. You can view the Log Snippet in the Pipeline Runs section, under the Resources tab. 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.

3.6.6. Editing Pipelines

You can edit the Pipelines in your cluster using the Developer perspective of the web console:

Procedure

  1. In the Pipelines view of the Developer perspective, select the Pipeline you want to edit to see the details of the Pipeline. In the Pipeline Details page, click Actions and select Edit Pipeline.
  2. In the Pipeline Builder page:

    • You can add additional Tasks, parameters, or resources to the Pipeline.
    • You can click the Task you want to modify to see the Task details in the side panel and modify the required Task details, such as the display name, parameters and resources.
    • Alternatively, to delete the Task, click the Task, and in the side panel, click Actions and select Remove Task.
  3. Click Save to save the modified Pipeline.

3.6.7. Deleting Pipelines

You can delete the Pipelines in your cluster using the Developer perspective of the web console.

Procedure

  1. In the Pipelines view of the Developer perspective, click the Options kebab menu adjoining a Pipeline, and select Delete Pipeline.
  2. In the Delete Pipeline confirmation prompt, click Delete to confirm the deletion.

3.7. Reducing resource consumption of OpenShift Pipelines

If you use clusters in multi-tenant environments you must control the consumption of CPU, memory, and storage resources for each project and Kubernetes object. This helps prevent any one application from consuming too many resources and affecting other applications.

To define the final resource limits that are set on the resulting pods, Red Hat OpenShift Pipelines use resource quota limits and limit ranges of the project in which they are executed.

To restrict resource consumption in your project, you can:

3.7.1. Understanding resource consumption in pipelines

Each task consists of a number of required steps to be executed in a particular order defined in the steps field of the Task resource. Every task runs as a pod, and each step runs as a container within that pod.

Steps are executed one at a time. The pod that executes the task only requests enough resources to run a single container image (step) in the task at a time, and thus does not store resources for all the steps in the task.

The Resources field in the steps spec specifies the limits for resource consumption. By default, the resource requests for the CPU, memory, and ephemeral storage are set to BestEffort (zero) values or to the minimums set through limit ranges in that project.

Example configuration of resource requests and limits for a step

spec:
  steps:
  - name: <step_name>
    resources:
      requests:
        memory: 2Gi
        cpu: 600m
      limits:
        memory: 4Gi
        cpu: 900m

When the LimitRange parameter and the minimum values for container resource requests are specified in the project in which the pipeline and task runs are executed, Red Hat OpenShift Pipelines looks at all the LimitRange values in the project and uses the minimum values instead of zero.

Example configuration of limit range parameters at a project level

apiVersion: v1
kind: LimitRange
metadata:
  name: <limit_container_resource>
spec:
  limits:
  - max:
      cpu: "600m"
      memory: "2Gi"
    min:
      cpu: "200m"
      memory: "100Mi"
    default:
      cpu: "500m"
      memory: "800Mi"
    defaultRequest:
      cpu: "100m"
      memory: "100Mi"
    type: Container
...

3.7.2. Mitigating extra resource consumption in pipelines

When you have resource limits set on the containers in your pod, OpenShift Container Platform sums up the resource limits requested as all containers run simultaneously.

To consume the minimum amount of resources needed to execute one step at a time in the invoked task, Red Hat OpenShift Pipelines requests the maximum CPU, memory, and ephemeral storage as specified in the step that requires the most amount of resources. This ensures that the resource requirements of all the steps are met. Requests other than the maximum values are set to zero.

However, this behavior can lead to higher resource usage than required. If you use resource quotas, this could also lead to unschedulable pods.

For example, consider a task with two steps that uses scripts, and that does not define any resource limits and requests. The resulting pod has two init containers (one for entrypoint copy, the other for writing scripts) and two containers, one for each step.

OpenShift Container Platform uses the limit range set up for the project to compute required resource requests and limits. For this example, set the following limit range in the project:

apiVersion: v1
kind: LimitRange
metadata:
  name: mem-min-max-demo-lr
spec:
  limits:
  - max:
      memory: 1Gi
    min:
      memory: 500Mi
    type: Container

In this scenario, each init container uses a request memory of 1Gi (the max limit of the limit range), and each container uses a request memory of 500Mi. Thus, the total memory request for the pod is 2Gi.

If the same limit range is used with a task of ten steps, the final memory request is 5Gi, which is higher than what each step actually needs, that is 500Mi (since each step runs after the other).

Thus, to reduce resource consumption of resources, you can:

  • Reduce the number of steps in a given task by grouping different steps into one bigger step, using the script feature, and the same image. This reduces the minimum requested resource.
  • Distribute steps that are relatively independent of each other and can run on their own to multiple tasks instead of a single task. This lowers the number of steps in each task, making the request for each task smaller, and the scheduler can then run them when the resources are available.

3.7.3. Additional resources

3.8. Setting compute resource quota for OpenShift Pipelines

A ResourceQuota object in Red Hat OpenShift Pipelines controls the total resource consumption per namespace. You can use it to limit the quantity of objects created in a namespace, based on the type of the object. In addition, you can specify a compute resource quota to restrict the total amount of compute resources consumed in a namespace.

However, you might want to limit the amount of compute resources consumed by pods resulting from a pipeline run, rather than setting quotas for the entire namespace. Currently, Red Hat OpenShift Pipelines does not enable you to directly specify the compute resource quota for a pipeline.

3.8.1. Alternative approaches for limiting compute resource consumption in OpenShift Pipelines

To attain some degree of control over the usage of compute resources by a pipeline, consider the following alternative approaches:

  • Set resource requests and limits for each step in a task.

    Example: Set resource requests and limits for each step in a task.

    ...
    spec:
      steps:
        - name: step-with-limts
          resources:
            requests:
              memory: 1Gi
              cpu: 500m
            limits:
              memory: 2Gi
              cpu: 800m
    ...

  • Set resource limits by specifying values for the LimitRange object. For more information on LimitRange, refer to Restrict resource consumption with limit ranges.
  • Reduce pipeline resource consumption.
  • Set and manage resource quotas per project.
  • Ideally, the compute resource quota for a pipeline should be same as the total amount of compute resources consumed by the concurrently running pods in a pipeline run. However, the pods running the tasks consume compute resources based on the use case. For example, a Maven build task might require different compute resources for different applications that it builds. As a result, you cannot predetermine the compute resource quotas for tasks in a generic pipeline. For greater predictability and control over usage of compute resources, use customized pipelines for different applications.
Note

When using Red Hat OpenShift Pipelines in a namespace configured with a ResourceQuota object, the pods resulting from task runs and pipeline runs might fail with an error, such as: failed quota: <quota name> must specify cpu, memory.

To avoid this error, do any one of the following:

  • (Recommended) Specify a limit range for the namespace.
  • Explicitly define requests and limits for all containers.

For more information, refer to the issue and the resolution.

If your use case is not addressed by these approaches, you can implement a workaround by using a resource quota for a priority class.

3.8.2. Specifying pipelines resource quota using priority class

A PriorityClass object maps priority class names to the integer values that indicates their relative priorities. Higher values increase the priority of a class. After you create a priority class, you can create pods that specify the priority class name in their specifications. In addition, you can control a pod’s consumption of system resources based on the pod’s priority.

Specifying resource quota for a pipeline is similar to setting a resource quota for the subset of pods created by a pipeline run. The following steps provide an example of the workaround by specifying resource quota based on priority class.

Procedure

  1. Create a priority class for a pipeline.

    Example: Priority class for a pipeline

    apiVersion: scheduling.k8s.io/v1
    kind: PriorityClass
    metadata:
      name: pipeline1-pc
    value: 1000000
    description: "Priority class for pipeline1"

  2. Create a resource quota for a pipeline.

    Example: Resource quota for a pipeline

    apiVersion: v1
    kind: ResourceQuota
    metadata:
      name: pipeline1-rq
    spec:
      hard:
        cpu: "1000"
        memory: 200Gi
        pods: "10"
      scopeSelector:
        matchExpressions:
        - operator : In
          scopeName: PriorityClass
          values: ["pipeline1-pc"]

  3. Verify the resource quota usage for the pipeline.

    Example: Verify resource quota usage for the pipeline

    $ kubectl describe quota
    
    Name:       pipeline1-rq
    Namespace:  default
    Resource    Used  Hard
    --------    ----  ----
    cpu         0     1k
    memory      0     200Gi
    pods        0     10

    Because pods are not running, the quota is unused.

  4. Create the pipelines and tasks.

    Example: YAML for the pipeline

    apiVersion: tekton.dev/v1alpha1
    kind: Pipeline
    metadata:
      name: maven-build
    spec:
      workspaces:
      - name: local-maven-repo
      resources:
      - name: app-git
        type: git
      tasks:
      - name: build
        taskRef:
          name: mvn
        resources:
          inputs:
          - name: source
            resource: app-git
        params:
        - name: GOALS
          value: ["package"]
        workspaces:
        - name: maven-repo
          workspace: local-maven-repo
      - name: int-test
        taskRef:
          name: mvn
        runAfter: ["build"]
        resources:
          inputs:
          - name: source
            resource: app-git
        params:
        - name: GOALS
          value: ["verify"]
        workspaces:
        - name: maven-repo
          workspace: local-maven-repo
      - name: gen-report
        taskRef:
          name: mvn
        runAfter: ["build"]
        resources:
          inputs:
          - name: source
            resource: app-git
        params:
        - name: GOALS
          value: ["site"]
        workspaces:
        - name: maven-repo
          workspace: local-maven-repo

    Example: YAML for a task in the pipeline

    apiVersion: tekton.dev/v1alpha1
    kind: Task
    metadata:
      name: mvn
    spec:
      workspaces:
      - name: maven-repo
      inputs:
        params:
        - name: GOALS
          description: The Maven goals to run
          type: array
          default: ["package"]
        resources:
        - name: source
          type: git
      steps:
        - name: mvn
          image: gcr.io/cloud-builders/mvn
          workingDir: /workspace/source
          command: ["/usr/bin/mvn"]
          args:
            - -Dmaven.repo.local=$(workspaces.maven-repo.path)
            - "$(inputs.params.GOALS)"
          priorityClassName: pipeline1-pc

    Note

    Ensure that all tasks in the pipeline belongs to the same priority class.

  5. Create and start the pipeline run.

    Example: YAML for a pipeline run

    apiVersion: tekton.dev/v1alpha1
    kind: PipelineRun
    metadata:
      generateName: petclinic-run-
    spec:
      pipelineRef:
        name: maven-build
      resources:
      - name: app-git
        resourceSpec:
          type: git
          params:
            - name: url
              value: https://github.com/spring-projects/spring-petclinic

  6. After the pods are created, verify the resource quota usage for the pipeline run.

    Example: Verify resource quota usage for the pipeline

    $ kubectl describe quota
    
    Name:       pipeline1-rq
    Namespace:  default
    Resource    Used  Hard
    --------    ----  ----
    cpu         500m  1k
    memory      10Gi  200Gi
    pods        1     10

    The output indicates that you can manage the combined resource quota for all concurrent running pods belonging to a priority class, by specifying the resource quota per priority class.

3.8.3. Additional resources

3.9. Using pods in a privileged security context

The default configuration of OpenShift Pipelines 1.3.x and later versions does not allow you to run pods with privileged security context, if the pods result from pipeline run or task run. For such pods, the default service account is pipeline, and the security context constraint (SCC) associated with the pipelines service account is pipelines-scc. The pipelines-scc SCC is similar to the anyuid SCC, but with a minor difference as defined in the YAML file for the SCC of pipelines:

Example SecurityContextConstraints object

apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
...
fsGroup:
  type: MustRunAs
...

In addition, the Buildah cluster task, shipped as part of the OpenShift Pipelines, uses vfs as the default storage driver.

3.9.1. Running pipeline run and task run pods with privileged security context

Procedure

To run a pod (resulting from pipeline run or task run) with the privileged security context, do the following modifications:

  • Configure the associated user account or service account to have an explicit SCC. You can perform the configuration using any of the following methods:

    • Run the following command:

      $ oc adm policy add-scc-to-user <scc-name> -z <service-account-name>
    • Alternatively, modify the YAML files for RoleBinding, and Role or ClusterRole:

      Example RoleBinding object

      apiVersion: rbac.authorization.k8s.io/v1
      kind: RoleBinding
      metadata:
        name: service-account-name 1
        namespace: default
      roleRef:
        apiGroup: rbac.authorization.k8s.io
        kind: ClusterRole
        name: pipelines-scc-clusterrole 2
      subjects:
      - kind: ServiceAccount
        name: pipeline
        namespace: default

      1
      Substitute with an appropriate service account name.
      2
      Substitute with an appropriate cluster role based on the role binding you use.

      Example ClusterRole object

      apiVersion: rbac.authorization.k8s.io/v1
      kind: ClusterRole
      metadata:
        name: pipelines-scc-clusterrole 1
      rules:
      - apiGroups:
        - security.openshift.io
        resourceNames:
        - nonroot
        resources:
        - securitycontextconstraints
        verbs:
        - use

      1
      Substitute with an appropriate cluster role based on the role binding you use.
    Note

    As a best practice, create a copy of the default YAML files and make changes in the duplicate file.

  • If you do not use the vfs storage driver, configure the service account associated with the task run or the pipeline run to have a privileged SCC, and set the security context as privileged: true.

3.9.2. Running pipeline run and task run by using a custom SCC and a custom service account

When using the pipelines-scc security context constraint (SCC) associated with the default pipelines service account, the pipeline run and task run pods may face timeouts. This happens because in the default pipelines-scc SCC, the fsGroup.type parameter is set to MustRunAs.

Note

For more information about pod timeouts, see BZ#1995779.

To avoid pod timeouts, you can create a custom SCC with the fsGroup.type parameter set to RunAsAny, and associate it with a custom service account.

Note

As a best practice, use a custom SCC and a custom service account for pipeline runs and task runs. This approach allows greater flexibility and does not break the runs when the defaults are modified during an upgrade.

Procedure

  1. Define a custom SCC with the fsGroup.type parameter set to RunAsAny:

    Example: Custom SCC

    apiVersion: security.openshift.io/v1
    kind: SecurityContextConstraints
    metadata:
      annotations:
        kubernetes.io/description: my-scc is a close replica of anyuid scc. pipelines-scc has fsGroup - RunAsAny.
      name: my-scc
    allowHostDirVolumePlugin: false
    allowHostIPC: false
    allowHostNetwork: false
    allowHostPID: false
    allowHostPorts: false
    allowPrivilegeEscalation: true
    allowPrivilegedContainer: false
    allowedCapabilities: null
    defaultAddCapabilities: null
    fsGroup:
      type: RunAsAny
    groups:
    - system:cluster-admins
    priority: 10
    readOnlyRootFilesystem: false
    requiredDropCapabilities:
    - MKNOD
    runAsUser:
      type: RunAsAny
    seLinuxContext:
      type: MustRunAs
    supplementalGroups:
      type: RunAsAny
    volumes:
    - configMap
    - downwardAPI
    - emptyDir
    - persistentVolumeClaim
    - projected
    - secret

  2. Create the custom SCC:

    Example: Create the my-scc SCC

    $ oc create -f my-scc.yaml

  3. Create a custom service account:

    Example: Create a fsgroup-runasany service account

    $ oc create serviceaccount fsgroup-runasany

  4. Associate the custom SCC with the custom service account:

    Example: Associate the my-scc SCC with the fsgroup-runasany service account

    $ oc adm policy add-scc-to-user my-scc -z fsgroup-runasany

    If you want to use the custom service account for privileged tasks, you can associate the privileged SCC with the custom service account by running the following command:

    Example: Associate the privileged SCC with the fsgroup-runasany service account

    $ oc adm policy add-scc-to-user privileged -z fsgroup-runasany

  5. Use the custom service account in the pipeline run and task run:

    Example: Pipeline run YAML with fsgroup-runasany custom service account

    apiVersion: tekton.dev/v1beta1
    kind: PipelineRun
    metadata:
      name: <pipeline-run-name>
    spec:
      pipelineRef:
        name: <pipeline-cluster-task-name>
      serviceAccountName: 'fsgroup-runasany'

    Example: Task run YAML with fsgroup-runasany custom service account

    apiVersion: tekton.dev/v1beta1
    kind: TaskRun
    metadata:
      name: <task-run-name>
    spec:
      taskRef:
        name: <cluster-task-name>
      serviceAccountName: 'fsgroup-runasany'

3.9.3. Additional resources

3.10. Securing webhooks with event listeners

As an administrator, you can secure webhooks with event listeners. After creating a namespace, you enable HTTPS for the Eventlistener resource by adding the operator.tekton.dev/enable-annotation=enabled label to the namespace. Then, you create a Trigger resource and a secured route using the re-encrypted TLS termination.

Triggers in Red Hat OpenShift Pipelines support insecure HTTP and secure HTTPS connections to the Eventlistener resource. HTTPS secures connections within and outside the cluster.

Red Hat OpenShift Pipelines runs a tekton-operator-proxy-webhook pod that watches for the labels in the namespace. When you add the label to the namespace, the webhook sets the service.beta.openshift.io/serving-cert-secret-name=<secret_name> annotation on the EventListener object. This, in turn, creates secrets and the required certificates.

service.beta.openshift.io/serving-cert-secret-name=<secret_name>

In addition, you can mount the created secret into the Eventlistener pod to secure the request.

3.10.1. Providing secure connection with OpenShift routes

To create a route with the re-encrypted TLS termination, run:

$ oc create route reencrypt --service=<svc-name> --cert=tls.crt --key=tls.key --ca-cert=ca.crt --hostname=<hostname>

Alternatively, you can create a re-encrypted TLS termination YAML file to create a secure route.

Example re-encrypt TLS termination YAML to create a secure route

apiVersion: v1
kind: Route
metadata:
  name: route-passthrough-secured  1
spec:
  host: <hostname>
  to:
    kind: Service
    name: frontend 2
  tls:
    termination: reencrypt 3
    key: [as in edge termination]
    certificate: [as in edge termination]
    caCertificate: [as in edge termination]
    destinationCACertificate: |- 4
      -----BEGIN CERTIFICATE-----
      [...]
      -----END CERTIFICATE-----

1 2
The name of the object, which is limited to only 63 characters.
3
The termination field is set to reencrypt. This is the only required TLS field.
4
This is required for re-encryption. The destinationCACertificate field specifies a CA certificate to validate the endpoint certificate, thus securing the connection from the router to the destination pods. You can omit this field in either of the following scenarios:
  • The service uses a service signing certificate.
  • The administrator specifies a default CA certificate for the router, and the service has a certificate signed by that CA.

You can run the oc create route reencrypt --help command to display more options.

3.10.2. Creating a sample EventListener resource using a secure HTTPS connection

This section uses the pipelines-tutorial example to demonstrate creation of a sample EventListener resource using a secure HTTPS connection.

Procedure

  1. Create the TriggerBinding resource from the YAML file available in the pipelines-tutorial repository:

    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/master/03_triggers/01_binding.yaml
  2. Create the TriggerTemplate resource from the YAML file available in the pipelines-tutorial repository:

    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/master/03_triggers/02_template.yaml
  3. Create the Trigger resource directly from the pipelines-tutorial repository:

    $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/master/03_triggers/03_trigger.yaml
  4. Create an EventListener resource using a secure HTTPS connection:

    1. Add a label to enable the secure HTTPS connection to the Eventlistener resource:

      $ oc label namespace <ns-name> operator.tekton.dev/enable-annotation=enabled
    2. Create the EventListener resource from the YAML file available in the pipelines-tutorial repository:

      $ oc create -f https://raw.githubusercontent.com/openshift/pipelines-tutorial/master/03_triggers/04_event_listener.yaml
    3. Create a route with the re-encrypted TLS termination:

      $ oc create route reencrypt --service=<svc-name> --cert=tls.crt --key=tls.key --ca-cert=ca.crt --hostname=<hostname>

3.11. Authenticating pipelines using git secret

A Git secret consists of credentials to securely interact with a Git repository, and is often used to automate authentication. In Red Hat OpenShift Pipelines, you can use Git secrets to authenticate pipeline runs and task runs that interact with a Git repository during execution.

A pipeline run or a task run gains access to the secrets through the associated service account. Pipelines support the use of Git secrets as annotations (key-value pairs) for basic authentication and SSH-based authentication.

3.11.1. Credential selection

A pipeline run or task run might require multiple authentications to access different Git repositories. Annotate each secret with the domains where Pipelines can use its credentials.

A credential annotation key for Git secrets must begin with tekton.dev/git-, and its value is the URL of the host for which you want Pipelines to use that credential.

In the following example, Pipelines uses a basic-auth secret, which relies on a username and password, to access repositories at github.com and gitlab.com.

Example: Multiple credentials for basic authentication

apiVersion: v1
kind: Secret
metadata:
  annotations:
    tekton.dev/git-0: github.com
    tekton.dev/git-1: gitlab.com
type: kubernetes.io/basic-auth
stringData:
  username: 1
  password: 2

1
Username for the repository
2
Password or personal access token for the repository

You can also use an ssh-auth secret (private key) to access a Git repository.

Example: Private key for SSH based authentication

apiVersion: v1
kind: Secret
metadata:
  annotations:
    tekton.dev/git-0: https://github.com
type: kubernetes.io/ssh-auth
stringData:
  ssh-privatekey: 1

1
Name of the file containing the SSH private key string.

3.11.2. Configuring basic authentication for Git

For a pipeline to retrieve resources from password-protected repositories, you must configure the basic authentication for that pipeline.

To configure basic authentication for a pipeline, update the secret.yaml, serviceaccount.yaml, and run.yaml files with the credentials from the Git secret for the specified repository. When you complete this process, Pipelines can use that information to retrieve the specified pipeline resources.

Note

For GitHub, authentication using plain password is deprecated. Instead, use a personal access token.

Procedure

  1. In the secret.yaml file, specify the username and password or GitHub personal access token to access the target Git repository.

    apiVersion: v1
    kind: Secret
    metadata:
      name: basic-user-pass 1
      annotations:
        tekton.dev/git-0: https://github.com
    type: kubernetes.io/basic-auth
    stringData:
      username: 2
      password: 3
    1
    Name of the secret. In this example, basic-user-pass.
    2
    Username for the Git repository.
    3
    Password for the Git repository.
  2. In the serviceaccount.yaml file, associate the secret with the appropriate service account.

    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: build-bot 1
    secrets:
      - name: basic-user-pass 2
    1
    Name of the service account. In this example, build-bot.
    2
    Name of the secret. In this example, basic-user-pass.
  3. In the run.yaml file, associate the service account with a task run or a pipeline run.

    • Associate the service account with a task run:

      apiVersion: tekton.dev/v1beta1
      kind: TaskRun
      metadata:
        name: build-push-task-run-2 1
      spec:
        serviceAccountName: build-bot 2
        taskRef:
          name: build-push 3
      1
      Name of the task run. In this example, build-push-task-run-2.
      2
      Name of the service account. In this example, build-bot.
      3
      Name of the task. In this example, build-push.
    • Associate the service account with a PipelineRun resource:

      apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        name: demo-pipeline 1
        namespace: default
      spec:
        serviceAccountName: build-bot 2
        pipelineRef:
          name: demo-pipeline 3
      1
      Name of the pipeline run. In this example, demo-pipeline.
      2
      Name of the service account. In this example, build-bot.
      3
      Name of the pipeline. In this example, demo-pipeline.
  4. Apply the changes.

    $ kubectl apply --filename secret.yaml,serviceaccount.yaml,run.yaml

3.11.3. Configuring SSH authentication for Git

For a pipeline to retrieve resources from repositories configured with SSH keys, you must configure the SSH-based authentication for that pipeline.

To configure SSH-based authentication for a pipeline, update the secret.yaml, serviceaccount.yaml, and run.yaml files with the credentials from the SSH private key for the specified repository. When you complete this process, Pipelines can use that information to retrieve the specified pipeline resources.

Note

Consider using SSH-based authentication rather than basic authentication.

Procedure

  1. Generate an SSH private key, or copy an existing private key, which is usually available in the ~/.ssh/id_rsa file.
  2. In the secret.yaml file, set the value of ssh-privatekey to the name of the SSH private key file, and set the value of known_hosts to the name of the known hosts file.

    apiVersion: v1
    kind: Secret
    metadata:
      name: ssh-key 1
      annotations:
        tekton.dev/git-0: github.com
    type: kubernetes.io/ssh-auth
    stringData:
      ssh-privatekey: 2
      known_hosts: 3
    1
    Name of the secret containing the SSH private key. In this example, ssh-key.
    2
    Name of the file containing the SSH private key string.
    3
    Name of the file containing a list of known hosts.
    Caution

    If you omit the private key, Pipelines accepts the public key of any server.

  3. Optional: To specify a custom SSH port, add :<port number> to the end of the annotation value. For example, tekton.dev/git-0: github.com:2222.
  4. In the serviceaccount.yaml file, associate the ssh-key secret with the build-bot service account.

    apiVersion: v1
    kind: ServiceAccount
    metadata:
      name: build-bot 1
    secrets:
      - name: ssh-key 2
    1
    Name of the service account. In this example, build-bot.
    2
    Name of the secret containing the SSH private key. In this example, ssh-key.
  5. In the run.yaml file, associate the service account with a task run or a pipeline run.

    • Associate the service account with a task run:

      apiVersion: tekton.dev/v1beta1
      kind: TaskRun
      metadata:
        name: build-push-task-run-2 1
      spec:
        serviceAccountName: build-bot 2
        taskRef:
          name: build-push 3
      1
      Name of the task run. In this example, build-push-task-run-2.
      2
      Name of the service account. In this example, build-bot.
      3
      Name of the task. In this example, build-push.
    • Associate the service account with a pipeline run:

      apiVersion: tekton.dev/v1beta1
      kind: PipelineRun
      metadata:
        name: demo-pipeline 1
        namespace: default
      spec:
        serviceAccountName: build-bot 2
        pipelineRef:
          name: demo-pipeline 3
      1
      Name of the pipeline run. In this example, demo-pipeline.
      2
      Name of the service account. In this example, build-bot.
      3
      Name of the pipeline. In this example, demo-pipeline.
  6. Apply the changes.

    $ kubectl apply --filename secret.yaml,serviceaccount.yaml,run.yaml

3.11.4. Using SSH authentication in git type tasks

When invoking Git commands, you can use SSH authentication directly in the steps of a task. SSH authentication ignores the $HOME variable and only uses the user’s home directory specified in the /etc/passwd file. So each step in a task must symlink the /tekton/home/.ssh directory to the home directory of the associated user.

However, explicit symlinks are not necessary when you use a pipeline resource of the git type, or the git-clone task available in the Tekton catalog.

As an example of using SSH authentication in git type tasks, refer to authenticating-git-commands.yaml.

3.11.5. Using secrets as a non-root user

You might need to use secrets as a non-root user in certain scenarios, such as:

  • The users and groups that the containers use to execute runs are randomized by the platform.
  • The steps in a task define a non-root security context.
  • A task specifies a global non-root security context, which applies to all steps in a task.

In such scenarios, consider the following aspects of executing task runs and pipeline runs as a non-root user:

  • SSH authentication for Git requires the user to have a valid home directory configured in the /etc/passwd directory. Specifying a UID that has no valid home directory results in authentication failure.
  • SSH authentication ignores the $HOME environment variable. So you must or symlink the appropriate secret files from the $HOME directory defined by Pipelines (/tekton/home), to the non-root user’s valid home directory.

In addition, to configure SSH authentication in a non-root security context, refer to the example for authenticating git commands.

3.11.6. Limiting secret access to specific steps

By default, the secrets for Pipelines are stored in the $HOME/tekton/home directory, and are available for all the steps in a task.

To limit a secret to specific steps, use the secret definition to specify a volume, and mount the volume in specific steps.

3.12. Viewing pipeline logs using the OpenShift Logging Operator

The logs generated by pipeline runs, task runs, and event listeners are stored in their respective pods. It is useful to review and analyze logs for troubleshooting and audits.

However, retaining the pods indefinitely leads to unnecessary resource consumption and cluttered namespaces.

To eliminate any dependency on the pods for viewing pipeline logs, you can use the OpenShift Elasticsearch Operator and the OpenShift Logging Operator. These Operators help you to view pipeline logs by using the Elasticsearch Kibana stack, even after you have deleted the pods that contained the logs.

3.12.1. Prerequisites

Before trying to view pipeline logs in a Kibana dashboard, ensure the following:

  • The steps are performed by a cluster administrator.
  • Logs for pipeline runs and task runs are available.
  • The OpenShift Elasticsearch Operator and the OpenShift Logging Operator are installed.

3.12.2. Viewing pipeline logs in Kibana

To view pipeline logs in the Kibana web console:

Procedure

  1. Log in to OpenShift Container Platform web console as a cluster administrator.
  2. In the top right of the menu bar, click the grid icon → ObservabilityLogging. The Kibana web console is displayed.
  3. Create an index pattern:

    1. On the left navigation panel of the Kibana web console, click Management.
    2. Click Create index pattern.
    3. Under Step 1 of 2: Define index patternIndex pattern, enter a * pattern and click Next Step.
    4. Under Step 2 of 2: Configure settingsTime filter field name, select @timestamp from the drop-down menu, and click Create index pattern.
  4. Add a filter:

    1. On the left navigation panel of the Kibana web console, click Discover.
    2. Click Add a filter +Edit Query DSL.

      Note
      • For each of the example filters that follows, edit the query and click Save.
      • The filters are applied one after another.
      1. Filter the containers related to pipelines:

        Example query to filter pipelines containers

        {
          "query": {
        	"match": {
          	"kubernetes.flat_labels": {
            	"query": "app_kubernetes_io/managed-by=tekton-pipelines",
            	"type": "phrase"
          	}
        	}
          }
        }

      2. Filter all containers that are not place-tools container. As an illustration of using the graphical drop-down menus instead of editing the query DSL, consider the following approach:

        Figure 3.6. Example of filtering using the drop-down fields

        Not place-tools
      3. Filter pipelinerun in labels for highlighting:

        Example query to filter pipelinerun in labels for highlighting

        {
          "query": {
        	"match": {
          	"kubernetes.flat_labels": {
            	"query": "tekton_dev/pipelineRun=",
            	"type": "phrase"
          	}
        	}
          }
        }

      4. Filter pipeline in labels for highlighting:

        Example query to filter pipeline in labels for highlighting

        {
          "query": {
        	"match": {
          	"kubernetes.flat_labels": {
            	"query": "tekton_dev/pipeline=",
            	"type": "phrase"
          	}
        	}
          }
        }

    3. From the Available fields list, select the following fields:

      • kubernetes.flat_labels
      • message

        Ensure that the selected fields are displayed under the Selected fields list.

    4. The logs are displayed under the message field.

      Figure 3.7. Filtered messages

      Filtered messages

3.12.3. Additional resources