Pod Templates

Pod templates are configuration fields within TaskRun and PipelineRun specifications that allow you to customize the Pod configuration for your Tekton workloads. They define a portion of a PodSpec that Tekton uses to configure the Pods that execute your Tasks and Pipelines. This configuration allows you to customize the execution environment without modifying the core Task or Pipeline definitions.

NOTE

Important: Pod templates are not separate Kubernetes resources. They are configuration fields within TaskRun and PipelineRun specifications.

Why Pod Templates are Needed

Pod Configuration Challenges

Kubernetes-based CI/CD systems face several Pod configuration challenges:

  • Environment Consistency: Ensure consistent execution environments across Tasks
  • Scheduling: Specify node selectors, tolerations, and affinity rules. Pod templates have no CPU or memory field; set compute resources with computeResources on a Step, or with computeResources on the TaskRun or on a PipelineRun taskRunSpecs entry (beta fields, enabled when enable-api-fields is beta, the default)
  • Security: Apply security contexts and access controls
  • Network & Storage: Configure DNS policies, volumes, and image access

Tekton's Solution

Tekton Pod templates address these challenges by providing:

  • Reusability: Define common configurations for multiple TaskRuns and PipelineRuns
  • Customization: Customize execution environments without modifying Task/Pipeline definitions
  • Flexibility: Support both global and per-execution configurations

Advantages

  • Consistency: Ensure consistent execution environments across Pipeline executions
  • Flexibility: Override default Pod configurations for specific use cases
  • Reusability: Define configurations once and apply to multiple executions
  • Security: Apply security policies and access controls at Pod level
  • Node Placement: Control where Pods are scheduled with node selectors, tolerations, and affinity rules

Scenarios

Pod templates are useful in various scenarios, including:

  • Resource-Intensive Workloads: Place build/test Tasks on suitable nodes with node selectors, tolerations, or affinity rules; set their CPU and memory with computeResources, not in the Pod template
  • Security-Sensitive Applications: Apply security contexts and access controls
  • Multi-Node Clusters: Use node selectors and affinity rules for optimal scheduling
  • Private Registry Access: Configure image pull secrets for private registries
  • Network Requirements: Customize DNS policies and network configurations
  • Storage Requirements: Define volumes and storage configurations

Constraints and Limitations

  • Pod template configuration only affects the Pod configuration, not the Task or Pipeline logic
  • Some fields may be overridden by Tekton's internal requirements
  • Global configurations are merged with execution-specific configurations
  • Affinity assistant Pods only support a subset of Pod template configuration fields
  • Pod template configuration cannot modify Tekton's core functionality or behavior

Principles

Pod Template Processing

When a Pod template configuration is specified:

  1. Tekton validates the Pod template configuration
  2. The configuration is merged with any global Pod template configuration
  3. For PipelineRuns, the configuration is applied to all TaskRuns unless overridden by taskRunSpecs
  4. For TaskRuns, the configuration is applied directly to the Pod
  5. Tekton creates the Pod with the merged configuration
  6. The Pod executes the Task or Pipeline steps with the specified configuration

Configuration Merging Strategy

Pod template configurations follow specific merging rules and have a clear priority hierarchy:

Priority Order

Pod template configurations are merged in the following order of precedence (highest to lowest):

  1. PipelineRun taskRunSpecs[].podTemplate (highest priority) - Pod template configurations specified in taskRunSpecs for specific tasks within a PipelineRun
  2. PipelineRun taskRunTemplate.podTemplate (medium priority) - Pod template configurations specified at the PipelineRun level for all its tasks; for a TaskRun that you create directly, its spec.podTemplate
  3. Global default-pod-template (lowest priority) - The global Pod template set in TektonConfig and written by the Tekton Operator into the config-defaults ConfigMap

When multiple configurations exist for the same field, the higher priority configuration will override the lower priority one.

Merging Rules

  • Environment Variables (env): Merged by name value in array elements. If items have the same name, the item from TaskRun or PipelineRun will be used
  • Volumes: Merged by name value in array elements. If items have the same name, the item from TaskRun or PipelineRun will be used
  • Other Fields: If a field exists in multiple configurations, the higher priority configuration takes precedence and replaces the field as a whole. For example, a securityContext set in taskRunSpecs replaces the securityContext of the PipelineRun-level Pod template; the two are not merged field by field

