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.
Important: Pod templates are not separate Kubernetes resources. They are configuration fields within TaskRun and PipelineRun specifications.
TOC
Why Pod Templates are NeededPod Configuration ChallengesTekton's SolutionAdvantagesScenariosConstraints and LimitationsPrinciplesPod Template ProcessingConfiguration Merging StrategyPriority OrderMerging RulesConfiguration ExamplesBasic Pod Template Configuration for TaskRunPod Template Configuration for PipelineRunGlobal Pod Template ConfigurationTaskRunSpecs with Pod Template ConfigurationImportant ParametersSupported FieldsNode Selection and SchedulingnodeSelectoraffinitytolerationsSecurity ConfigurationsecurityContextResource and Volume ManagementvolumesNetwork ConfigurationdnsPolicyenableServiceLinksImage Access ConfigurationimagePullSecretsEnvironment VariablesenvBest PracticesConfiguration OrganizationSecurity ConsiderationsResource OptimizationMaintenanceReferencesWhy 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
computeResourceson aStep, or withcomputeResourceson theTaskRunor on aPipelineRuntaskRunSpecsentry (beta fields, enabled whenenable-api-fieldsisbeta, 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:
- Tekton validates the Pod template configuration
- The configuration is merged with any global Pod template configuration
- For PipelineRuns, the configuration is applied to all TaskRuns unless overridden by taskRunSpecs
- For TaskRuns, the configuration is applied directly to the Pod
- Tekton creates the Pod with the merged configuration
- 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):
- PipelineRun
taskRunSpecs[].podTemplate(highest priority) - Pod template configurations specified intaskRunSpecsfor specific tasks within a PipelineRun - PipelineRun
taskRunTemplate.podTemplate(medium priority) - Pod template configurations specified at the PipelineRun level for all its tasks; for aTaskRunthat you create directly, itsspec.podTemplate - Global default-pod-template (lowest priority) - The global Pod template set in
TektonConfigand written by the Tekton Operator into theconfig-defaultsConfigMap
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
securityContextset intaskRunSpecsreplaces thesecurityContextof the PipelineRun-level Pod template; the two are not merged field by field
Configuration Examples
Basic Pod Template Configuration for TaskRun
Pod Template Configuration for PipelineRun
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.
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.
Save the sample as tektonconfig-pod-template.yaml and merge it into the existing TektonConfig:
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:
To undo the change: if the saved TektonConfig output was empty, remove the field from TektonConfig, which returns to the shipped 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.
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).
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
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
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
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
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
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
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.
enableServiceLinks
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
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
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
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