Labels and Annotations

Tekton allows you to use custom Kubernetes Labels to easily mark Tekton entities belonging to the same conceptual execution chain. Tekton also automatically adds select labels to more easily identify resource relationships. This document describes the label propagation scheme, automatic labeling, and provides usage examples.

Label propagation

Labels propagate among Tekton entities as follows:

  • For Pipelines instantiated using a PipelineRun, labels propagate automatically from Pipelines to PipelineRuns to TaskRuns, and then to the associated Pods. If a label is present in both Pipeline and PipelineRun, the label in PipelineRun takes precedence.

  • Labels from Tasks referenced by TaskRuns within a PipelineRun propagate to the corresponding TaskRuns, and then to the associated Pods. As for Pipeline and PipelineRun, if a label is present in both Task and TaskRun, the label in TaskRun takes precedence.

  • For standalone TaskRuns (that is, ones not executing as part of a Pipeline), labels propagate from the referenced Task, if one exists, to the corresponding TaskRun, and then to the associated Pod. The same as above applies.

Automatic labeling

Tekton automatically adds labels to Tekton entities as described in the following table.

Note: *.tekton.dev labels are reserved for Tekton’s internal use only. Do not add or remove them manually.

Label Added To Propagates To Contains
tekton.dev/pipeline PipelineRuns TaskRuns, Pods Name of the Pipeline that the PipelineRun references.
tekton.dev/pipelineRun TaskRuns that are created automatically during the execution of a PipelineRun. TaskRuns, Pods Name of the PipelineRun that triggered the creation of the TaskRun.
tekton.dev/task TaskRuns that reference an existing Task. Pods Name of the Task that the TaskRun references.
tekton.dev/clusterTask TaskRuns that reference an existing ClusterTask. Pods Name of the ClusterTask that the TaskRun references.
tekton.dev/taskRun Pods No propagation. Name of the TaskRun that created the Pod.
tekton.dev/memberOf TaskRuns that are created automatically during the execution of a PipelineRun. TaskRuns, Pods tasks or finally depending on the PipelineTask's membership in the Pipeline.
app.kubernetes.io/instance, app.kubernetes.io/component Pods, StatefulSets (Affinity Assistant) No propagation. Pod affinity values for TaskRuns.

Usage examples

Below are some examples of using labels:

The following command finds all Pods created by a PipelineRun named test-pipelinerun:

kubectl get pods --all-namespaces -l tekton.dev/pipelineRun=test-pipelinerun

The following command finds all TaskRuns that reference a Task named test-task:

kubectl get taskruns --all-namespaces -l tekton.dev/task=test-task

The following command finds all TaskRuns that reference a ClusterTask named test-clustertask:

kubectl get taskruns --all-namespaces -l tekton.dev/clusterTask=test-clustertask

Annotations propagation

Annotation propagate among Tekton entities as follows (similar to Labels):

  • For Pipelines instantiated using a PipelineRun, annotations propagate automatically from Pipelines to PipelineRuns to TaskRuns, and then to the associated Pods. If a annotation is present in both Pipeline and PipelineRun, the annotation in PipelineRun takes precedence.

  • Annotations from Tasks referenced by TaskRuns within a PipelineRun propagate to the corresponding TaskRuns, and then to the associated Pods. As for Pipeline and PipelineRun, if a annotation is present in both Task and TaskRun, the annotation in TaskRun takes precedence.

  • For standalone TaskRuns (that is, ones not executing as part of a Pipeline), annotations propagate from the referenced Task, if one exists, to the corresponding TaskRun, and then to the associated Pod. The same as above applies.