Alauda DevOps Pipelines Docs
  • 简体中文

    • Pod 模板配置指南

    目录

    快速导航

    快速入门：

    常见场景：

    故障排查：

    为什么使用 Pod 模板？

    在生产环境运行 Tekton Pipelines 时，您可能会遇到默认 Pod 配置无法满足需求的情况：

    常见挑战：

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

    没有 Pod 模板时：

    您需要修改单个 Task 定义或创建多个同一 Task 的不同版本，导致：

    • 配置重复且维护成本高
    • 难以统一执行安全策略
    • 无法适配社区 Tasks（如 Tekton catalog Tasks）到您的环境

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

    Pod 模板提供灵活的多层级配置体系，允许您：

    • 为集群中所有 Pipeline 设置安全基线配置
    • 针对特定 Pipeline 或 Task 进行覆盖配置
    • 使用官方 Tekton catalog Tasks 并适配您的环境
    • 保持 Task 逻辑与执行环境配置的分离

    什么是 Pod 模板？

    Pod 模板是允许您自定义 Tekton TaskRun 和 PipelineRun 所创建 Pod 规格的配置字段。它定义了 Tekton 用于配置执行 Task 和 Pipeline 的 PodSpec 的一部分。

    Pod 模板可在不同层级（全局、单 Pipeline、单 Task）配置，提供不同范围和优先级的灵活配置能力。

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

    何时使用 Pod 模板

    Pod 模板适用于以下场景：

    • 安全需求：配置安全上下文（如 runAsUser、fsGroup）以满足安全策略
    • 私有镜像仓库访问：配置镜像拉取凭据
    • 节点调度：配置节点选择器、容忍度或亲和性规则控制 Pod 调度
    • 资源管理：配置计算资源、卷和存储需求
    • 环境变量：设置 Pipeline 执行的环境变量
    • 网络配置：配置 DNS 策略和网络设置
    • 一致性：确保多次 Pipeline 执行环境一致

    我应该选择哪种配置方法

    使用此决策指南快速确定适合您的配置方法：

    场景推荐方法原因
    一次性执行，带特殊需求方法 1：TaskRun仅应用于单个 TaskRun。
    先测试配置再全局应用方法 1：TaskRun安全测试，不影响其他执行。
    某个特定 Pipeline 需要特殊配置方法 2：PipelineRun仅覆盖该 Pipeline，不影响其他 Pipeline。
    同一 Pipeline 中不同任务需要不同配置方法 3：TaskRunSpecs任务级细粒度控制，适合混合工作负载（官方 + 自定义 Tasks）。
    为集群中所有 Pipeline 设置基线配置方法 4：全局（TektonConfig）一次设置，影响所有执行。适合安全默认、镜像拉取凭据等。

    如何配置 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 中所有任务应用统一配置。

    配置位置：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 中的特定任务配置 Pod 模板，实现对单个任务的细粒度控制。

    使用场景：同一 Pipeline 中不同任务需要不同配置。

    配置位置：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  # 针对该任务的覆盖配置
        nodeSelector:
          disktype: ssd
          performance: high
        tolerations:
          - key: "dedicated"
            operator: "Equal"
            value: "build"
            effect: "NoSchedule"
    - pipelineTaskName: deploy
      podTemplate:
        securityContext:
          runAsUser: 65532  # 该任务使用安全默认
          runAsNonRoot: true
        nodeSelector:
          environment: production

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

    配置集群范围内所有 TaskRun 和 PipelineRun 的默认 Pod 模板。

    使用场景：为集群中所有 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 中所有任务中等针对 Pipeline 的需求易管理，应用于 Pipeline 中所有任务需为每个 PipelineRun 指定
    方法 3：TaskRunSpecsPipelineRun 中特定任务最高混合工作负载（官方 + 自定义 Tasks）任务级细粒度控制配置更复杂
    方法 4：全局（TektonConfig）集群中所有 TaskRun/PipelineRun最低安全基线和默认配置一次设置，影响所有执行影响全局，需集群权限

    优先级规则：同一字段在多个层级配置时，优先级高的配置生效。TaskRunSpecs（最高） > PipelineRun/TaskRun（中等） > 全局（最低）。

    配置优先级

    Pod 模板配置遵循明确的优先级层级。多个配置同时存在时，优先级高的覆盖优先级低的。

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

    1. PipelineRun taskRunSpecs podTemplate - 最高优先级，针对特定任务
    2. PipelineRun podTemplate 或 TaskRun podTemplate - 中等优先级，针对 Pipeline 或 Task 级别
    3. 全局 default-pod-template - 最低优先级，针对所有执行

    合并行为：

    • 环境变量：按名称合并，优先级高的覆盖低的
    • 卷：按名称合并，优先级高的覆盖低的
    • 其他字段：优先级高的配置完全替换低优先级配置

    示例：

    假设有：

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

    结果为：

    • 特定任务（使用官方 Task）：runAsUser: 65532
    • Pipeline 中其他任务（使用自定义镜像）：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（要求 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

    迁移路径：

    1. 短期：对需要 root 的遗留 Pipeline 使用此覆盖
    2. 中期：更新自定义容器镜像支持非 root 用户（UID 65532）
    3. 长期：移除覆盖，依赖安全全局默认

    重要提示：这是迁移期间的临时解决方案。

    重要注意事项

    常见陷阱

    以下是用户最常遇到的问题，配置前请仔细检查：

    1. ❌ 全局设置 runAsUser 为 0：切勿在全局 default-pod-template 中设置 runAsUser: 0，这违背安全最佳实践，导致所有 Pipeline 执行暴露风险。应始终使用 runAsUser: 65532 作为全局默认。需要 root 权限时，仅在 TaskRun/PipelineRun 级别覆盖。

    2. ❌ 安全上下文冲突：确保 Task 级安全上下文（如 runAsNonRoot: true）与 Pod 模板安全上下文兼容。常见错误为 container's runAsUser breaks non-root policy。详见 故障排查：自定义镜像 Pod 创建失败。

    3. ❌ 配置优先级误解：记住高优先级配置覆盖低优先级：

      • TaskRunSpecs（最高） > PipelineRun/TaskRun（中等） > 全局（最低）
      • 配置无效时，检查是否被更高优先级配置覆盖。

    4. ❌ 全局配置影响范围：修改全局 default-pod-template 会影响集群中所有 Pipeline 执行。建议先用 TaskRun/PipelineRun 测试。

    5. ❌ YAML 格式：在 TektonConfig 中配置 default-pod-template 时，使用管道符 (|) 进行多行字符串格式化：

      default-pod-template: |
  securityContext:
    runAsUser: 65532

    配置范围与生效时机

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

    所需权限

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

    最佳实践

    1. 遵循安全最佳实践：全局默认使用非 root 用户（runAsUser: 65532）。官方 Tasks 设计为使用 UID 65532。仅对确实需要 root 权限的任务覆盖为 runAsUser: 0。

    2. 从安全全局默认开始：在全局 default-pod-template 中配置安全基线：

      securityContext:
  runAsUser: 65532
  runAsNonRoot: true
  fsGroup: 65532

    3. 选择性覆盖：自定义镜像需要 root 权限时，仅在 TaskRun 或 taskRunSpecs 级别覆盖。不要修改全局默认为 runAsUser: 0。

    4. 使用 TaskRunSpecs 实现细粒度控制：当同一 Pipeline 中不同任务需要不同安全上下文时，使用 taskRunSpecs 应用不同配置。

    5. 记录安全例外：清晰记录为何特定任务需要 root 权限，定期审查是否可取消例外。

    6. 测试配置变更：在非生产环境测试 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（或您配置的值）

    相关文档