Pod 模板

Pod 模板是 TaskRun 和 PipelineRun 规范中的配置字段,可用于自定义 Tekton 工作负载的 Pod 配置。它们定义了 PodSpec 的一部分,Tekton 使用该部分配置执行 Tasks 和 Pipelines 的 Pod。通过此配置,您可以自定义执行环境,而无需修改核心 Task 或 Pipeline 定义。

NOTE

重要:Pod 模板不是独立的 Kubernetes 资源,而是 TaskRun 和 PipelineRun 规范中的配置字段。

为什么需要 Pod 模板

Pod 配置挑战

基于 Kubernetes 的 CI/CD 系统面临多项 Pod 配置挑战:

  • 环境一致性:确保各个 Task 使用一致的执行环境
  • 调度:指定节点选择器、容忍度和亲和性规则。Pod 模板没有 CPU 或内存字段;请在 Step 上使用 computeResources 设置计算资源,或者在 TaskRun 或 PipelineRun taskRunSpecs 条目上使用 computeResources 设置计算资源(这些字段处于 beta 阶段,在 enable-api-fields 为 beta 时启用,这是默认值)
  • 安全性:应用安全上下文和访问控制
  • 网络与存储:配置 DNS 策略、卷和镜像访问

Tekton 的解决方案

Tekton Pod 模板通过提供以下功能解决这些挑战:

  • 可复用性:为多个 TaskRun 和 PipelineRun 定义通用配置
  • 可定制性:自定义执行环境,而无需修改 Task/Pipeline 定义
  • 灵活性:同时支持全局配置和按执行配置

优势

  • 一致性:确保各次 Pipeline 执行使用一致的执行环境
  • 灵活性:针对特定使用场景覆盖默认 Pod 配置
  • 可复用性:仅需定义一次配置,即可应用于多次执行
  • 安全性:在 Pod 级别应用安全策略和访问控制
  • 节点放置:通过节点选择器、容忍度和亲和性规则控制 Pod 的调度位置

场景

Pod 模板适用于各种场景,包括:

  • 资源密集型工作负载:使用节点选择器、容忍度或亲和性规则,将构建/测试 Task 放置在合适的节点上;使用 computeResources 设置其 CPU 和内存,而不是在 Pod 模板中设置
  • 安全敏感型应用:应用安全上下文和访问控制
  • 多节点集群:使用节点选择器和亲和性规则实现最佳调度
  • 访问私有 Registry:为私有 Registry 配置镜像拉取密钥
  • 网络要求:自定义 DNS 策略和网络配置
  • 存储要求:定义卷和存储配置

约束和限制

  • Pod 模板配置仅影响 Pod 配置,不影响 Task 或 Pipeline 逻辑
  • 某些字段可能会被 Tekton 的内部要求覆盖
  • 全局配置会与执行专用配置合并
  • 亲和性助手 Pod 仅支持 Pod 模板配置字段的子集
  • Pod 模板配置无法修改 Tekton 的核心功能或行为

原则

Pod 模板处理

指定 Pod 模板配置时:

  1. Tekton 验证 Pod 模板配置
  2. 将该配置与任何全局 Pod 模板配置合并
  3. 对于 PipelineRun,除非被 taskRunSpecs 覆盖,否则会将该配置应用于所有 TaskRun
  4. 对于 TaskRun,会将该配置直接应用于 Pod
  5. Tekton 使用合并后的配置创建 Pod
  6. Pod 使用指定的配置执行 Task 或 Pipeline 步骤

配置合并策略

Pod 模板配置遵循特定的合并规则,并具有明确的优先级层次结构:

优先级顺序

Pod 模板配置按以下优先级顺序合并(从高到低):

  1. PipelineRun taskRunSpecs[].podTemplate(最高优先级)— 在 PipelineRun 中的 taskRunSpecs 内为特定 Task 指定的 Pod 模板配置
  2. PipelineRun taskRunTemplate.podTemplate(中等优先级)— 在 PipelineRun 级别为其所有 Task 指定的 Pod 模板配置;对于直接创建的 TaskRun,其 spec.podTemplate
  3. 全局 default-pod-template(最低优先级)— 在 TektonConfig 中设置,并由 Tekton Operator 写入 config-defaults ConfigMap 的全局 Pod 模板

同一字段存在多个配置时,高优先级配置会覆盖低优先级配置。

