Skip to content

Latest commit

 

History

History
416 lines (337 loc) · 14.3 KB

pipelineruns.md

File metadata and controls

416 lines (337 loc) · 14.3 KB
Raw

PipelineRuns

This document defines PipelineRuns and their capabilities.

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

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

Syntax

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

  • Required:
    • apiVersion - Specifies the API version, for example tekton.dev/vbeta1
    • kind - Specify the PipelineRun resource object.
    • metadata - Specifies data to uniquely identify the PipelineRun resource object, for example a name.
    • spec - Specifies the configuration information for your PipelineRun resource object.
  • Optional:
    • resources - Specifies which PipelineResources 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 resource object that enables your build to run with the defined authentication information. When a ServiceAccount isn't specified, the default-service-account specified in the configmap - config-defaults will be applied.
    • serviceAccountNames - Specifies a list of serviceAccountName and 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 of timeout 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 can follow the instruction here to configure the default 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 specify what Pipeline to invoke.

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

spec:
  pipelineRef:
    name: mypipeline

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

spec:
  pipelineSpec:
    tasks:
    - name: task1
      taskRef:
        name: mytask

Here is a sample PipelineRun to display different greetings 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:

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

And the logs from this pod are displaying evening greetings:

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

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

spec:
  pipelineSpec:
    tasks:
    - name: task1
      taskSpec:
        steps:
          ...

Here is a sample PipelineRun with embedded the 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 the PipelineResources to use with it. One Pipeline may need to be run with different PipelineResources in cases such as:

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

Specify the PipelineResources in the PipelineRun using the resources section in the PipelineRun's spec, for example:

spec:
  resources:
    - name: source-repo
      resourceRef:
        name: skaffold-git
    - name: web-image
      resourceRef:
        name: skaffold-image-leeroy-web
    - name: app-image
      resourceRef:
        name: skaffold-image-leeroy-app

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

spec:
  resources:
    - name: source-repo
      resourceSpec:
        type: git
        params:
          - name: revision
            value: v0.32.0
          - name: url
            value: https://github.com/GoogleContainerTools/skaffold
    - name: web-image
      resourceSpec:
        type: image
        params:
          - name: url
            value: gcr.io/christiewilson-catfactory/leeroy-web
    - name: app-image
      resourceSpec:
        type: image
        params:
          - name: url
            value: gcr.io/christiewilson-catfactory/leeroy-app

Params

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

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

spec:
  params:
  - name: pl-param-x
    value: "100"
  - name: pl-param-y
    value: "500"

Service Account

Specifies the name of a ServiceAccount resource object. Use the serviceAccountName field to run your Pipeline with the privileges of the specified service account. If no serviceAccountName field is specified, your resulting TaskRuns run using the service account specified in the ConfigMap configmap-defaults which if absent will default to the default service account that is in the namespace of the TaskRun resource object.

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

Service Accounts

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

spec:
  serviceAccountName: sa-1
  serviceAccountNames:
    - taskName: build-task
      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.

kind: Pipeline
spec:
  tasks:
    - name: build-task
      taskRef:
        name: build-push
    - name: test-task
      taskRef:
        name: test

Pod Template

Specifies a pod template configuration that will be used as the basis for the Task pod. This allows 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 a persistentVolumeClaim. The Pod will also run as a non-root user.

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: mytask
spec:
  steps:
    - name: writesomething
      image: ubuntu
      command: ["bash", "-c"]
      args: ["echo 'foo' > /my-cache/bar"]
      volumeMounts:
        - name: my-cache
          mountPath: /my-cache
---
apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: mypipeline
spec:
  tasks:
    - name: task1
      taskRef:
        name: mytask
---
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: mypipelinerun
spec:
  pipelineRef:
    name: mypipeline
  podTemplate:
    securityContext:
      runAsNonRoot: true
    volumes:
    - name: my-cache
      persistentVolumeClaim:
        claimName: my-volume-claim

PersistentVolumeClaims

Any persistent volume claims within a PipelineRun are bound until the corresponding PipelineRun or pods are deleted. This also applies to any internally generated persistent volume claims.

Workspaces

Workspaces allow PVC, emptyDir, configmap and secret volume sources to be easily wired into tasks and pipelines.

For a PipelineRun to execute a Pipeline that declares workspaces, at runtime you need to map the workspace names to actual physical volumes. This is managed through the PipelineRun's workspaces field. Values in workspaces are Volumes, however currently we only support a subset of VolumeSources:

If you need support for a VolumeSource not listed here please open an issue or feel free to contribute a PR.

If the workspaces declared in the Pipeline are not provided at runtime, the PipelineRun will fail with an error.

For example to provide an existing PVC called mypvc for a workspace called myworkspace declared by the Pipeline, using the my-subdir folder which already exists on the PVC (there will be an error if it does not exist):

workspaces:
- name: myworkspace
  persistentVolumeClaim:
    claimName: mypvc
  subPath: my-subdir

An emptyDir can also be used for this with the following caveats:

  1. An emptyDir volume type is not shared amongst Tasks. Instead each Task will simply receive a new emptyDir of its own from its underlying Pod.
workspaces:
- name: myworkspace
  emptyDir: {}

A configMap can also be used as a workspace with the following caveats:

  1. ConfigMap volume sources are always mounted as read-only inside a task's containers - tasks cannot write content to them and a step may error out and fail the task if a write is attempted.
  2. The ConfigMap you want to use as a workspace must already exist prior to the TaskRun being submitted.
  3. ConfigMaps have a size limit of 1MB

To use a configMap as a workspace:

workspaces:
- name: myworkspace
  configmap:
    name: my-configmap

A secret can also be used as a workspace with the following caveats:

  1. Secret volume sources are always mounted as read-only inside a task's containers - tasks cannot write content to them and a step may error out and fail the task if a write is attempted.
  2. The Secret you want to use as a workspace must already exist prior to the TaskRun being submitted.
  3. Secrets have a size limit of 1MB

To use a secret as a workspace:

workspaces:
- name: myworkspace
  secret:
    secretName: my-secret

For a complete example see workspaces.yaml.

Cancelling a PipelineRun

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

apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: go-example-git
spec:
  # […]
  status: "PipelineRunCancelled"

LimitRanges

In order to request the minimum amount of resources needed to support the containers for 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 max resource 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 namespace with a minimum set for container resource requests (i.e. CPU, memory, and ephemeral storage) where PipelineRuns are attempting to run, Tekton will search through all LimitRanges present in the namespace and use the minimum set for container resource requests instead of requesting 0.

An example PipelineRun with a LimitRange is available here.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.