Pod 模板配置指南
目录
快速导航
入门指南:
常见场景:
故障排查:
为什么使用 Pod 模板?
在生产环境中运行 Tekton Pipelines 时,您可能会遇到默认 Pod 配置无法满足需求的情况:
常见挑战:
- 安全策略要求:组织的安全策略要求所有容器以非 root 用户身份运行,但部分 Pipeline 执行因权限错误失败。
- 私有镜像仓库访问:Pipeline 使用来自私有仓库的自定义镜像,但 Pod 因缺少凭据无法拉取镜像。
- 资源调度:需要将构建任务调度到配备 SSD 存储的高性能节点,但 Pod 被调度到普通节点,导致构建缓慢。
- 多租户环境:不同团队需要为其 Pipeline 设置不同的安全配置、资源配额或节点调度。
- 合规要求:必须满足特定合规标准(如 PCI DSS、HIPAA 等),要求特定的 Pod 安全配置。
没有 Pod 模板时:
您需要修改单个 Task 定义或创建多个不同配置版本的 Task,导致:
- 配置重复且维护成本高
- 难以统一执行安全策略
- 无法灵活适配社区 Tasks(如 Tekton catalog Tasks)
Pod 模板如何解决这些问题:
Pod 模板提供灵活的多层级配置体系,允许您:
- 为集群中所有 Pipeline 设置安全基线配置
- 针对特定 Pipeline 或 Task 进行配置覆盖
- 使用官方 Tekton catalog Tasks 并适配您的环境
- 保持 Task 逻辑与执行环境配置的分离
什么是 Pod 模板?
Pod 模板是允许您自定义 Tekton TaskRuns 和 PipelineRuns 所使用 Pod 规格的配置字段。它定义了 Tekton 用于配置执行 Task 和 Pipeline 的 PodSpec 的一部分。
Pod 模板可在不同层级(全局、单 Pipeline、单 Task)配置,提供灵活的作用范围和优先级控制。
有关 Pod 模板概念及支持字段的详细信息,请参见 Pod Templates Concepts。
何时使用 Pod 模板
Pod 模板适用于以下场景:
- 安全需求:配置安全上下文(如
runAsUser、fsGroup)以满足安全策略
- 私有镜像仓库访问:配置镜像拉取凭据
- 节点调度:配置节点选择器、容忍度或亲和规则以控制 Pod 调度
- 资源管理:配置计算资源、卷和存储需求
- 环境变量:为 Pipeline 执行设置环境变量
- 网络配置:配置 DNS 策略和网络设置
- 一致性:确保多次 Pipeline 执行环境一致
选择哪种配置方法
使用下表快速判断适合您的配置方法:
如何配置 Pod 模板
Pod 模板可在四个不同层级配置,每个层级作用范围和目的不同。
方法 1:TaskRun 级别配置
直接在 TaskRun 中配置 Pod 模板,仅影响该 TaskRun 执行。
使用场景:为单个 TaskRun 执行应用特定配置。
配置位置:TaskRun 的 spec.podTemplate
示例:
apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
name: build-task-run
spec:
taskRef:
name: build-task
podTemplate:
securityContext:
runAsUser: 65532 # 可根据需要修改(如 0 表示 root,1000 表示自定义用户)
fsGroup: 65532
nodeSelector:
disktype: ssd
方法 2:PipelineRun 级别配置
在 PipelineRun 级别配置 Pod 模板,影响该 PipelineRun 中所有 Task,除非被 taskRunSpecs 覆盖。
使用场景:为 Pipeline 中所有 Task 应用一致配置。
配置位置:PipelineRun 的 spec.taskRunTemplate.podTemplate
示例:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: build-deploy-pipeline-run
spec:
pipelineRef:
name: build-deploy-pipeline
taskRunTemplate:
podTemplate:
securityContext:
runAsUser: 65532 # 可根据需要修改(如 0 表示 root)
fsGroup: 65532
nodeSelector:
environment: production
imagePullSecrets:
- name: private-registry-secret
方法 3:PipelineRun TaskRunSpecs 配置
为 PipelineRun 中的特定 Task 配置 Pod 模板,实现对单个 Task 的细粒度控制。
使用场景:同一 Pipeline 中不同 Task 需要不同配置。
配置位置:PipelineRun 的 spec.taskRunSpecs[].podTemplate
示例:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: build-deploy-pipeline-run
spec:
pipelineRef:
name: build-deploy-pipeline
taskRunSpecs:
- pipelineTaskName: build
podTemplate:
securityContext:
runAsUser: 0 # 针对该 Task 的覆盖配置
nodeSelector:
disktype: ssd
performance: high
tolerations:
- key: "dedicated"
operator: "Equal"
value: "build"
effect: "NoSchedule"
- pipelineTaskName: deploy
podTemplate:
securityContext:
runAsUser: 65532 # 该 Task 使用安全默认
runAsNonRoot: true
nodeSelector:
environment: production
方法 4:全局默认配置(TektonConfig)
配置集群范围的默认 Pod 模板,应用于所有 TaskRun 和 PipelineRun。
使用场景:为集群中所有 Pipeline 执行设置统一基线配置。
配置位置:TektonConfig 的 spec.pipeline.default-pod-template
[安全最佳实践]
建议默认配置使用非 root 用户(如 runAsUser: 65532),遵循最小权限原则。官方 Tekton Tasks 设计为使用 UID 65532。仅在自定义镜像或遗留应用确实需要时,针对特定 TaskRun/PipelineRun 覆盖为 runAsUser: 0。
[为什么选择 UID 65532?]
UID 65532 是官方 Tekton Tasks 及大多数 Tekton catalog Tasks 使用的标准非 root 用户 ID,符合最小权限原则,广泛应用于 Tekton 生态的安全最佳实践。
fsGroup:为 Pod 中所有容器设置组 ID,确保 Pod 创建的文件归属该组,保证文件访问权限正确。
步骤:
第 1 步
编辑 TektonConfig 资源:
$ kubectl edit tektonconfigs.operator.tekton.dev config
第 2 步
添加或修改 spec.pipeline.default-pod-template 配置:
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
name: config
spec:
pipeline:
default-pod-template: |
securityContext:
runAsUser: 65532
fsGroup: 65532
imagePullSecrets:
- name: private-registry-secret
第 3 步
验证配置:
$ kubectl get configmap -n tekton-pipelines config-defaults -o yaml | grep 'default-pod-template: |' -A5
配置方法对比
| 方法 | 作用范围 | 优先级 | 适用场景 | 优点 | 缺点 |
|---|
| 方法 1:TaskRun | 单个 TaskRun 执行 | 中等 | 测试、一次性执行 | 安全隔离,易于测试 | 需为每个 TaskRun 配置 |
| 方法 2:PipelineRun | 单个 PipelineRun 中所有 Task | 中等 | 针对 Pipeline 的统一需求 | 易管理,应用于 Pipeline 中所有 Task | 需为每个 PipelineRun 指定 |
| 方法 3:TaskRunSpecs | PipelineRun 中特定 Task | 最高 | 混合工作负载(官方 + 自定义 Tasks) | 细粒度控制每个 Task | 配置较复杂 |
| 方法 4:全局(TektonConfig) | 集群中所有 TaskRun/PipelineRun | 最低 | 基线安全和默认配置 | 一次设置,影响所有执行 | 全局影响,需集群权限 |
优先级规则:同一字段在多个层级配置时,优先级高的生效。TaskRunSpecs(最高)> PipelineRun/TaskRun(中等)> 全局(最低)。
配置优先级
Pod 模板配置遵循明确的优先级层级。存在多个配置时,优先级高的覆盖优先级低的。
优先级顺序(从高到低):
- PipelineRun taskRunSpecs podTemplate - 最高优先级,针对特定 Task
- PipelineRun podTemplate 或 TaskRun podTemplate - 中等优先级,针对 Pipeline 或 Task 级别
- 全局 default-pod-template - 最低优先级,针对所有执行
合并行为:
- 环境变量:按名称合并,优先级高的值覆盖低的
- 卷:按名称合并,优先级高的值覆盖低的
- 其他字段:优先级高的配置完全替换低优先级配置
示例:
假设:
- 全局配置:
runAsUser: 65532(安全默认)
- PipelineRun 配置:
runAsUser: 0(自定义镜像覆盖)
- TaskRunSpec 配置:
runAsUser: 65532(官方 Task 恢复安全默认)
结果:
- 特定 Task(使用官方 Task):
runAsUser: 65532
- Pipeline 中其他 Task(使用自定义镜像):
runAsUser: 0
配置示例
示例 1:安全默认配置(推荐)
场景:为所有 Pipeline 任务设置非 root 用户的安全默认配置,符合安全最佳实践。
全局配置:
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
name: config
spec:
pipeline:
default-pod-template: |
securityContext:
runAsUser: 65532
runAsNonRoot: true
fsGroup: 65532
fsGroupChangePolicy: "OnRootMismatch"
说明:官方 Tekton Tasks 和 catalog Tasks 设计为使用 UID 65532,确保所有 Pipeline 执行默认安全运行。
示例 2:镜像拉取凭据
场景:配置访问私有镜像仓库的镜像拉取凭据。
PipelineRun 配置:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: build-pipeline-run
spec:
pipelineRef:
name: build-pipeline
taskRunTemplate:
podTemplate:
imagePullSecrets:
- name: private-registry-secret
- name: enterprise-registry-secret
示例 3:节点调度
场景:将构建任务调度到高性能节点。
TaskRunSpecs 配置:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: build-deploy-pipeline-run
spec:
pipelineRef:
name: build-deploy-pipeline
taskRunSpecs:
- pipelineTaskName: build
podTemplate:
nodeSelector:
disktype: ssd
performance: high
tolerations:
- key: "dedicated"
operator: "Equal"
value: "build"
effect: "NoSchedule"
示例 4:为需要 root 权限的自定义镜像覆盖配置
场景:全局默认使用安全非 root 用户(65532),但某 Pipeline 中自定义镜像需要 root 权限。使用 TaskRunSpecs 针对特定任务覆盖,同时保持官方 Tasks 的安全默认。
# 全局基线配置(安全默认)
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
name: config
spec:
pipeline:
default-pod-template: |
securityContext:
runAsUser: 65532
fsGroup: 65532
fsGroupChangePolicy: "OnRootMismatch"
imagePullSecrets:
- name: default-registry-secret
---
# Pipeline 执行,选择性覆盖
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: mixed-workload-pipeline-run
spec:
pipelineRef:
name: build-deploy-pipeline
taskRunSpecs:
# 仅覆盖使用需要 root 的自定义镜像的任务
- pipelineTaskName: custom-build
podTemplate:
securityContext:
runAsUser: 0
nodeSelector:
disktype: ssd
# 使用官方 Tekton catalog Tasks 的任务继承安全默认(65532)
# 无需覆盖 'git-clone'、'kaniko-build' 等任务
最佳实践:仅对确实需要 root 权限的任务覆盖为 runAsUser: 0,官方 Tasks 使用安全默认(65532)。
示例 5:使用官方 Tasks 兼容遗留全局配置
场景:您从 Alauda DevOps Tekton v3 迁移至 Alauda DevOps Pipelines,设置了全局 default-pod-template 为 runAsUser: 0 以兼容现有自定义镜像。现在想使用官方 Tekton catalog Tasks,这些 Tasks 需要 runAsUser: 65532 和 fsGroup: 65532。
解决方案:针对使用官方 Tasks 的 Pipeline,在 PipelineRun 级别覆盖全局配置。
当前全局配置(迁移时设置):
apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
name: config
spec:
pipeline:
default-pod-template: |
securityContext:
runAsUser: 0 # 兼容自定义镜像的遗留全局设置
官方 Tasks PipelineRun 配置:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: catalog-tasks-pipeline-run
spec:
pipelineRef:
name: pipeline-using-catalog-tasks # 使用 git-clone、buildah 等 Tasks 的 Pipeline
taskRunTemplate:
podTemplate:
# 覆盖全局 runAsUser: 0,使用官方 Tasks 所需的安全配置
securityContext:
runAsUser: 65532
fsGroup: 65532
替代方案:混合场景使用 TaskRunSpecs:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: mixed-pipeline-run
spec:
pipelineRef:
name: mixed-pipeline
# 大多数任务使用全局 runAsUser: 0(自定义镜像)
taskRunSpecs:
# 仅覆盖使用官方 catalog Tasks 的任务
- pipelineTaskName: git-clone
podTemplate:
securityContext:
runAsUser: 65532
fsGroup: 65532
- pipelineTaskName: buildah
podTemplate:
securityContext:
runAsUser: 65532
fsGroup: 65532
# 其他任务(自定义镜像)继承全局 runAsUser: 0
长期建议:逐步更新自定义镜像以支持非 root 用户,随后将全局默认改为 runAsUser: 65532,提升安全性。
示例 6:迁移期间的临时覆盖
场景:您正在从 Alauda DevOps Tekton v3 迁移至 Alauda DevOps Pipelines,自定义镜像尚未支持非 root 用户。需要临时方案运行遗留 Pipeline,同时更新镜像。
背景:与示例 5(迁移完成,使用全局 runAsUser: 0)不同,此场景适用于:
- 已设置安全全局默认(
runAsUser: 65532)
- 正在迁移遗留 Pipeline
- 需要临时覆盖以支持旧镜像
临时 PipelineRun 配置:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: legacy-pipeline-run
spec:
pipelineRef:
name: legacy-pipeline-requiring-root
taskRunTemplate:
podTemplate:
# 迁移期间的临时覆盖,计划后续移除
securityContext:
runAsUser: 0
迁移路径:
- 短期:对需要 root 的遗留 Pipeline 使用此覆盖
- 中期:更新自定义容器镜像支持非 root 用户(UID 65532)
- 长期:移除覆盖,依赖安全全局默认
重要提示:此为迁移期间的临时解决方案。
重要注意事项
常见陷阱
以下是用户最常遇到的问题,配置 Pod 模板前请务必检查:
-
❌ 全局设置 runAsUser 为 0:切勿在全局 default-pod-template 中设置 runAsUser: 0。这违反安全最佳实践,导致所有 Pipeline 执行暴露于不必要风险。应始终使用 runAsUser: 65532 作为全局默认。需要 root 权限时,仅在 TaskRun/PipelineRun 级别覆盖。
-
❌ 安全上下文冲突:确保 Task 级安全上下文(如 runAsNonRoot: true)与 Pod 模板安全上下文兼容。常见错误:container's runAsUser breaks non-root policy。详见 故障排查:自定义镜像 Pod 创建失败。
-
❌ 配置优先级误解:记住高优先级配置覆盖低优先级:
- TaskRunSpecs(最高)> PipelineRun/TaskRun(中等)> 全局(最低)
- 配置无效时,检查是否被更高优先级配置覆盖。
-
❌ 全局配置影响范围:修改全局 default-pod-template 会影响集群中所有 Pipeline 执行。建议先用 TaskRun/PipelineRun 测试变更。
-
❌ YAML 格式问题:在 TektonConfig 中配置 default-pod-template 时,使用管道符 (|) 以保证多行字符串格式正确:
default-pod-template: |
securityContext:
runAsUser: 65532
配置作用范围与生效时机
- 全局配置:影响配置生效后新创建的 TaskRun 和 PipelineRun,不影响已运行的执行。
- TaskRun/PipelineRun 配置:仅影响对应的执行。
- 配置变更:对新执行立即生效,无需重启 Tekton 组件。
所需权限
- 全局配置:需要集群级权限修改 TektonConfig 资源(通常为 cluster-admin 或等效权限)。
- TaskRun/PipelineRun 配置:需要命名空间级权限创建/修改 TaskRun 或 PipelineRun 资源。
最佳实践
-
遵循安全最佳实践:始终使用非 root 用户(runAsUser: 65532)作为全局默认。官方 Tasks 设计为使用 UID 65532。仅对确实需要 root 权限的任务覆盖为 runAsUser: 0。
-
从安全全局默认开始:在全局 default-pod-template 中配置安全基线:
securityContext:
runAsUser: 65532
runAsNonRoot: true
fsGroup: 65532
-
选择性覆盖:自定义镜像需要 root 权限时,仅在 TaskRun 或 taskRunSpecs 级别覆盖。不要修改全局默认为 runAsUser: 0。
-
使用 TaskRunSpecs 实现细粒度控制:当 Pipeline 中不同任务需要不同安全上下文时,使用 taskRunSpecs 配置。
-
记录安全例外:明确记录为何特定任务需要 root 权限(runAsUser: 0),并定期审查是否可取消这些例外。
-
测试配置变更:在非生产环境测试 Pod 模板配置变更,尤其是安全上下文相关配置。
验证
应用 Pod 模板配置后,验证配置是否生效:
验证全局配置
检查 ConfigMap 中配置是否生效:
# 查看 ConfigMap
$ kubectl get configmap -n tekton-pipelines config-defaults -o yaml | grep 'default-pod-template' -A 10
default-pod-template: |
securityContext:
runAsUser: 65532
预期输出应显示您配置的 Pod 模板。
验证 TaskRun/PipelineRun 配置
步骤 1:查找 TaskRun 或 PipelineRun 创建的 Pod
# 查询 TaskRun 创建的 Pod
$ kubectl get pods -n <namespace> -l tekton.dev/taskRun=<taskrun-name>
# 查询 PipelineRun 创建的所有 Pod
$ kubectl get pods -n <namespace> -l tekton.dev/pipelineRun=<pipelinerun-name>
# 示例输出:
# NAME READY STATUS RESTARTS AGE
# build-task-run-pod 0/1 Completed 0 2m
步骤 2:检查 Pod 规格
# 查看 Pod 的 securityContext
$ kubectl get pod -n <namespace> <pod-name> -o yaml | grep -A 10 "securityContext:"
securityContext:
runAsUser: 65532
fsGroup: 65532
# 检查具体字段
$ kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.securityContext.runAsUser}'
# 应输出:65532(或您配置的值)
# 检查 fsGroup
$ kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.securityContext.fsGroup}'
# 应输出:65532(或您配置的值)
相关文档