Tekton Pod Template: Customize TaskRun Pod Specs (2026)

Tekton’s PodTemplate allows you to inject arbitrary fields into the PodSpec of the containers it creates, and most people don’t realize you can use it to grant extra privileges to your build containers that they wouldn’t normally have.

Let’s say you have a Task that needs to interact with the Kubernetes API directly, perhaps to create a Service or Ingress object as part of your build process. Normally, your Task’s containers run with the default service account, which has limited permissions. To grant it more power, you’d typically create a dedicated ServiceAccount with appropriate RBAC roles and then configure your TaskRun to use it.

However, with PodTemplate, you can achieve this without creating a separate ServiceAccount or modifying RBAC. You can directly inject a securityContext into the PodSpec that grants elevated privileges.

Here’s a Task definition that uses PodTemplate to add a securityContext to the PodSpec of its steps:

apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: pod-template-example
spec:
  params:
    - name: image
      type: string
      description: The image to use for the steps
      default: ubuntu:latest
  steps:
    - name: run-with-extra-privs
      image: $(params.image)
      script: |
        #!/bin/bash
        echo "Running with elevated privileges..."
        # Example: Attempt to create a dummy Service (this will likely fail without actual RBAC)
        # but demonstrates the intent of having API access.
        kubectl create service clusterip my-test-service --tcp=80:80
        echo "kubectl command executed."
  podTemplate:
    securityContext:
      runAsUser: 0 # Run as root
      privileged: true # Grant all Linux capabilities

Now, when a TaskRun is created for this Task, the resulting PodSpec will include the securityContext defined in podTemplate. The runAsUser: 0 will ensure the container runs as the root user, and privileged: true grants the container all Linux capabilities, effectively making it equivalent to running as root on the host.

Here’s how a TaskRun for the above Task would look:

apiVersion: tekton.dev/v1beta1
kind: TaskRun
metadata:
  name: pod-template-example-run
spec:
  taskRef:
    name: pod-template-example
  params:
    - name: image
      value: "ubuntu:latest"

When Tekton spins up the Pod for this TaskRun, the PodSpec will look something like this (simplified for clarity):

apiVersion: v1
kind: Pod
metadata:
  # ... other metadata ...
spec:
  containers:
    - name: tekton-step-run-with-extra-privs
      # ... other container spec ...
      securityContext:
        runAsUser: 0
        privileged: true
  # ... other pod spec ...

This securityContext is directly applied to the Pod created by Tekton, not just to the individual steps. This means any command executed within the container will inherit these elevated privileges.

The most surprising part is that PodTemplate isn’t just for securityContext. You can inject any valid field from a Kubernetes PodSpec here. For instance, you could add nodeSelector or tolerations to ensure your build pods land on specific nodes, or even mount hostPath volumes if absolutely necessary (though this is generally discouraged for security reasons).

Consider this podTemplate that adds a nodeSelector:

  podTemplate:
    nodeSelector:
      disktype: ssd
    tolerations:
      - key: "key-to-taint"
        operator: "Exists"
        effect: "NoSchedule"

This would ensure that the TaskRun’s Pod is scheduled only on nodes with the label disktype: ssd and that it can tolerate a NoSchedule taint with the key key-to-taint. This level of control allows for sophisticated workload placement and management directly within your Tekton pipeline definitions.

The key takeaway is that PodTemplate offers a powerful, declarative way to customize the underlying Kubernetes Pods that Tekton uses for executing your tasks. It bridges the gap between Tekton’s declarative pipeline definitions and the granular control offered by Kubernetes Pod specifications, allowing for advanced use cases like granting elevated privileges or controlling pod scheduling without resorting to external configurations or complex workarounds.

The next logical step after customizing pod specs is to explore how to manage secrets and sensitive data within your Tekton pipelines.