合并规则

  • 环境变量(env):按数组元素中的名称值合并。如果项具有相同名称,则使用来自 TaskRun 或 PipelineRun 的项
  • 卷:按数组元素中的名称值合并。如果项具有相同名称,则使用来自 TaskRun 或 PipelineRun 的项
  • 其他字段:如果某个字段存在于多个配置中,则以高优先级配置为准,并整体替换该字段。例如,在 taskRunSpecs 中设置的 securityContext 会替换 PipelineRun 级别 Pod 模板中的 securityContext;两者不会逐字段合并

配置示例

TaskRun 的基本 Pod 模板配置

apiVersion: tekton.dev/v1
kind: TaskRun
metadata:
  name: build-with-pod-template
spec:
  taskRef:
    name: build-task
  podTemplate:
    nodeSelector:
      disktype: ssd
    tolerations:
    - key: "dedicated"
      operator: "Equal"
      value: "build"
      effect: "NoSchedule"
    securityContext:
      runAsUser: 1000
      runAsGroup: 1000
      fsGroup: 1000
    volumes:
    - name: cache-volume
      emptyDir: {}

PipelineRun 的 Pod 模板配置

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-with-pod-template
spec:
  pipelineRef:
    name: build-deploy-pipeline
  taskRunTemplate:
    podTemplate:
      nodeSelector:
        environment: production
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: kubernetes.io/os
                operator: In
                values:
                - linux
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
      imagePullSecrets:
      - name: registry-secret
      env:
      - name: BUILD_ENV
        value: "production"

运行的 imagePullSecrets 列表会写入其每个 TaskRun Pod,因此 Kubernetes 不再将 ServiceAccount 的拉取 Secret 添加到这些 Pod 中,并且全局默认 Pod 模板的 imagePullSecrets 列表(见下文)也不会使用。请列出运行所需的每个 Secret。

在 tekton.dev/v1 PipelineRun 中,所有 Task 的 Pod 模板为 spec.taskRunTemplate.podTemplate。tekton.dev/v1beta1 PipelineRun 使用了 spec.podTemplate;带有 spec.podTemplate 的 v1 PipelineRun 会被 API server 以 strict decoding error: unknown field "spec.podTemplate" 拒绝。

全局 Pod 模板配置

全局默认 Pod 模板是 tekton-pipelines 命名空间中 config-defaults ConfigMap 的 default-pod-template 键。Tekton Operator 会根据 TektonConfig 写入该 ConfigMap,因此请按照方法 4:全局默认配置(TektonConfig)中的说明,在 TektonConfig 的 spec.pipeline.default-pod-template 中设置该值,不要编辑 ConfigMap。tekton-pipelines 是 TektonConfig spec.targetNamespace 的默认值;如果你的安装使用其他命名空间,请在命令中替换它。

WARNING

该值会应用于集群中每个命名空间内每个新 TaskRun 的 Pod。使用下面的 nodeSelector 后,这些 Pod 只会调度到带有 workload: tekton 标签的节点上;如果没有节点带有该标签,它们会保持 Pending。请在设置该值之前为节点添加标签和污点。下面的 imagePullSecrets 列表会写入每个运行未设置自身列表的 TaskRun Pod,因此 Kubernetes 不再将 ServiceAccount 的拉取 Secret 添加到这些 Pod 中,并且 default-registry-secret 必须存在于运行 TaskRun 的每个命名空间中。该值还会整体替换当前的默认 Pod 模板:先读取它(kubectl get configmap -n tekton-pipelines config-defaults -o jsonpath='{.data.default-pod-template}'),同时读取在 TektonConfig 中设置的值(kubectl get tektonconfig config -o jsonpath='{.spec.pipeline.default-pod-template}'),保存两个输出,并保留默认模板的字段。示例保留了随附的 fsGroup 和 fsGroupChangePolicy。

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  pipeline:
    default-pod-template: |
      nodeSelector:
        workload: tekton
      tolerations:
      - key: "workload"
        operator: "Equal"
        value: "tekton"
        effect: "NoSchedule"
      securityContext:
        fsGroup: 65532
        fsGroupChangePolicy: "OnRootMismatch"
      imagePullSecrets:
      - name: default-registry-secret

将示例保存为 tektonconfig-pod-template.yaml,并将其合并到现有的 TektonConfig 中:

kubectl patch tektonconfig config --type merge --patch-file tektonconfig-pod-template.yaml

检查更改是否已生效。读取 ConfigMap 需要对 tekton-pipelines 中的 ConfigMap 具有读取权限,通常需要集群管理员权限。该命令会输出完整的默认 Pod 模板,该模板必须是示例中的模板:

kubectl get configmap -n tekton-pipelines config-defaults -o jsonpath='{.data.default-pod-template}'

