Pod 模板配置指南

快速导航

入门：

如何配置 Pod 模板？ - 查看 4 种配置方法
我应该使用哪种方法？ - 决策指南
如何验证我的配置？ - 验证命令

常见场景：

我的自定义镜像需要 root 访问权限 - 如何安全地覆盖
我从 Tekton v3 迁移而来，并且全局配置了 runAsUser: 0 - 如何使用官方 Tekton Tasks

故障排查：

我的 Pod 创建失败了 - 检查常见问题和解决方案

为什么使用 Pod 模板？

在生产环境中运行 Tekton Pipelines 时，你很可能会遇到默认 Pod 配置无法满足需求的场景：

常见挑战：

安全策略要求：你所在组织的安全策略要求所有容器都以非 root 用户运行，但某些 Pipeline 执行因权限错误而失败。
私有镜像仓库访问：你的 Pipeline 使用来自私有镜像仓库的自定义镜像，但由于缺少凭据，Pod 无法拉取镜像。
资源调度：你需要将构建任务运行在带有 SSD 存储的高性能节点上，但 Pod 被调度到普通节点，导致构建速度很慢。
多租户环境：不同团队的 Pipeline 需要不同的安全设置、资源配额或节点放置策略。
合规性要求：你必须满足特定的合规标准（PCI DSS、HIPAA 等），这些标准要求采用某些 Pod 安全配置。

如果没有 Pod 模板：

你需要修改单个 Task 定义，或者为同一个 Task 创建多个不同配置的版本，这会导致：

配置重复和维护开销增加
难以强制执行一致的安全策略
无法将 Community Tasks（例如 Tekton catalog Tasks）适配到你的环境

Pod 模板如何解决这些问题：

Pod 模板提供了一个灵活的多层级配置系统，使你能够：

为集群中的所有 Pipeline 设置安全的基线配置
在需要时为特定 Pipeline 或 Task 覆盖配置
使用官方 Tekton catalog Tasks，同时将其适配到你的环境
将 Task 逻辑与执行环境配置分离

什么是 Pod 模板？

Pod 模板是配置字段，允许你自定义 Tekton TaskRun 和 PipelineRun 的 Pod 规范。它们定义了 PodSpec 的一部分，Tekton 使用这些字段来配置执行你的 Tasks 和 Pipelines 的 Pod。

Pod 模板可以在不同级别进行配置（全局、按 Pipeline、按 Task），从而灵活地根据不同范围和优先级应用配置。

有关 Pod 模板概念和受支持字段的详细信息，请参见 Pod Templates Concepts。

何时使用 Pod 模板

Pod 模板适用于以下场景：

安全要求：配置 security context（例如 runAsUser、fsGroup）以满足安全策略
私有镜像仓库访问：配置 image pull secrets 以访问私有容器镜像仓库
节点调度：配置 node selector、toleration 或 affinity 规则来控制 Pod 放置
资源管理：配置计算资源、卷和存储需求
环境变量：为 Pipeline 执行设置环境变量
网络配置：配置 DNS policy 和网络设置
一致性：确保多次 Pipeline 执行之间的执行环境保持一致

选择哪种配置方法

使用此决策指南，快速确定哪种配置方法最适合你的需求：

场景	推荐方法	原因
一次性的、带有特殊要求的执行	方法 1：TaskRun	仅应用于单个 TaskRun。
在全局应用之前先测试某个配置	方法 1：TaskRun	可安全测试，不影响其他执行。
某个特定 Pipeline 需要特殊配置	方法 2：PipelineRun	仅覆盖这个 Pipeline，不影响其他 Pipeline。
同一个 Pipeline 中的不同 Task 需要不同配置	方法 3：TaskRunSpecs	按 Task 进行细粒度控制，适用于混合工作负载（官方 + 自定义 Tasks）。
为集群中的所有 Pipeline 设置基线配置	方法 4：全局（TektonConfig）	配置一次即可影响所有执行。适合安全默认值和 image pull secrets。

如何配置 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 中的所有 Tasks，除非被 taskRunSpecs 覆盖。

使用场景：为一次 Pipeline 执行中的所有 Tasks 应用一致的配置。

配置位置：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 中的特定 Tasks 配置 Pod 模板。这允许对 Pipeline 中的单个 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 一起工作。仅在自定义镜像或旧版应用需要时，才将 runAsUser 覆盖为 0。

[为什么是 UID 65532？]

UID 65532 是官方 Tekton Tasks 和大多数 Tekton catalog Tasks 使用的标准非 root 用户 ID。该 ID 遵循最小权限原则，并且在 Tekton 生态中被广泛采用，作为安全最佳实践。

fsGroup：为 Pod 中的所有容器设置 group ID。这可确保 Pod 创建的文件归指定组所有，从而允许正确的文件访问权限。

