Alauda Container Platform Pipelines Docs
  • 简体中文

    • Pod 模板配置指南

    目录

    快速导航为什么使用 Pod 模板？什么是 Pod 模板？何时使用 Pod 模板选择哪种配置方法如何配置 Pod 模板方法 1：TaskRun 层级配置方法 2：PipelineRun 层级配置方法 3：PipelineRun TaskRunSpecs 配置方法 4：全局默认配置（TektonConfig）配置方法比较配置优先级配置示例示例 1：安全默认配置（推荐）示例 2：镜像拉取密钥示例 3：节点调度示例 4：需要 root 访问权限的自定义镜像的覆盖配置示例 5：在旧版全局配置下使用官方 Task示例 6：迁移期间的临时覆盖配置重要注意事项常见陷阱配置范围和生效时机所需权限最佳实践验证全局配置TaskRun/PipelineRun 配置相关文档

    快速导航

    入门：

    常见场景：

    故障排除：

    为什么使用 Pod 模板？

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

    常见挑战：

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

    没有 Pod 模板时：

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

    • 配置重复和维护开销
    • 难以强制执行一致的安全策略
    • 无法使 Community Task（如 Tekton catalog Task）适应您的环境

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

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

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

    什么是 Pod 模板？

    Pod 模板是用于自定义 Tekton TaskRun 和 PipelineRun 的 Pod 规范的配置字段。它们定义了 PodSpec 的一部分，Tekton 使用这些内容来配置执行 Task 和 Pipeline 的 Pod。

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

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

    何时使用 Pod 模板

    Pod 模板适用于以下场景：

    • 安全要求：配置安全上下文（例如 runAsUser、fsGroup）以满足安全策略
    • 访问私有 Registry：配置 image pull secrets，以访问私有容器 Registry
    • 节点调度：配置节点选择器、容忍度或亲和性规则，以控制 Pod 放置位置
    • 资源管理：配置计算资源、卷和存储要求
    • 环境变量：为 Pipeline 执行设置环境变量
    • 网络配置：配置 DNS 策略和网络设置
    • 一致性：确保多次 Pipeline 执行使用一致的执行环境

    选择哪种配置方法

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

    场景推荐方法原因
    具有特殊要求的一次性执行方法 1：TaskRun仅应用于单个 TaskRun。
    在全局应用前测试配置方法 1：TaskRun安全地进行测试，不影响其他执行。
    某个特定 Pipeline 需要特殊配置方法 2：PipelineRun仅覆盖此 Pipeline，不影响其他 Pipeline。
    同一 Pipeline 中的不同 Task 需要不同配置方法 3：TaskRunSpecs按 Task 进行细粒度控制。适用于混合工作负载（官方 Task + 自定义 Task）。
    为集群中的所有 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  # Can be modified as needed (e.g., 0 for root, 1000 for custom user)
      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  # Can be modified as needed (e.g., 0 for root)
        fsGroup: 65532
      nodeSelector:
        environment: production
      imagePullSecrets:
        - name: private-registry-secret

    方法 3：PipelineRun TaskRunSpecs 配置

    为 PipelineRun 中的特定 Task 配置 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  # Override for this specific task if needed
        nodeSelector:
          disktype: ssd
          performance: high
        tolerations:
          - key: "dedicated"
            operator: "Equal"
            value: "build"
            effect: "NoSchedule"
    - pipelineTaskName: deploy
      podTemplate:
        securityContext:
          runAsUser: 65532  # Use secure default for this task
          runAsNonRoot: true
        nodeSelector:
          environment: production

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

    配置一个全局默认 Pod 模板，将其应用于集群中的所有 TaskRun 和 PipelineRun。

    使用场景：为集群中的所有 Pipeline 执行应用一致的基线配置。

    配置位置：TektonConfig 中的 spec.pipeline.default-pod-template

    [安全最佳实践]

    建议使用非 root 用户（例如 runAsUser: 65532）作为默认配置，以遵循最小权限原则。官方 Tekton Task 设计为使用 UID 65532。只有在自定义镜像或旧版应用程序有要求时，才应针对特定的 TaskRun/PipelineRun 覆盖为 runAsUser: 0。

    [为什么是 UID 65532？]

    UID 65532 是官方 Tekton Task 和大多数 Tekton catalog Task 使用的标准非 root 用户 ID。此 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：TaskRunSpecsPipelineRun 中的特定 Task最高混合工作负载（官方 + 自定义 Task）对每个 Task 进行细粒度控制配置更复杂
    方法 4：全局（TektonConfig）集群中的所有 TaskRun/PipelineRun最低基线安全和默认值设置一次，影响所有执行全局影响，需要集群权限

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

    配置优先级

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

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

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

    合并行为：

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

    示例：

    如果存在以下配置：

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

    最终结果为：

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

    配置示例

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

    场景：为所有 Pipeline Task 设置使用非 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 Task 和 catalog Task 设计为使用 UID 65532。此配置可确保所有 Pipeline 执行默认以安全方式运行。

    示例 2：镜像拉取密钥

    场景：配置镜像拉取密钥，以访问私有 registry。

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

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

    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 为特定 Task 进行覆盖，同时为官方 Task 保持安全默认配置。

    # Global baseline configuration (secure default)
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 execution with selective overrides
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: mixed-workload-pipeline-run
spec:
  pipelineRef:
    name: build-deploy-pipeline
  taskRunSpecs:
    # Override ONLY for tasks using custom images that require root
    - pipelineTaskName: custom-build
      podTemplate:
        securityContext:
          runAsUser: 0
        nodeSelector:
          disktype: ssd
    # Tasks using official Tekton catalog Tasks inherit the secure default (65532)
    # No override needed for 'git-clone', 'kaniko-build', etc.

    最佳实践：仅对确实需要 root 访问权限的特定 Task，将 runAsUser 覆盖为 0。让官方 Tekton Task 使用安全默认值（65532）。

    示例 5：在旧版全局配置下使用官方 Task

    场景：你已从 Alauda DevOps Tekton v3 迁移到 Alauda Container Platform Pipelines，并将全局 default-pod-template 设置为 runAsUser: 0，以便与现有自定义镜像保持向后兼容。现在你希望使用官方 Tekton catalog Task，而这些 Task 需要 runAsUser: 65532 和 fsGroup: 65532。

    解决方案：对于使用官方 Task 的 Pipeline，在 PipelineRun 级别覆盖全局配置。

    当前全局配置（迁移期间设置）：

    apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    default-pod-template: |
      securityContext:
        runAsUser: 0  # Legacy global setting for custom images

    官方 Task 的 PipelineRun 配置：

    apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: catalog-tasks-pipeline-run