要撤销更改:如果保存的 TektonConfig 输出为空,请从 TektonConfig 中移除该字段,以恢复随附的默认 Pod 模板:

kubectl patch tektonconfig config --type json \
  -p '[{"op":"remove","path":"/spec/pipeline/default-pod-template"}]'

否则,请重新设置保存的 TektonConfig 值。

使用 Pod 模板配置的 TaskRunSpecs

可以使用 TaskRunSpecs 将 Pod 模板配置应用于 PipelineRun 中的特定 Task。

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: build-deploy-with-specific-templates
spec:
  pipelineRef:
    name: build-deploy-pipeline
  taskRunTemplate:
    podTemplate:
      # Pod template for all tasks of this PipelineRun
      # A taskRunSpecs entry overrides the fields it sets for its task (env and volumes are merged by name)
      nodeSelector:
        environment: production
      securityContext:
        fsGroup: 65532
  taskRunSpecs:
  - pipelineTaskName: build
    podTemplate:
      # Task-specific pod template configuration
      # nodeSelector and tolerations replace the PipelineRun-level values for the 'build' task;
      # securityContext is not set here, so 'build' keeps fsGroup: 65532 from taskRunTemplate
      nodeSelector:
        disktype: ssd
      tolerations:
      - key: "dedicated"
        operator: "Equal"
        value: "build"
        effect: "NoSchedule"
  - pipelineTaskName: deploy
    podTemplate:
      # Task-specific pod template configuration
      # nodeSelector and securityContext replace the PipelineRun-level values for the 'deploy' task
      nodeSelector:
        environment: production
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000

重要参数

支持的字段

Pod 模板配置支持下表中列出的字段。Pod 模板没有 CPU 或内存字段:在 Step 上使用 computeResources 设置计算资源,或在 TaskRun 上使用 computeResources,或者在 PipelineRun taskRunSpecs 条目上使用(测试版字段,在 enable-api-fields 为 beta 时启用,默认为该值)。

字段描述
env在 TaskRun 和 PipelineRun 级别的 Pod 模板中定义的环境变量优先于在 steps 和 stepTemplate 中定义的环境变量
nodeSelector必须满足Pod 适合调度到节点这一条件。
tolerations允许(但不要求)Pod 调度到具有匹配污点的节点上。
affinity允许根据节点上存在的标签,限制 Pod 可调度到的节点集合。
securityContext指定 Pod 级别的安全属性和常见的容器设置,例如 runAsUser 和 selinux。
volumes指定 Pod 内容器可以挂载的卷列表。这允许你为 Task 中的每个 volumeMount 指定卷类型。
runtimeClassName指定 Pod 的运行时类。
automountServiceAccountToken默认值:true。确定 Tekton 是否自动为 Pod 中容器使用的 service account 提供令牌,并将其放置在预定义路径下。
dnsPolicy默认值:ClusterFirst。指定 Pod 的DNS 策略。合法值包括 ClusterFirst、ClusterFirstWithHostNet、Default 和 None;Tekton 会将该值原样传递给 Pod。仅将 ClusterFirstWithHostNet 与 hostNetwork: true 一起使用。
dnsConfig指定 Pod 的其他 DNS 配置,例如名称服务器和搜索域。
enableServiceLinks默认值:true。确定 Pod 命名空间中的服务是否作为环境变量暴露给 Pod。
priorityClassName指定 Pod 的优先级类。允许你选择性地对较低优先级的工作负载启用抢占。
schedulerName指定分派 Pod 时使用的调度器。你可以为不同类型的工作负载指定不同的调度器,例如为机器学习工作负载指定 volcano.sh。
imagePullSecrets指定拉取容器镜像时使用的Secret。
hostNetwork默认值:false。确定是否使用主机网络命名空间。
hostUsers默认值:true。确定 Pod 是否使用主机的用户命名空间。将其设置为 false 需要 Kubernetes UserNamespacesSupport 特性门控。
hostAliases向 Pod 的 /etc/hosts 添加条目,以提供 Pod 级别的主机名覆盖。有关详细信息,请参阅Kubernetes 关于此字段的文档。
topologySpreadConstraints指定 Pod 如何在集群中的拓扑域之间分布。

以下各节中的示例仅展示 podTemplate 块。在 TaskRun 中,将其放置在 spec 下;在 PipelineRun 中,将其放置在 spec.taskRunTemplate 下或 spec.taskRunSpecs 条目中。

节点选择和调度

nodeSelector

指定 Pod 调度时必须存在的节点标签。

使用场景

  • 确保 Pod 在特定类型的节点(SSD、GPU 等)上运行
  • 将工作负载路由到专用基础设施
  • 优化资源利用率