Configuration Examples

Basic Pod Template Configuration for TaskRun

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: build-with-pod-template
spec:
  taskRef:
    name: build-task
  podTemplate:
    nodeSelector:
      disktype: ssd
    tolerations:
    - key: "dedicated"
      operator: "Equal"
      value: "build"
      effect: "NoSchedule"
    securityContext:
      runAsUser: 1000
      runAsGroup: 1000
      fsGroup: 1000
    volumes:
    - name: cache-volume
      emptyDir: {}

Pod Template Configuration for PipelineRun

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-with-pod-template
spec:
  pipelineRef:
    name: build-deploy-pipeline
  taskRunTemplate:
    podTemplate:
      nodeSelector:
        environment: production
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: kubernetes.io/os
                operator: In
                values:
                - linux
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
      imagePullSecrets:
      - name: registry-secret
      env:
      - name: BUILD_ENV
        value: "production"

The run's imagePullSecrets list is written into each of its TaskRun Pods, so Kubernetes no longer adds the ServiceAccount's pull secrets to those Pods, and the imagePullSecrets list of the global default Pod template (see below) is not used either. List every Secret that the run needs.

In a tekton.dev/v1 PipelineRun, the Pod template for all tasks is spec.taskRunTemplate.podTemplate. The tekton.dev/v1beta1 PipelineRun used spec.podTemplate instead; a v1 PipelineRun with spec.podTemplate is rejected by the API server with strict decoding error: unknown field "spec.podTemplate".

Global Pod Template Configuration

The global default Pod template is the default-pod-template key of the config-defaults ConfigMap in tekton-pipelines. The Tekton Operator writes that ConfigMap from TektonConfig, so set the value in spec.pipeline.default-pod-template of TektonConfig, as described in Method 4: Global Default Configuration (TektonConfig), and do not edit the ConfigMap. tekton-pipelines is the default of TektonConfig spec.targetNamespace; replace it in the commands if your installation uses another namespace.

WARNING

The value applies to the Pods of every new TaskRun in every namespace of the cluster. With the nodeSelector below, these Pods are scheduled only on nodes labeled workload: tekton; if no node has that label, they stay Pending. Label and taint the nodes before you set the value. The imagePullSecrets list below is written into every TaskRun Pod whose run does not set its own list, so Kubernetes no longer adds the ServiceAccount's pull secrets to those Pods, and default-registry-secret must exist in every namespace that runs TaskRuns. The value also replaces the current default Pod template as a whole: read it first (kubectl get configmap -n tekton-pipelines config-defaults -o jsonpath='{.data.default-pod-template}'), also read the value set in TektonConfig (kubectl get tektonconfig config -o jsonpath='{.spec.pipeline.default-pod-template}'), save both outputs, and keep the default's fields. The sample keeps the shipped fsGroup and fsGroupChangePolicy.

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    default-pod-template: |
      nodeSelector:
        workload: tekton
      tolerations:
      - key: "workload"
        operator: "Equal"
        value: "tekton"
        effect: "NoSchedule"
      securityContext:
        fsGroup: 65532
        fsGroupChangePolicy: "OnRootMismatch"
      imagePullSecrets:
      - name: default-registry-secret

Save the sample as tektonconfig-pod-template.yaml and merge it into the existing TektonConfig:

kubectl patch tektonconfig config --type merge --patch-file tektonconfig-pod-template.yaml

Check that the change took effect. Reading the ConfigMap needs read access to ConfigMaps in tekton-pipelines, usually a cluster administrator. The command prints the whole default Pod template, which must be the template of the sample:

kubectl get configmap -n tekton-pipelines config-defaults -o jsonpath='{.data.default-pod-template}'

To undo the change: if the saved TektonConfig output was empty, remove the field from TektonConfig, which returns to the shipped default Pod template:

kubectl patch tektonconfig config --type json \
  -p '[{"op":"remove","path":"/spec/pipeline/default-pod-template"}]'

