Pod templates

A Pod template defines a portion of a PodSpec configuration that Tekton can use as “boilerplate” for a Pod that runs your Tasks and Pipelines.

You can specify a Pod template for TaskRuns and PipelineRuns. In the template, you can specify custom values for fields governing the execution of individual Tasks or for all Tasks executed by a given PipelineRun.

You also have the option to define a global Pod template in your Tekton config using the key default-pod-template. However, this global template is going to be merged with any templates you specify in your TaskRuns and PipelineRuns.
Except for the env and volumes fields, other fields that exist in both the global template and the TaskRun’s or PipelineRun’s template will be taken from the TaskRun or PipelineRun. The env and volumes fields are merged by the name value in the array elements. If the item’s name is the same, the item from TaskRun or PipelineRun will be used.

See the following for examples of specifying a Pod template:

Supported fields

Pod templates support fields listed in the table below.

Field Description
env Environment variables defined in the Pod template at TaskRun and PipelineRun level take precedence over the ones defined in steps and stepTemplate
nodeSelector Must be true for the Pod to fit on a node.
tolerations Allows (but does not require) the Pods to schedule onto nodes with matching taints.
affinity Allows constraining the set of nodes for which the Pod can be scheduled based on the labels present on the node.
securityContext Specifies Pod-level security attributes and common container settings such as runAsUser and selinux.
volumes Specifies a list of volumes that containers within the Pod can mount. This allows you to specify a volume type for each volumeMount in a Task.
runtimeClassName Specifies the runtime class for the Pod.
automountServiceAccountToken Default: true. Determines whether Tekton automatically provides the token for the service account used by the Pod inside containers at a predefined path.
dnsPolicy Default: ClusterFirst. Specifies the DNS policy for the Pod. Legal values are ClusterFirst, Default, and None. Does not support ClusterFirstWithHostNet because Tekton Pods cannot run with host networking.
dnsConfig Specifies additional DNS configuration for the Pod, such as name servers and search domains.
enableServiceLinks Default: true. Determines whether services in the Pod's namespace are exposed as environment variables to the Pod, similarly to Docker service links.
priorityClassName Specifies the priority class for the Pod. Allows you to selectively enable preemption on lower-priority workloads.
schedulerName Specifies the scheduler to use when dispatching the Pod. You can specify different schedulers for different types of workloads, such as volcano.sh for machine learning workloads.
imagePullSecrets Specifies the secret to use when pulling a container image.
hostNetwork Default: false. Determines whether to use the host network namespace.
hostAliases Adds entries to a Pod's `/etc/hosts` to provide Pod-level overrides of hostnames. For further info see [Kubernetes' docs for this field](https://kubernetes.io/docs/tasks/network/customize-hosts-file-for-pods/).
topologySpreadConstraints Specify how Pods are spread across your cluster among topology domains.

Use imagePullSecrets to lookup entrypoint

If no command is configured in task and imagePullSecrets is configured in podTemplate, the Tekton Controller will look up the entrypoint of image with imagePullSecrets. The Tekton controller’s service account is given access to secrets by default. See this for reference. If the Tekton controller’s service account is not granted the access to secrets in different namespace, you need to grant the access via RoleBinding:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: creds-getter
  namespace: my-ns
rules:
- apiGroups: [""]
  resources: ["secrets"]
  resourceNames: ["creds"]
  verbs: ["get"]
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: creds-getter-binding
  namespace: my-ns
subjects:
- kind: ServiceAccount
  name: tekton-pipelines-controller
  namespace: tekton-pipelines
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: creds-getter
  apiGroup: rbac.authorization.k8s.io

Affinity Assistant Pod templates

The Pod templates specified in the TaskRuns and PipelineRuns also apply to the affinity assistant Pods that are created when using Workspaces, but only on selected fields.

The supported fields for affinity assistant pods are: tolerations, nodeSelector, securityContext, priorityClassName and imagePullSecrets (see the table above for more details about the fields).

Similarly to global Pod Template, you have the option to define a global affinity assistant Pod template in your Tekton config using the key default-affinity-assistant-pod-template. The merge strategy is the same as the one described above for the supported fields.


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.