配置示例

podTemplate:
  nodeSelector:
    disktype: ssd
    environment: production

affinity

允许根据节点标签对 Pod 调度进行精细控制。

使用场景

  • 优先选择具有特定特征的节点
  • 避免使用某些类型的节点
  • 平衡工作负载分布

配置示例

podTemplate:
  affinity:
    nodeAffinity:
      preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 1
        preference:
          matchExpressions:
          - key: kubernetes.io/arch
            operator: In
            values:
            - amd64

tolerations

允许 Pod 调度到具有匹配污点的节点上。

使用场景

  • 将 Pod 调度到专用或特殊用途的节点上
  • 处理节点维护场景
  • 优化资源分配

配置示例

podTemplate:
  tolerations:
  - key: "dedicated"
    operator: "Equal"
    value: "build"
    effect: "NoSchedule"

安全配置

securityContext

指定 Pod 级别的安全属性和常见的容器设置。

使用场景

  • 以非 root 用户运行容器
  • 设置文件系统组所有权
  • 配置 SELinux 设置
  • 应用安全策略

配置示例

podTemplate:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    runAsGroup: 1000
    fsGroup: 1000
    seccompProfile:
      type: RuntimeDefault

资源和卷管理

volumes

指定 Pod 内容器可以挂载的卷。

使用场景

  • 在步骤之间共享数据
  • 挂载配置文件
  • 提供持久化存储
  • 访问 Secret 和 ConfigMap

配置示例

podTemplate:
  volumes:
  - name: shared-data
    emptyDir: {}
  - name: config-volume
    configMap:
      name: app-config
  - name: secret-volume
    secret:
      secretName: app-secrets

网络配置

dnsPolicy

指定 Pod 的 DNS 策略。

使用场景

  • 配置自定义 DNS 解析
  • 处理网络隔离要求
  • 优化网络性能

配置示例

podTemplate:
  dnsPolicy: ClusterFirst
  dnsConfig:
    nameservers:
    - <internal-dns-server-ip>
    searches:
    - default.svc.cluster.local
    - svc.cluster.local

将 <internal-dns-server-ip> 替换为集群中 Pod 可以访问的 DNS 服务器地址,例如内部 DNS 服务器。在隔离网络集群中,无法访问公共解析器。

确定 Pod 命名空间中的服务是否作为环境变量暴露。

使用场景

  • 控制服务发现行为
  • 优化环境变量使用
  • 处理旧版应用程序要求

配置示例

podTemplate:
  enableServiceLinks: false

镜像访问配置

imagePullSecrets

指定拉取容器镜像时使用的 Secret。

使用场景

  • 访问私有容器注册表
  • 处理注册表身份验证
  • 支持企业注册表配置

配置示例

podTemplate:
  imagePullSecrets:
  - name: private-registry-secret
  - name: enterprise-registry-secret

注意:该列表会替换 Kubernetes 原本从 ServiceAccount 添加的镜像拉取 Secret:从 Pod 模板获取列表的 Pod 不会获得 ServiceAccount 的镜像拉取 Secret。运行自身的列表也会替换全局列表。请列出 Pod 所需的每个 Secret。

注意:配置 imagePullSecrets 且 Task 中未指定命令时,Tekton 将使用配置的 Secret 自动查找镜像的 entrypoint。

环境变量

env

指定 Pod 的环境变量。

使用场景

  • 设置构建环境变量
  • 配置应用程序设置
  • 向容器传递配置数据

配置示例

podTemplate:
  env:
  - name: BUILD_ENV
    value: "production"
  - name: DEBUG_LEVEL
    value: "info"
  - name: API_ENDPOINT
    valueFrom:
      configMapKeyRef:
        name: app-config
        key: api-endpoint

最佳实践

配置组织

  • 全局配置:用于所有执行中的通用配置
  • 特定执行配置:用于独特需求或覆盖配置
  • 特定 Task 配置:使用 TaskRunSpecs 进行细粒度控制

安全注意事项

  • 尽可能始终以非 root 用户运行容器
  • 使用适当的安全上下文
  • 为私有 registry 配置镜像拉取 Secret
  • 应用最小权限原则

资源优化

  • 使用节点选择器将工作负载路由到适当的节点
  • 为专用基础设施配置容忍度
  • 使用 computeResources 设置 CPU 和内存请求与限制;Pod 模板不会设置这些内容
  • 优化卷配置以提升性能

维护

  • 保持配置简单且专注
  • 记录配置用途和要求
  • 对配置进行版本控制
  • 在非生产环境中测试配置更改

参考