Otherwise set the saved TektonConfig value again.

TaskRunSpecs with Pod Template Configuration

Pod template configurations can be applied to specific Tasks within a PipelineRun using TaskRunSpecs.

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-with-specific-templates
spec:
  pipelineRef:
    name: build-deploy-pipeline
  taskRunTemplate:
    podTemplate:
      # Pod template for all tasks of this PipelineRun
      # A taskRunSpecs entry overrides the fields it sets for its task (env and volumes are merged by name)
      nodeSelector:
        environment: production
      securityContext:
        fsGroup: 65532
  taskRunSpecs:
  - pipelineTaskName: build
    podTemplate:
      # Task-specific pod template configuration
      # nodeSelector and tolerations replace the PipelineRun-level values for the 'build' task;
      # securityContext is not set here, so 'build' keeps fsGroup: 65532 from taskRunTemplate
      nodeSelector:
        disktype: ssd
      tolerations:
      - key: "dedicated"
        operator: "Equal"
        value: "build"
        effect: "NoSchedule"
  - pipelineTaskName: deploy
    podTemplate:
      # Task-specific pod template configuration
      # nodeSelector and securityContext replace the PipelineRun-level values for the 'deploy' task
      nodeSelector:
        environment: production
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000

Important Parameters

Supported Fields

Pod template configuration supports the fields listed in the table below. Pod templates have no CPU or memory field: set compute resources with computeResources on a Step, or with computeResources on the TaskRun or on a PipelineRun taskRunSpecs entry (beta fields, enabled when enable-api-fields is beta, the default).

FieldDescription
envEnvironment variables defined in the Pod template at TaskRun and PipelineRun level take precedence over the ones defined in steps and stepTemplate
nodeSelectorMust be true for the Pod to fit on a node.
tolerationsAllows (but does not require) the Pods to schedule onto nodes with matching taints.
affinityAllows constraining the set of nodes for which the Pod can be scheduled based on the labels present on the node.
securityContextSpecifies Pod-level security attributes and common container settings such as runAsUser and selinux.
volumesSpecifies 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.
runtimeClassNameSpecifies the runtime class for the Pod.
automountServiceAccountTokenDefault: true. Determines whether Tekton automatically provides the token for the service account used by the Pod inside containers at a predefined path.
dnsPolicyDefault: ClusterFirst. Specifies the DNS policy for the Pod. Legal values are ClusterFirst, ClusterFirstWithHostNet, Default, and None; Tekton passes the value to the Pod unchanged. Use ClusterFirstWithHostNet only together with hostNetwork: true.
dnsConfigSpecifies additional DNS configuration for the Pod, such as name servers and search domains.
enableServiceLinksDefault: true. Determines whether services in the Pod's namespace are exposed as environment variables to the Pod.
priorityClassNameSpecifies the priority class for the Pod. Allows you to selectively enable preemption on lower-priority workloads.
schedulerNameSpecifies 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.
imagePullSecretsSpecifies the secret to use when pulling a container image.
hostNetworkDefault: false. Determines whether to use the host network namespace.
hostUsersDefault: true. Determines whether the Pod uses the host's user namespace. Setting it to false requires the Kubernetes UserNamespacesSupport feature gate.
hostAliasesAdds entries to a Pod's /etc/hosts to provide Pod-level overrides of hostnames. For further info see Kubernetes' docs for this field.
topologySpreadConstraintsSpecify how Pods are spread across your cluster among topology domains.

The examples in the following sections show only the podTemplate block. In a TaskRun, place it under spec; in a PipelineRun, place it under spec.taskRunTemplate or in a spec.taskRunSpecs entry.

Node Selection and Scheduling

nodeSelector

Specifies node labels that must be present for Pod scheduling.

Use Cases

  • Ensure Pods run on specific node types (SSD, GPU, etc.)
  • Route workloads to dedicated infrastructure
  • Optimize resource utilization

Configuration Example

podTemplate:
  nodeSelector:
    disktype: ssd
    environment: production

affinity

Allows fine-grained control over Pod scheduling based on node labels.

