PipelineRuns

This document defines PipelineRuns and their capabilities.

On its own, a Pipeline declares what Tasks torun, and the order they run in. To execute the Tasksin the Pipeline, you must create a PipelineRun.

Creation of a PipelineRun will trigger the creation ofTaskRuns for each Task in your pipeline.

Syntax

To define a configuration file for a PipelineRun resource, you can specify thefollowing fields:

  • Required:
    • apiVersion - Specifies the API version, for exampletekton.dev/vbeta1
    • kind - Specify the PipelineRun resource object.
    • metadata - Specifies data to uniquely identify thePipelineRun resource object, for example a name.
    • spec - Specifies the configuration information foryour PipelineRun resource object.
    • pipelineRef or pipelineSpec - Specifies the Pipeline you want to run.
  • Optional:
    • resources - Specifies whichPipelineResources to use for this PipelineRun.
    • params - Specifies which params to be passed to the pipeline specified/referenced by this pipeline run.
    • serviceAccountName - Specifies a ServiceAccount resourceobject that enables your build to run with the defined authenticationinformation. When a ServiceAccount isn’t specified, the default-service-accountspecified in the configmap - config-defaults will be applied.
    • serviceAccountNames - Specifies a list of serviceAccountNameand PipelineTask pairs that enable you to overwrite a ServiceAccount for a concrete PipelineTask.
    • timeout - Specifies timeout after which the PipelineRun will fail. If the value oftimeout is empty, the default timeout will be applied. If the value is set to 0,there is no timeout. PipelineRun shares the same default timeout as TaskRun. You canfollow the instruction here to configure thedefault timeout, the same way as TaskRun.
    • podTemplate - Specifies a pod template that will be used as the basis for the Task pod.

Specifying a pipeline

Since a PipelineRun is an invocation of a Pipeline, you must specifywhat Pipeline to invoke.

You can do this by providing a reference to an existing Pipeline:

  1. spec:
  2.   pipelineRef:
  3.     name: mypipeline

Or you can embed the spec of the Pipeline directly in the PipelineRun:

  1. spec:
  2.   pipelineSpec:
  3.     tasks:
  4.     - name: task1
  5.       taskRef:
  6.         name: mytask

Here is a sample PipelineRun to display differentgreetings while embedding the spec of the Pipeline directly in the PipelineRun.

After creating such a PipelineRun, the logs from this pod are displaying morning greetings:

  1. kubectl logs $(kubectl get pods -o name | grep pipelinerun-echo-greetings-echo-good-morning)
  2. Good Morning, Bob!

And the logs from this pod are displaying evening greetings:

  1. kubectl logs $(kubectl get pods -o name | grep pipelinerun-echo-greetings-echo-good-night)
  2. Good Night, Bob!

Even further you can embed the spec of a Task directly in the Pipeline:

  1. spec:
  2.   pipelineSpec:
  3.     tasks:
  4.     - name: task1
  5.       taskSpec:
  6.         steps:
  7.           ...

Here is a sample PipelineRun with embeddedthe spec of the Pipeline directly in the PipelineRun along with the spec of the Task under PipelineSpec.

Resources

When running a Pipeline, you will need to specify thePipelineResources to use with it. One Pipeline may need tobe run with different PipelineResources in cases such as:

  • When triggering the run of a Pipeline against a pull request, the triggeringsystem must specify the commit-ish of a git PipelineResource to use
  • When invoking a Pipeline manually against one’s own setup, one will need toensure one’s own GitHub fork (via the git PipelineResource), imageregistry (via the image PipelineResource) and Kubernetes cluster (via thecluster PipelineResource).

Specify the PipelineResources in the PipelineRun using the resources sectionin the PipelineRun’s spec, for example:

  1. spec:
  2.   resources:
  3.     - name: source-repo
  4.       resourceRef:
  5.         name: skaffold-git
  6.     - name: web-image
  7.       resourceRef:
  8.         name: skaffold-image-leeroy-web
  9.     - name: app-image
  10.       resourceRef:
  11.         name: skaffold-image-leeroy-app

Or you can embed the spec of the Resource directly in the PipelineRun:

  1. spec:
  2.   resources:
  3.     - name: source-repo
  4.       resourceSpec:
  5.         type: git
  6.         params:
  7.           - name: revision
  8.             value: v0.32.0
  9.           - name: url
  10.             value: https://github.com/GoogleContainerTools/skaffold
  11.     - name: web-image
  12.       resourceSpec:
  13.         type: image
  14.         params:
  15.           - name: url
  16.             value: gcr.io/christiewilson-catfactory/leeroy-web
  17.     - name: app-image
  18.       resourceSpec:
  19.         type: image
  20.         params:
  21.           - name: url
  22.             value: gcr.io/christiewilson-catfactory/leeroy-app

Params

While writing a Pipelinerun, we can specify params that need to be bound tothe input params of the pipeline specified/referenced by the Pipelinerun.