spec:
  pipelineRef:
    name: pipeline-using-catalog-tasks  # Pipeline using git-clone, buildah, etc.
  taskRunTemplate:
    podTemplate:
      # Override global runAsUser: 0 to use secure settings required by official Tasks
      securityContext:
        runAsUser: 65532
        fsGroup: 65532

    替代方案：对于混合场景，使用 TaskRunSpecs：

    apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: mixed-pipeline-run
spec:
  pipelineRef:
    name: mixed-pipeline
  # Most tasks will use global runAsUser: 0 (for custom images)
  taskRunSpecs:
    # Override only for tasks using official catalog Tasks
    - pipelineTaskName: git-clone
      podTemplate:
        securityContext:
          runAsUser: 65532
          fsGroup: 65532
    - pipelineTaskName: buildah
      podTemplate:
        securityContext:
          runAsUser: 65532
          fsGroup: 65532
    # Other tasks (using custom images) inherit global runAsUser: 0

    长期建议：逐步更新自定义镜像以支持非 root 用户，然后将全局默认值更改为 runAsUser: 65532，以提高安全性。

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

    场景：你当前正在从 Alauda DevOps Tekton v3 迁移到 Alauda Container Platform 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:
      # Temporary override for migration - plan to remove this
      securityContext:
        runAsUser: 0

    迁移路径：

    1. 短期：对需要 root 权限的旧版 Pipeline 使用此覆盖配置
    2. 中期：更新自定义容器镜像以支持非 root 用户（UID 65532）
    3. 长期：移除这些覆盖配置，并依赖安全的全局默认配置

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

    重要注意事项

    常见陷阱

    以下是用户最常遇到的问题。在配置 Pod 模板之前，请先查看这些内容：

    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 时，请使用管道符（|）字符，以确保 YAML 多行字符串格式正确：

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

    配置范围和生效时机

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

    所需权限

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

    最佳实践

    1. 遵循安全最佳实践：始终使用非 root 用户（runAsUser: 65532）作为全局默认值。官方 Tekton 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 中的不同任务需要不同的安全上下文时（例如自定义镜像与官方 Tasks），请使用 taskRunSpecs 应用不同的配置。

    5. 记录安全例外：清楚记录特定任务需要 root 访问权限的原因（runAsUser: 0）。定期检查这些例外，确认是否可以消除。

    6. 测试配置更改：在应用到生产环境之前，先在非生产环境中测试 Pod 模板配置更改，尤其是安全上下文更改。

    验证

    应用 Pod 模板配置后，请验证其是否已生效：

    全局配置

    检查配置是否已应用到 ConfigMap：

    # Check 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

    # For TaskRun
$ kubectl get pods -n <namespace> -l tekton.dev/taskRun=<taskrun-name>

# For PipelineRun (shows all Pods created by the PipelineRun)
$ kubectl get pods -n <namespace> -l tekton.dev/pipelineRun=<pipelinerun-name>

# Example output:
# NAME                                      READY   STATUS      RESTARTS   AGE
# build-task-run-pod                        0/1     Completed   0          2m

    步骤 2：验证 Pod 规范

    # Check the Pod's security context
$ kubectl get pod -n <namespace> <pod-name> -o yaml | grep -A 10 "securityContext:"

  securityContext:
    runAsUser: 65532
    fsGroup: 65532

# Check specific fields
$ kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.securityContext.runAsUser}'
# Should output: 65532 (or your configured value)

# Check fsGroup
$ kubectl get pod -n <namespace> <pod-name> -o jsonpath='{.spec.securityContext.fsGroup}'
# Should output: 65532 (or your configured value)

    相关文档