Use Cases

  • Prefer specific node characteristics
  • Avoid certain node types
  • Balance workload distribution

Configuration Example

podTemplate:
  affinity:
    nodeAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 1
        preference:
          matchExpressions:
          - key: kubernetes.io/arch
            operator: In
            values:
            - amd64

tolerations

Allows Pods to be scheduled on nodes with matching taints.

Use Cases

  • Schedule Pods on dedicated or specialized nodes
  • Handle node maintenance scenarios
  • Optimize resource allocation

Configuration Example

podTemplate:
  tolerations:
  - key: "dedicated"
    operator: "Equal"
    value: "build"
    effect: "NoSchedule"

Security Configuration

securityContext

Specifies Pod-level security attributes and common container settings.

Use Cases

  • Run containers as non-root users
  • Set file system group ownership
  • Configure SELinux settings
  • Apply security policies

Configuration Example

podTemplate:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    runAsGroup: 1000
    fsGroup: 1000
    seccompProfile:
      type: RuntimeDefault

Resource and Volume Management

volumes

Specifies volumes that containers within the Pod can mount.

Use Cases

  • Share data between steps
  • Mount configuration files
  • Provide persistent storage
  • Access secrets and config maps

Configuration Example

podTemplate:
  volumes:
  - name: shared-data
    emptyDir: {}
  - name: config-volume
    configMap:
      name: app-config
  - name: secret-volume
    secret:
      secretName: app-secrets

Network Configuration

dnsPolicy

Specifies the DNS policy for the Pod.

Use Cases

  • Configure custom DNS resolution
  • Handle network isolation requirements
  • Optimize network performance

Configuration Example

podTemplate:
  dnsPolicy: ClusterFirst
  dnsConfig:
    nameservers:
    - <internal-dns-server-ip>
    searches:
    - default.svc.cluster.local
    - svc.cluster.local

Replace <internal-dns-server-ip> with the address of a DNS server that the Pods of your cluster can reach, such as an internal DNS server. In an air-gapped cluster, public resolvers are not reachable.

Determines whether services in the Pod's namespace are exposed as environment variables.

Use Cases

  • Control service discovery behavior
  • Optimize environment variable usage
  • Handle legacy application requirements

Configuration Example

podTemplate:
  enableServiceLinks: false

Image Access Configuration

imagePullSecrets

Specifies secrets to use when pulling container images.

Use Cases

  • Access private container registries
  • Handle registry authentication
  • Support enterprise registry configurations

Configuration Example

podTemplate:
  imagePullSecrets:
  - name: private-registry-secret
  - name: enterprise-registry-secret

Note: The list replaces the pull secrets that Kubernetes would otherwise add from the ServiceAccount: a Pod that gets a list from a Pod template does not get the ServiceAccount's pull secrets. A run's own list also replaces a global list. List every Secret that the Pod needs.

Note: When imagePullSecrets is configured and no command is specified in the Task, Tekton will automatically look up the entrypoint of the image using the configured secrets.

Environment Variables

env

Specifies environment variables for the Pod.

Use Cases

  • Set build environment variables
  • Configure application settings
  • Pass configuration data to containers

Configuration Example

podTemplate:
  env:
  - name: BUILD_ENV
    value: "production"
  - name: DEBUG_LEVEL
    value: "info"
  - name: API_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: app-config
        key: api-endpoint

Best Practices

Configuration Organization

  • Global Configurations: Use for common configurations across all executions
  • Execution-Specific Configurations: Use for unique requirements or overrides
  • Task-Specific Configurations: Use TaskRunSpecs for fine-grained control

Security Considerations

  • Always run containers as non-root users when possible
  • Use appropriate security contexts
  • Configure image pull secrets for private registries
  • Apply least-privilege principles

Resource Optimization

  • Use node selectors to route workloads to appropriate nodes
  • Configure tolerations for specialized infrastructure
  • Set CPU and memory requests and limits with computeResources; Pod templates do not set them
  • Optimize volume configurations for performance

Maintenance

  • Keep configurations simple and focused
  • Document configuration purposes and requirements
  • Version control configuration
  • Test configuration changes in non-production environments

References