This means that a Pipeline can be run with different input params, by writing Pipelinerunswhich bound different input values to the Pipeline params.

  1. spec:
  2.   params:
  3.   - name: pl-param-x
  4.     value: "100"
  5.   - name: pl-param-y
  6.     value: "500"

Service Account

Specifies the name of a ServiceAccount resource object. Use theserviceAccountName field to run your Pipeline with the privileges of thespecified service account. If no serviceAccountName field is specified, yourresulting TaskRuns run using the service account specified in the ConfigMapconfigmap-defaults which if absent will default to thedefault service accountthat is in the namespaceof the TaskRun resource object.

For examples and more information about specifying service accounts, see theServiceAccount reference topic.

Service Accounts

Specifies the list of serviceAccountName and PipelineTask pairs. A specifiedPipelineTask will be run with the configured ServiceAccount,overwriting the serviceAccountName configuration, for example:

  1. spec:
  2.   serviceAccountName: sa-1
  3.   serviceAccountNames:
  4.     - taskName: build-task
  5.       serviceAccountName: sa-for-build

If used with this Pipeline, test-task will use the ServiceAccount sa-1, while build-task will use sa-for-build.

  1. kind: Pipeline
  2. spec:
  3.   tasks:
  4.     - name: build-task
  5.       taskRef:
  6.         name: build-push
  7.     - name: test-task
  8.       taskRef:
  9.         name: test

Pod Template

Specifies a pod template configuration that will be used as the basis for the Task pod. Thisallows to customize some Pod specific field per Task execution, aka TaskRun.

In the following example, the Task is defined with a volumeMount(my-cache), that is provided by the PipelineRun, using apersistentVolumeClaim. The Pod will also run as a non-root user.

  1. apiVersion: tekton.dev/v1beta1
  2. kind: Task
  3. metadata:
  4.   name: mytask
  5. spec:
  6.   steps:
  7.     - name: writesomething
  8.       image: ubuntu
  9.       command: ["bash", "-c"]
  10.       args: ["echo 'foo' > /my-cache/bar"]
  11.       volumeMounts:
  12.         - name: my-cache
  13.           mountPath: /my-cache
  14. ---
  15. apiVersion: tekton.dev/v1beta1
  16. kind: Pipeline
  17. metadata:
  18.   name: mypipeline
  19. spec:
  20.   tasks:
  21.     - name: task1
  22.       taskRef:
  23.         name: mytask
  24. ---
  25. apiVersion: tekton.dev/v1beta1
  26. kind: PipelineRun
  27. metadata:
  28.   name: mypipelinerun
  29. spec:
  30.   pipelineRef:
  31.     name: mypipeline
  32.   podTemplate:
  33.     securityContext:
  34.       runAsNonRoot: true
  35.     volumes:
  36.     - name: my-cache
  37.       persistentVolumeClaim:
  38.         claimName: my-volume-claim

PersistentVolumeClaims

Any persistent volume claims within a PipelineRun are bound until thecorresponding PipelineRun or pods are deleted. This also applies to anyinternally generated persistent volume claims.

Workspaces

For a PipelineRun to execute a Pipeline that declares workspaces it needs to mapthose workspaces to actual physical volumes.

Here are the relevant fields of a PipelineRun spec when providing aPersistentVolumeClaim as a workspace:

  1. workspaces:
  2. - name: myworkspace # must match workspace name in Task
  3.   persistentVolumeClaim:
  4.     claimName: mypvc # this PVC must already exist
  5.   subPath: my-subdir

For more examples and complete documentation on configuring workspaces inPipelineRuns see workspaces.md.

Tekton supports several different kinds of Volume in Workspaces. For a list ofthe different kinds see the section onVolumeSources for Workspaces.

For a complete example see the Workspaces PipelineRunin the examples directory.

Cancelling a PipelineRun

In order to cancel a running pipeline (PipelineRun), you need to update itsspec to mark it as cancelled. Related TaskRun instances will be marked ascancelled and running Pods will be deleted.

  1. apiVersion: tekton.dev/v1beta1
  2. kind: PipelineRun
  3. metadata:
  4.   name: go-example-git
  5. spec:
  6.   # […]
  7.   status: "PipelineRunCancelled"

LimitRanges

In order to request the minimum amount of resources needed to support the containersfor steps that are part of a TaskRun, Tekton only requests the maximum values for CPU,memory, and ephemeral storage from the steps that are part of a TaskRun. Only the maxresource request values are needed since steps only execute one at a time in a TaskRun pod.All requests that are not the max values are set to zero as a result.

When a LimitRange is present in a namespacewith a minimum set for container resource requests (i.e. CPU, memory, and ephemeral storage) where PipelineRunsare attempting to run, Tekton will search through all LimitRanges present in the namespace and use the minimumset for container resource requests instead of requesting 0.

An example PipelineRun with a LimitRange is available here.