Skip to content

pipelineruns.md

Latest commit

 

History

History
216 lines (184 loc) · 7.42 KB

pipelineruns.md

File metadata and controls

216 lines (184 loc) · 7.42 KB

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/v1alpha1.
    • 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.
      • pipelineRef - Specifies the Pipeline you want to run.

  • Optional:

    • resources - Specifies which PipelineResources to use for this PipelineRun.
    • serviceAccount - Specifies a ServiceAccount resource object that enables your build to run with the defined authentication information.
    • serviceAccounts - Specifies a list of ServiceAccount and PipelineTask pairs that enable you to overwrite ServiceAccount for 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 subset of PodSpec configuration that will be used as the basis for the Task pod.

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 commitish of a git PipelineResource to use
  • When invoking a Pipeline manually against one's own setup, one will need to ensure that 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 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

Service Account

Specifies the name of a ServiceAccount resource object. Use the serviceAccount field to run your Pipeline with the privileges of the specified service account. If no serviceAccount field is specified, your resulting TaskRuns run using 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 ServiceAccount and PipelineTask pairs. Specified PipelineTask will be run with configured ServiceAccount, overwriting serviceAccount configuration, for example:

spec:
  serviceAccount: sa-1
  serviceAccounts:
    - taskName: build-task
      serviceAccount: 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
  tasks:
    - name: test-task
      taskRef:
        name: test

Pod Template

Specifies a subset of PodSpec 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. The current field supported are:

  • nodeSelector: a selector which must be true for the pod to fit on a node, see here.
  • tolerations: allow (but do not require) the pods to schedule onto nodes with matching taints.
  • affinity: allow to constrain which nodes your pod is eligible to be scheduled on, based on labels on the node.
  • securityContext: pod-level security attributes and common container settings, like runAsUser or selinux.
  • volumes: list of volumes that can be mounted by containers belonging to the pod. This lets the user of a Task define which type of volume to use for a Task volumeMount

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

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

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/v1alpha1
kind: PipelineRun
metadata:
  name: go-example-git
spec:
  # […]
  status: "PipelineRunCancelled"

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.