步骤：

Step 1

编辑 TektonConfig 资源：

$ kubectl edit tektonconfigs.operator.tekton.dev config

Step 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

Step 3

验证配置：

$ kubectl get configmap -n tekton-pipelines config-defaults -o yaml | grep 'default-pod-template: |' -A5

配置方法对比

方法	范围	优先级	何时使用	优势	劣势
方法 1：TaskRun	单个 TaskRun 执行	中	测试、一次性执行	安全、隔离、易于测试	需要为每个 TaskRun 单独配置
方法 2：PipelineRun	一个 PipelineRun 中的所有 tasks	中	需要特定 Pipeline 配置	易于管理，适用于 Pipeline 中的所有 tasks	必须为每个 PipelineRun 指定
方法 3：TaskRunSpecs	PipelineRun 中的特定 tasks	最高	混合工作负载（官方 + 自定义 Tasks）	按 task 进行细粒度控制	配置更复杂
方法 4：全局（TektonConfig）	集群中的所有 TaskRun/PipelineRun	最低	基线安全和默认值	配置一次，影响所有执行	全局影响，需要集群权限

优先级规则：当同一字段在多个级别配置时，优先级更高的配置将生效。TaskRunSpecs（最高）> PipelineRun/TaskRun（中）> Global（最低）。

配置优先级

Pod 模板配置遵循清晰的优先级层级。当同一字段存在多个配置时，优先级更高的配置会覆盖优先级更低的配置。

优先级顺序（从高到低）：

PipelineRun taskRunSpecs podTemplate - 最高优先级，适用于特定 tasks
PipelineRun podTemplate 或 TaskRun podTemplate - 中等优先级，适用于 Pipeline 或 task 级别
Global default-pod-template - 最低优先级，适用于所有执行

合并行为：

Environment Variables：按名称合并；优先级更高的值覆盖更低优先级的值
Volumes：按名称合并；优先级更高的值覆盖更低优先级的值
其他字段：优先级更高的配置会完全替换优先级更低的配置

示例：

如果你有：

全局配置：runAsUser: 65532（安全默认值）
PipelineRun 配置：runAsUser: 0（为自定义镜像覆盖）
TaskRunSpec 配置：runAsUser: 65532（为官方 Tasks 恢复安全默认值）

结果将是：

特定 task（使用官方 Task）：runAsUser: 65532
Pipeline 中的其他 tasks（使用自定义镜像）：runAsUser: 0

配置示例

示例 1：安全默认配置（推荐）

场景：为所有 Pipeline tasks 设置使用非 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：Image Pull Secrets

场景：配置 image pull secrets 以访问私有仓库。

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：节点调度

场景：在高性能节点上运行构建 tasks。

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 进行覆盖，同时为官方 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 的自定义镜像的 tasks 覆盖
    - pipelineTaskName: custom-build
      podTemplate:
        securityContext:
          runAsUser: 0
        nodeSelector:
          disktype: ssd
    # 使用官方 Tekton catalog Tasks 的 tasks 会继承安全默认值（65532）
    # 'git-clone'、'kaniko-build' 等无需覆盖

最佳实践：仅对确实需要 root 访问权限的特定 tasks，将 runAsUser 覆盖为 0。让官方 Tekton 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 等的 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
  # 大多数 tasks 将使用全局 runAsUser: 0（用于自定义镜像）
  taskRunSpecs:
    # 仅为使用官方 catalog Tasks 的 tasks 覆盖
    - pipelineTaskName: git-clone
      podTemplate:
        securityContext:
          runAsUser: 65532
          fsGroup: 65532
    - pipelineTaskName: buildah
      podTemplate:
        securityContext:
          runAsUser: 65532
          fsGroup: 65532
    # 其他 tasks（使用自定义镜像）继承全局 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 级别覆盖。
❌ security context 冲突：确保 Task 级别的 security context 设置（例如 runAsNonRoot: true）与 Pod 模板的 security context 兼容。常见错误：container's runAsUser breaks non-root policy。有关解决方案，请参见 Troubleshooting: Custom Image Pod Creation Failed。
❌ 对配置优先级的误解：请记住，更高优先级的配置会覆盖更低优先级的配置：
- TaskRunSpecs（最高）> PipelineRun/TaskRun（中）> Global（最低）
- 如果某个配置未生效，请检查更高优先级级别是否存在覆盖。
❌ 全局配置影响：修改全局 default-pod-template 时要谨慎，因为它会影响集群中的所有 Pipeline 执行。请先使用 TaskRun/PipelineRun 进行测试。
❌ YAML 格式：在 TektonConfig 中配置 default-pod-template 时，请使用竖线符号（|）以正确格式化 YAML 多行字符串：
default-pod-template: | securityContext: runAsUser: 65532

