Pod Template Configuration Guide
TOC
Quick NavigationWhy Use Pod Templates?What Are Pod Templates?When to Use Pod TemplatesWhich Configuration Method to ChooseHow to Configure Pod TemplatesMethod 1: TaskRun Level ConfigurationMethod 2: PipelineRun Level ConfigurationMethod 3: PipelineRun TaskRunSpecs ConfigurationMethod 4: Global Default Configuration (TektonConfig)Configuration Methods ComparisonConfiguration PriorityConfiguration ExamplesExample 1: Secure Default Configuration (Recommended)Example 2: Image Pull SecretsExample 3: Node SchedulingExample 4: Override for Custom Images Requiring Root AccessExample 5: Using Official Tasks with Legacy Global ConfigurationExample 6: Temporary Override During Active MigrationImportant ConsiderationsCommon PitfallsConfiguration Scope and TimingPermissions RequiredBest PracticesVerificationFor Global ConfigurationFor TaskRun/PipelineRun ConfigurationRelated DocumentationQuick Navigation
Getting Started:
- How do I configure Pod templates? - See the 4 configuration methods
- Which method should I use? - Decision guide
- How do I verify my configuration? - Verification commands
Common Scenarios:
- My custom images need root access - How to override securely
- I migrated from Tekton v3 with global runAsUser: 0 - What to change
Troubleshooting:
- My Pod creation is failing - Check common pitfalls and solutions
Why Use Pod Templates?
When running Tekton Pipelines in production environments, you'll likely encounter scenarios where the default Pod configuration doesn't meet your needs:
Common Challenges:
- Security Policy Requirements: Your organization's security policies require all containers to run as non-root users, but some Pipeline executions fail with permission errors.
- Private Registry Access: Your Pipeline uses custom images from a private registry, but Pods fail to pull images due to missing credentials.
- Resource Scheduling: You need build tasks to run on high-performance nodes with SSD storage, but Pods are scheduled to regular nodes, causing slow builds.
- Multi-tenant Environments: Different teams need different security settings or node placements for their Pipelines.
- Compliance Requirements: You must meet specific compliance standards (PCI DSS, HIPAA, etc.) that mandate certain Pod security configurations.
Without Pod Templates:
You would need to modify individual Task definitions or create multiple versions of the same Task with different configurations, leading to:
- Configuration duplication and maintenance overhead
- Difficulty enforcing consistent security policies
- Unable to adapt community Tasks (like Tekton catalog Tasks) to your environment
How Pod Templates Solve These Problems:
Pod templates provide a flexible, multi-level configuration system that allows you to:
- Set secure baseline configurations for all Pipelines in your cluster
- Override configurations for specific Pipelines or Tasks when needed
- Use official Tekton catalog Tasks while adapting them to your environment
- Maintain separation between Task logic and execution environment configuration
What Are Pod Templates?
Pod templates are configuration fields that allow you to customize the Pod specifications for your Tekton TaskRuns and PipelineRuns. They define a portion of a PodSpec that Tekton uses to configure the Pods executing your Tasks and Pipelines.
Pod templates can be configured at different levels (global, per-pipeline, per-task), providing flexibility to apply configurations with varying scopes and priorities.
For detailed information about Pod template concepts and supported fields, see Pod Templates Concepts.
When to Use Pod Templates
Pod templates are useful in the following scenarios:
- Security Requirements: Configure security contexts (e.g.,
runAsUser,fsGroup) to meet security policies - Private Registry Access: Configure image pull secrets for accessing private container registries
- Node Scheduling: Configure node selectors, tolerations, or affinity rules to control Pod placement
- Volumes: Add Pod volumes, such as an
emptyDircache, thatStepsmount withvolumeMounts. Pod templates have no CPU or memory field; set compute resources withcomputeResourceson aStep, or withcomputeResourceson theTaskRunor on aPipelineRuntaskRunSpecsentry (beta fields, enabled whenenable-api-fieldsisbeta, the default). - Environment Variables: Set environment variables for Pipeline executions
- Network Configuration: Configure DNS policies and network settings
- Consistency: Ensure consistent execution environments across multiple Pipeline executions
Which Configuration Method to Choose
Use this decision guide to quickly determine which configuration method fits your needs:
How to Configure Pod Templates
Pod templates can be configured at four different levels, each serving different purposes and having different scopes of impact.
Method 1: TaskRun Level Configuration
Configure Pod template directly in a TaskRun. This affects only the specific TaskRun execution.
Use Case: Apply specific configurations to individual TaskRun executions.
Configuration Location: spec.podTemplate in TaskRun
Example:
Method 2: PipelineRun Level Configuration
Configure Pod template at the PipelineRun level. This affects all Tasks within the PipelineRun unless overridden by taskRunSpecs.
Use Case: Apply consistent configurations to all Tasks in a Pipeline execution.
Configuration Location: spec.taskRunTemplate.podTemplate in PipelineRun
Example:
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 a global imagePullSecrets list from Method 4 is not used either. List every Secret that the run needs (see Example 2).
Method 3: PipelineRun TaskRunSpecs Configuration
Configure Pod template for specific Tasks within a PipelineRun. This allows fine-grained control over individual Tasks in a Pipeline.
Use Case: Apply different configurations to different Tasks within the same Pipeline execution.
Configuration Location: spec.taskRunSpecs[].podTemplate in PipelineRun
Example:
Method 4: Global Default Configuration (TektonConfig)
Configure a global default Pod template that applies to all TaskRuns and PipelineRuns in the cluster.
Use Case: Apply consistent baseline configurations across all Pipeline executions in the cluster.
Configuration Location: spec.pipeline.default-pod-template in TektonConfig
It is recommended to use a non-root user (e.g., runAsUser: 65532) as the default configuration to follow the principle of least privilege. Official Tekton Tasks are designed to work with UID 65532. Only set runAsUser: 0 on the steps of specific Tasks when required by custom images or legacy applications (see Example 4).
UID 65532 is the standard non-root user ID used by official Tekton Tasks and most Tekton catalog Tasks. This ID follows the principle of least privilege and is widely adopted in the Tekton ecosystem for security best practices.
fsGroup: Adds the group ID as a supplemental group to every container in the Pod; the primary group of the container process does not change. For volume types that support it, Kubernetes also changes the group ownership of the volume to this ID and sets the setgid bit, so new files created in the volume are owned by this group.
Steps:
Step 1
The change applies to every new TaskRun on the cluster. Read the default Pod template in effect and the value set in TektonConfig first, and save both outputs, so that you can keep the default's fields and restore it later:
tekton-pipelines is the default of TektonConfig spec.targetNamespace; replace it in the commands if your installation uses another namespace.
Step 2
Save the spec.pipeline.default-pod-template configuration in a file, for example tektonconfig-pod-template.yaml. The value replaces the current default Pod template as a whole, so the sample keeps the shipped fsGroup: 65532 and fsGroupChangePolicy: "OnRootMismatch" next to runAsUser:
A cluster-wide imagePullSecrets list 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. The named Secret must exist in every namespace that runs TaskRuns. To give a pull secret only to some runs, attach the pull secret to the ServiceAccount that those runs use, and leave imagePullSecrets out of the global template. A per-run list (see Example 2) also works, but it replaces the ServiceAccount's pull secrets in that run's Pods in the same way, so it must name every pull secret that the run needs.
Merge the file into the existing TektonConfig. A merge patch changes only the keys in the file and keeps the other fields of TektonConfig. It needs permission to patch TektonConfig, which is cluster-scoped, usually a cluster administrator:
Do not use kubectl apply -f for a file that holds only part of TektonConfig: a later kubectl apply -f of another partial file deletes the fields that this file set and the later file leaves out, such as this default-pod-template.
To undo the change later: if the saved TektonConfig output was empty, remove the field from TektonConfig; otherwise set the saved TektonConfig value again:
Step 3
Verify the configuration. The command prints the whole default Pod template, which must be the template that you set in Step 2:
Configuration Methods Comparison
Priority Rule: When the same field is configured at multiple levels, the configuration with the higher priority level takes effect. TaskRunSpecs (highest) > PipelineRun/TaskRun (medium) > Global (lowest). A field such as securityContext is replaced as a whole, not merged: a securityContext in a TaskRun Pod template drops every securityContext setting of the global default, including runAsNonRoot, so repeat the settings you still need. The default is the default-pod-template key of the config-defaults ConfigMap in tekton-pipelines (read it as in Step 1 of Method 4). The roles shipped with Tekton Pipelines let every authenticated user read only the pipelines-info ConfigMap in that namespace, so if you cannot read config-defaults, ask your cluster administrator for the default Pod template.
Configuration Priority
Pod template configurations follow a clear priority hierarchy. When multiple configurations exist for the same field, the higher priority configuration overrides the lower priority one.
Priority Order (Highest to Lowest):
- PipelineRun taskRunSpecs podTemplate - Highest priority, applies to specific tasks
- PipelineRun podTemplate or TaskRun podTemplate - Medium priority, applies to pipeline or task level
- Global default-pod-template - Lowest priority, applies to all executions
Merging Behavior:
- Environment Variables: Merged by name; higher priority values override lower priority ones
- Volumes: Merged by name; higher priority values override lower priority ones
- Other Fields: Higher priority configuration completely replaces lower priority configuration
Example:
If you have:
- Global config:
runAsUser: 65532(secure default) - PipelineRun config:
runAsUser: 1000(override for custom images) - TaskRunSpec config:
runAsUser: 65532(restore secure default for official Tasks)
The result will be:
- Specific task (using official Task):
runAsUser: 65532 - Other tasks in the pipeline (using custom images):
runAsUser: 1000
Configuration Examples
Example 1: Secure Default Configuration (Recommended)
Scenario: Set a secure default configuration with non-root user for all Pipeline tasks. This is the recommended baseline configuration that follows security best practices.
Global Configuration:
Note: Official Tekton Tasks and catalog Tasks are designed to work with UID 65532. This configuration ensures all Pipeline executions run securely by default.
Before you merge it into TektonConfig with kubectl patch tektonconfig config --type merge --patch-file <file>, read and save the default Pod template in effect and the value set in TektonConfig, and keep any of the default's fields that you still need. To undo the change: if the saved TektonConfig output was empty, remove the field from TektonConfig; otherwise set the saved TektonConfig value again. These steps are shown in Method 4.
Example 2: Image Pull Secrets
Scenario: Configure image pull secrets for accessing private registries.
PipelineRun Configuration:
The run's own imagePullSecrets list is written into each of its TaskRun Pods, so Kubernetes no longer adds the ServiceAccount's pull secrets to those Pods, and a global imagePullSecrets list from Method 4 is not used either. List every Secret that the run needs.
Example 3: Node Scheduling
Scenario: Run build tasks on high-performance nodes.
TaskRunSpecs Configuration:
Example 4: Override for Custom Images Requiring Root Access
Scenario: Your global default uses secure non-root user (65532), but you have a pipeline with custom images that require root access. Set runAsUser: 0 on the steps of the Task that needs root, and use TaskRunSpecs for that task's Pod template, while maintaining secure defaults for official Tasks.
With set-security-context: true, the default in Alauda DevOps Pipelines, Tekton starts its init containers (for example prepare) with runAsNonRoot: true and without runAsUser, so they run with the Pod-level runAsUser. A Pod-template runAsUser: 0 therefore makes the TaskRun fail (see Common Pitfalls); set runAsUser: 0 in the step securityContext instead. A namespace that enforces the restricted Pod Security Standard rejects the Pod of a step that runs as root (the TaskRun fails with PodAdmissionFailed), so use this example only in a namespace that does not enforce restricted; see Comply with Pod Security Restricted Standard.
Global Configuration (merge it into TektonConfig with kubectl patch tektonconfig config --type merge --patch-file <file>; read and save the current values first and undo the change as described in Method 4):
Task Configuration (the Task that the custom-build pipeline task runs; replace the image with the custom image that needs root):
PipelineRun Configuration (a separate object in the namespace of the run):
The imagePullSecrets list in the global configuration above 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 (see the warning in Method 4).
With this Pod template, the step of custom-build runs as UID 0 and prints 0, while the init containers run as the non-root user of their images.
Best Practice: Only set runAsUser: 0 on the steps of specific Tasks that truly require root access. Let official Tekton Tasks use the secure default (65532).
Example 5: Using Official Tasks with Legacy Global Configuration
Scenario: You migrated from Alauda DevOps Tekton v3 to Alauda Container Platform Pipelines and set the global default-pod-template to runAsUser: 0 for backward compatibility with existing custom images. Now you want to use official Tekton catalog Tasks, which require runAsUser: 65532 and fsGroup: 65532.
With set-security-context: true, the default in Alauda DevOps Pipelines, this global value makes the TaskRuns that use it fail, those of the custom images included (see Common Pitfalls).
Solution: Remove runAsUser: 0 from the global configuration, and run only the steps of the custom-image Tasks as root, as in Example 4.
Current Global Configuration (set during migration):
Read and save the current values first, then set the securityContext of the global configuration of Example 4 in TektonConfig as described in Method 4. Leave out the imagePullSecrets list of that example unless you want it for every TaskRun Pod (see the note under Example 4). Official Tasks then use the secure default without an override, and the custom-image Tasks set runAsUser: 0 on their steps, with the Pod template shown in Example 4 for their pipeline tasks.
Long-term Recommendation: Gradually update your custom images to support non-root users, then remove runAsUser: 0 from their steps.
Example 6: Temporary Override During Active Migration
Scenario: You are currently migrating from Alauda DevOps Tekton v3 to Alauda Container Platform Pipelines and your custom images are not yet updated to support non-root users. You need a temporary solution to run legacy pipelines while you update your images.
Context: Unlike Example 5 (where the global default still sets runAsUser: 0), this scenario is for users who:
- Have a secure global default (
runAsUser: 65532) - Are actively migrating legacy pipelines
- Need temporary overrides while updating container images
Temporary Configuration: A PipelineRun-level Pod template with runAsUser: 0 makes the TaskRuns fail while set-security-context is true (see Common Pitfalls). Set runAsUser: 0 on the steps of the legacy Tasks that require root, and give their pipeline tasks a Pod template securityContext without runAsUser and runAsNonRoot, as in Example 4.
Migration Path:
- Short-term: Use these step settings for legacy pipelines that require root
- Medium-term: Update your custom container images to support non-root users (UID 65532)
- Long-term: Remove these overrides and rely on the secure global default
Important: This is a temporary workaround during active migration.
Important Considerations
Common Pitfalls
These are the most common issues users encounter. Review these before configuring Pod templates:
-
❌ Setting Global runAsUser to 0: Do not set
runAsUser: 0in the globaldefault-pod-template. This violates security best practices and exposes all Pipeline executions to unnecessary risk. Always userunAsUser: 65532as the global default. If you need root access, setrunAsUser: 0on the steps that need it, as in Example 4. -
❌ Security Context Conflicts: A Pod template with
runAsUser: 0, at any level, conflicts with therunAsNonRoot: truethat Tekton sets on its init containers whileset-security-contextistrue, the default. In a namespace that does not enforce therestrictedPod Security Standard, the TaskRun fails withCreateContainerConfigError, and the Pod events showError: container's runAsUser breaks non-root policy (pod: "<pod-name>_<namespace>(<pod-uid>)", container: prepare). In a namespace that enforcesrestricted, the Pod is rejected at admission instead, and the TaskRun fails withPodAdmissionFailed. RemoverunAsUser: 0from the Pod template and set it on the steps that need root, as in Example 4. -
❌ Configuration Priority Misunderstanding: Remember that higher-priority configurations override lower-priority ones:
- TaskRunSpecs (highest) > PipelineRun/TaskRun (medium) > Global (lowest)
- If a configuration doesn't take effect, check for overrides at higher priority levels.
-
❌ Global Configuration Impact: Be cautious when modifying global
default-pod-templateas it affects ALL Pipeline executions in the cluster. Test changes with TaskRun/PipelineRun first. -
❌ YAML Formatting: When configuring
default-pod-templatein TektonConfig, use the pipe (|) character for proper YAML multiline string formatting:
Configuration Scope and Timing
- Global Configuration: Affects all TaskRuns and PipelineRuns created after the configuration is applied. It also reaches the TaskRuns that an already running PipelineRun creates after the change: they get every field of the new default that the PipelineRun did not store when it was created. Fields stored at creation, including those filled in from the previous default, keep their values, and existing Pods do not change.
- TaskRun/PipelineRun Configuration: Affects only the specific execution.
- Configuration Changes: Take effect immediately for new executions. No restart of Tekton components is required.
Permissions Required
- Global Configuration: Requires cluster-level permissions to modify TektonConfig resource (typically cluster-admin or equivalent).
- TaskRun/PipelineRun Configuration: Requires namespace-level permissions to create/modify TaskRun or PipelineRun resources.
Best Practices
-
Follow Security Best Practices: Always use non-root user (
runAsUser: 65532) as the global default. Official Tekton Tasks are designed to work with UID 65532. Only setrunAsUser: 0on the steps of specific Tasks that require root privileges. -
Start with Secure Global Defaults: Configure secure baseline settings in the global
default-pod-template, and keep the shippedfsGroupChangePolicy:Read and save the value in effect and the value set in
TektonConfigbefore the change. To undo it: if the savedTektonConfigoutput was empty, remove the field fromTektonConfig; otherwise set the savedTektonConfigvalue again; see Method 4. -
Override Selectively: When you have custom images requiring root access, set
runAsUser: 0ONLY on the steps of those Tasks, with a Pod template for their tasks that sets norunAsUserorrunAsNonRoot, as in Example 4. Do not change the global default torunAsUser: 0. -
Use TaskRunSpecs for Fine-Grained Control: When different tasks in a pipeline require different security contexts (e.g., custom images vs. official Tasks), use
taskRunSpecsto apply different configurations. -
Document Security Exceptions: Clearly document why specific tasks require root access (
runAsUser: 0). Review these exceptions regularly to see if they can be eliminated. -
Test Configuration Changes: Test Pod template configuration changes in non-production environments before applying to production, especially security context changes.
Verification
After applying Pod template configurations, verify they are effective:
For Global Configuration
Check that the configuration is applied to the ConfigMap. The command prints the whole default Pod template, which must be the template that you set in TektonConfig:
On a default installation, where TektonConfig sets no default-pod-template, it prints the shipped template:
For TaskRun/PipelineRun Configuration
Step 1: Find the Pod created by your TaskRun or PipelineRun
Step 2: Verify the Pod specification
Related Documentation
- Pod Templates Concepts - Detailed explanation of Pod templates, supported fields, and merging behavior
- Troubleshooting: Custom Image Pod Creation Failed - Solutions for common Pod template configuration issues
- Adjusting Optional Configuration Items - General guide for customizing TektonConfig options
- Kubernetes PodSpec Documentation - Official Kubernetes PodSpec reference