配置范围和生效时间

全局配置：会影响配置应用后新创建的所有 TaskRun 和 PipelineRun。不会影响已经在运行中的执行。
TaskRun/PipelineRun 配置：仅影响特定的执行。
配置变更：会立即对新的执行生效。无需重启 Tekton 组件。

所需权限

全局配置：需要集群级权限来修改 TektonConfig 资源（通常为 cluster-admin 或等效权限）。
TaskRun/PipelineRun 配置：需要命名空间级权限来创建/修改 TaskRun 或 PipelineRun 资源。

最佳实践

遵循安全最佳实践：始终使用非 root 用户（runAsUser: 65532）作为全局默认值。官方 Tekton Tasks 的设计可与 UID 65532 一起工作。仅对需要 root 权限的特定 tasks 覆盖为 runAsUser: 0。
从安全的全局默认值开始：在全局 default-pod-template 中配置安全的基线设置：
securityContext: runAsUser: 65532 runAsNonRoot: true fsGroup: 65532
选择性覆盖：当自定义镜像需要 root 访问权限时，只在这些特定 tasks 的 TaskRun 或 taskRunSpecs 级别进行覆盖。不要将全局默认值改为 runAsUser: 0。
使用 TaskRunSpecs 进行细粒度控制：当 Pipeline 中不同的 tasks 需要不同的 security context（例如自定义镜像与官方 Tasks）时，使用 taskRunSpecs 应用不同配置。
记录安全例外：清晰记录为什么某些 tasks 需要 root 访问权限（runAsUser: 0）。定期审查这些例外，看看是否可以消除。
测试配置变更：在将 Pod 模板配置变更应用到生产环境之前，先在非生产环境中进行测试，尤其是 security context 相关变更。

验证

应用 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
$ kubectl get pods -n <namespace> -l tekton.dev/taskRun=<taskrun-name>

# 对于 PipelineRun（显示由该 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 的 security context
$ 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（或你配置的值）

Pod 模板配置指南

目录

快速导航

为什么使用 Pod 模板？

什么是 Pod 模板？

何时使用 Pod 模板

选择哪种配置方法

如何配置 Pod 模板

方法 1：TaskRun 级别配置

方法 2：PipelineRun 级别配置

方法 3：PipelineRun TaskRunSpecs 配置

方法 4：全局默认配置（TektonConfig）

Step 1

Step 2

Step 3

配置方法对比

配置优先级

配置示例

示例 1：安全默认配置（推荐）

示例 2：Image Pull Secrets

示例 3：节点调度

示例 4：为需要 root 访问权限的自定义镜像覆盖

示例 5：使用官方 Tasks 和旧版全局配置

示例 6：迁移期间的临时覆盖

重要注意事项

常见问题

配置范围和生效时间

所需权限

最佳实践

验证

对于全局配置

对于 TaskRun/PipelineRun 配置

相关文档

#Pod 模板配置指南

#目录

#快速导航

#为什么使用 Pod 模板？

#什么是 Pod 模板？

#何时使用 Pod 模板

#选择哪种配置方法

#如何配置 Pod 模板

#方法 1：TaskRun 级别配置

#方法 2：PipelineRun 级别配置

#方法 3：PipelineRun TaskRunSpecs 配置

#方法 4：全局默认配置（TektonConfig）

#Step 1

#Step 2

#Step 3

#配置方法对比

#配置优先级

#配置示例

#示例 1：安全默认配置（推荐）

#示例 2：Image Pull Secrets

#示例 3：节点调度

#示例 4：为需要 root 访问权限的自定义镜像覆盖

#示例 5：使用官方 Tasks 和旧版全局配置

#示例 6：迁移期间的临时覆盖

#重要注意事项

#常见问题

#配置范围和生效时间

#所需权限

#最佳实践

#验证

#对于全局配置

#对于 TaskRun/PipelineRun 配置

#相关文档

Pod 模板配置指南

目录

快速导航

为什么使用 Pod 模板？

什么是 Pod 模板？

何时使用 Pod 模板

选择哪种配置方法

如何配置 Pod 模板

方法 1：TaskRun 级别配置

方法 2：PipelineRun 级别配置

方法 3：PipelineRun TaskRunSpecs 配置

方法 4：全局默认配置（TektonConfig）

Step 1

Step 2

Step 3

配置方法对比

配置优先级

配置示例

示例 1：安全默认配置（推荐）

示例 2：Image Pull Secrets

示例 3：节点调度

示例 4：为需要 root 访问权限的自定义镜像覆盖

示例 5：使用官方 Tasks 和旧版全局配置

示例 6：迁移期间的临时覆盖

重要注意事项

常见问题

配置范围和生效时间

所需权限

最佳实践

验证

对于全局配置

对于 TaskRun/PipelineRun 配置

相关文档