Pod 模板配置指南
目录
快速导航为什么使用 Pod 模板?什么是 Pod 模板?何时使用 Pod 模板选择哪种配置方法如何配置 Pod 模板方法 1:TaskRun 级别配置方法 2:PipelineRun 级别配置方法 3:PipelineRun TaskRunSpecs 配置方法 4:全局默认配置(TektonConfig)配置方法比较配置优先级配置示例示例 1:安全默认配置(推荐)示例 2:镜像拉取 Secret示例 3:节点调度示例 4:需要 root 访问权限的自定义镜像的覆盖配置示例 5:在旧版全局配置下使用官方 Task示例 6:迁移期间的临时覆盖配置重要注意事项常见问题配置范围和时机所需权限最佳实践验证对于全局配置对于 TaskRun/PipelineRun 配置相关文档快速导航
入门:
- 如何配置 Pod 模板? - 查看 4 种配置方法
- 应该使用哪种方法? - 决策指南
- 如何验证配置? - 验证命令
常见场景:
- 我的自定义镜像需要 root 访问权限 - 了解如何安全地覆盖配置
- 我已从使用全局 runAsUser: 0 的 Tekton v3 迁移 - 了解需要更改的内容
故障排除:
- 我的 Pod 创建失败 - 检查常见问题及解决方案
为什么使用 Pod 模板?
在生产环境中运行 Tekton Pipelines 时,您可能会遇到默认 Pod 配置无法满足需求的情况:
常见挑战:
- 安全策略要求:您所在组织的安全策略要求所有容器都以非 root 用户运行,但某些 Pipeline 执行会因权限错误而失败。
- 私有 Registry 访问:您的 Pipeline 使用来自私有 Registry 的自定义镜像,但 Pod 因缺少凭据而无法拉取镜像。
- 资源调度:您需要在配备 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:配置镜像拉取 Secret,以访问私有容器 Registry
- 节点调度:配置节点选择器、容忍度或亲和性规则,以控制 Pod 的放置位置
- 卷:添加 Pod 卷,例如
emptyDir缓存,该缓存由Steps使用volumeMounts挂载。Pod 模板没有 CPU 或内存字段;请在Step上使用computeResources设置计算资源,或者在TaskRun上使用computeResources,也可以在PipelineRuntaskRunSpecs条目上使用(这些是 beta 字段,在enable-api-fields为beta时启用,默认即为此值)。 - 环境变量:为 Pipeline 执行设置环境变量
- 网络配置:配置 DNS 策略和网络设置
- 一致性:确保多次 Pipeline 执行使用一致的执行环境
选择哪种配置方法
使用此决策指南快速确定符合您需求的配置方法:
如何配置 Pod 模板
Pod 模板可以在四个不同级别进行配置,每个级别都有不同的用途和影响范围。
方法 1:TaskRun 级别配置
直接在 TaskRun 中配置 Pod 模板。这只会影响特定的 TaskRun 执行。
使用场景:为单个 TaskRun 执行应用特定配置。
配置位置:TaskRun 中的 spec.podTemplate
示例:
方法 2:PipelineRun 级别配置
在 PipelineRun 级别配置 Pod 模板。除非被 taskRunSpecs 覆盖,否则这会影响 PipelineRun 中的所有 Task。
使用场景:为一次 Pipeline 执行中的所有 Task 应用一致的配置。
配置位置:PipelineRun 中的 spec.taskRunTemplate.podTemplate
示例:
运行的 imagePullSecrets 列表会写入其每个 TaskRun Pod,因此 Kubernetes 不再将 ServiceAccount 的拉取 Secret 添加到这些 Pod 中,并且也不会使用方法 4中的全局 imagePullSecrets 列表。请列出运行所需的每个 Secret(请参阅示例 2)。
方法 3:PipelineRun TaskRunSpecs 配置
为 PipelineRun 中的特定 Task 配置 Pod 模板。这可以对 Pipeline 中的各个 Task 进行精细控制。
使用场景:为同一次 Pipeline 执行中的不同 Task 应用不同配置。
配置位置:PipelineRun 中的 spec.taskRunSpecs[].podTemplate
示例:
方法 4:全局默认配置(TektonConfig)
配置全局默认 Pod 模板,将其应用于集群中的所有 TaskRun 和 PipelineRun。
使用场景:在集群中的所有 Pipeline 执行之间应用一致的基线配置。
配置位置:TektonConfig 中的 spec.pipeline.default-pod-template
建议使用非 root 用户(例如 runAsUser: 65532)作为默认配置,以遵循最小权限原则。官方 Tekton Task 的设计目标是使用 UID 65532。只有在自定义镜像或旧版应用需要时,才在特定 Task 的步骤上设置 runAsUser: 0(请参阅示例 4)。
UID 65532 是官方 Tekton Task 和大多数 Tekton catalog Task 使用的标准非 root 用户 ID。此 ID 遵循最小权限原则,并且在 Tekton 生态系统中被广泛采用,符合安全最佳实践。
fsGroup:将组 ID 作为补充组添加到 Pod 中的每个容器;容器进程的主组不会发生变化。对于支持此功能的卷类型,Kubernetes 还会将卷的组所有权更改为此 ID,并设置 setgid 位,因此在卷中创建的新文件将归该组所有。
步骤:
步骤 1
此更改会应用于集群中的每个新 TaskRun。首先读取当前生效的默认 Pod 模板以及 TektonConfig 中设置的值,并保存这两个输出,以便保留默认模板的字段并在之后恢复:
tekton-pipelines 是 TektonConfig spec.targetNamespace 的默认值;如果您的安装使用其他命名空间,请在命令中替换它。
步骤 2
将 spec.pipeline.default-pod-template 配置保存到文件中,例如 tektonconfig-pod-template.yaml。该值会整体替换当前默认 Pod 模板,因此示例会将随附的 fsGroup: 65532 和 fsGroupChangePolicy: "OnRootMismatch" 与 runAsUser 一并保留:
集群范围的 imagePullSecrets 列表会写入每个未设置自身列表的 TaskRun Pod,因此 Kubernetes 不再将 ServiceAccount 的拉取 Secret 添加到这些 Pod 中。命名的 Secret 必须存在于运行 TaskRun 的每个命名空间中。若只想向部分运行提供拉取 Secret,请将拉取 Secret 附加到这些运行所使用的 ServiceAccount,并从全局模板中省略 imagePullSecrets。每次运行的列表(请参阅示例 2)同样可行,但它也会以相同方式替换该运行 Pod 中 ServiceAccount 的拉取 Secret,因此必须列出运行所需的每个拉取 Secret。
将文件合并到现有的 TektonConfig 中。合并补丁只会更改文件中的键,并保留 TektonConfig 的其他字段。此操作需要修补 TektonConfig 的权限;该资源是集群范围的,通常需要集群管理员权限:
对于仅包含 TektonConfig 部分内容的文件,不要使用 kubectl apply -f:之后对另一个部分文件执行 kubectl apply -f 时,会删除此文件设置但后续文件未包含的字段,例如此处的 default-pod-template。
若要稍后撤销更改:如果保存的 TektonConfig 输出为空,请从 TektonConfig 中移除该字段;否则,请重新设置保存的 TektonConfig 值:
步骤 3
验证配置。该命令会打印完整的默认 Pod 模板,该模板必须是您在步骤 2 中设置的模板:
配置方法比较
优先级规则:当同一字段在多个级别进行配置时,优先级较高的配置生效。TaskRunSpecs(最高)> PipelineRun/TaskRun(中)> 全局(最低)。诸如 securityContext 之类的字段会被整体替换,而不是合并:TaskRun Pod 模板中的 securityContext 会丢弃全局默认配置中的所有 securityContext 设置,包括 runAsNonRoot,因此请重复指定仍然需要的设置。默认值是 tekton-pipelines 中 config-defaults ConfigMap 的 default-pod-template 键(按照方法 4的步骤 1 读取)。Tekton Pipelines 随附的角色允许每个经过身份验证的用户仅读取该命名空间中的 pipelines-info ConfigMap,因此如果您无法读取 config-defaults,请向集群管理员请求默认 Pod 模板。
配置优先级
Pod 模板配置遵循明确的优先级层次结构。当同一字段存在多个配置时,优先级较高的配置会覆盖优先级较低的配置。
优先级顺序(从高到低):
- PipelineRun taskRunSpecs podTemplate - 最高优先级,适用于特定 Task
- PipelineRun podTemplate 或 TaskRun podTemplate - 中等优先级,适用于 Pipeline 或 Task 级别
- 全局 default-pod-template - 最低优先级,适用于所有执行
合并行为:
- 环境变量:按名称合并;优先级较高的值会覆盖优先级较低的值
- 卷:按名称合并;优先级较高的值会覆盖优先级较低的值
- 其他字段:优先级较高的配置会完全替换优先级较低的配置
示例:
如果您有:
- 全局配置:
runAsUser: 65532(安全默认配置) - PipelineRun 配置:
runAsUser: 1000(自定义镜像的覆盖配置) - TaskRunSpec 配置:
runAsUser: 65532(为官方 Task 恢复安全默认配置)
结果将是:
- 特定 Task(使用官方 Task):
runAsUser: 65532 - Pipeline 中的其他 Task(使用自定义镜像):
runAsUser: 1000
配置示例
示例 1:安全默认配置(推荐)
场景:为所有 Pipeline Task 设置使用非 root 用户的安全默认配置。这是遵循安全最佳实践的推荐基线配置。
全局配置:
注意:官方 Tekton Task 和 catalog Task 设计为使用 UID 65532。此配置可确保默认情况下所有 Pipeline 执行都以安全方式运行。
在使用 kubectl patch tektonconfig config --type merge --patch-file <file> 将其合并到 TektonConfig 之前,请读取并保存当前生效的默认 Pod 模板以及 TektonConfig 中设置的值,并保留默认配置中仍需要的字段。要撤销更改:如果保存的 TektonConfig 输出为空,请从 TektonConfig 中移除该字段;否则,重新设置之前保存的 TektonConfig 值。这些步骤请参阅方法 4。
示例 2:镜像拉取 Secret
场景:配置镜像拉取 Secret,以访问私有 registry。
PipelineRun 配置:
该运行自身的 imagePullSecrets 列表会写入其每个 TaskRun Pod,因此 Kubernetes 不会再将 ServiceAccount 的拉取 Secret 添加到这些 Pod 中,并且方法 4中的全局 imagePullSecrets 列表也不会使用。请列出该运行所需的每个 Secret。
示例 3:节点调度
场景:在高性能节点上运行构建 Task。
TaskRunSpecs 配置:
示例 4:需要 root 访问权限的自定义镜像的覆盖配置
场景:您的全局默认配置使用安全的非 root 用户(65532),但您有一个使用需要 root 访问权限的自定义镜像的 Pipeline。请在需要 root 的 Task 的步骤上设置 runAsUser: 0,并使用 TaskRunSpecs 为该 Task 的 Pod 配置模板,同时为官方 Task 保持安全默认配置。
使用 set-security-context: true(Alauda DevOps Pipelines 中的默认配置)时,Tekton 会使用 runAsNonRoot: true 启动其 init 容器(例如 prepare),且不设置 runAsUser,因此这些容器会使用 Pod 级别的 runAsUser 运行。因此,Pod 模板中的 runAsUser: 0 会导致 TaskRun 失败(请参阅常见问题);请改为在步骤 securityContext 中设置 runAsUser: 0。强制执行 restricted Pod Security Standard 的命名空间会拒绝以 root 身份运行的步骤的 Pod(TaskRun 会因 PodAdmissionFailed 而失败),因此仅在未强制执行 restricted 的命名空间中使用此示例;请参阅遵循 Pod Security Restricted Standard。
全局配置(使用 kubectl patch tektonconfig config --type merge --patch-file <file> 将其合并到 TektonConfig;请先读取并保存当前值,并按照方法 4中的说明撤销更改):
Task 配置(custom-build Pipeline Task 运行的 Task;请将镜像替换为需要 root 权限的自定义镜像):
PipelineRun 配置(运行所在命名空间中的独立对象):
上述全局配置中的 imagePullSecrets 列表会写入其运行未设置自身列表的每个 TaskRun Pod,因此 Kubernetes 不会再将 ServiceAccount 的拉取 Secret 添加到这些 Pod 中,并且运行 TaskRun 的每个命名空间中都必须存在 default-registry-secret(请参阅方法 4中的警告)。
使用此 Pod 模板时,custom-build 的步骤会以 UID 0 运行并打印 0,而 init 容器会以其镜像中的非 root 用户运行。
最佳实践:仅在确实需要 root 访问权限的特定 Task 的步骤上设置 runAsUser: 0。让官方 Tekton Task 使用安全默认配置(65532)。
示例 5:在旧版全局配置下使用官方 Task
场景:您已从 Alauda DevOps Tekton v3 迁移到 Alauda Container Platform Pipelines,并将全局 default-pod-template 设置为 runAsUser: 0,以便与现有自定义镜像向后兼容。现在,您希望使用需要 runAsUser: 65532 和 fsGroup: 65532 的官方 Tekton catalog Task。
使用 set-security-context: true(Alauda DevOps Pipelines 中的默认配置)时,该全局值会导致使用它的 TaskRun 失败,其中也包括使用自定义镜像的 TaskRun(请参阅常见问题)。
解决方案:从全局配置中移除 runAsUser: 0,并按照示例 4中的方式,仅让使用自定义镜像的 Task 的步骤以 root 身份运行。
当前全局配置(在迁移期间设置):
请先读取并保存当前值,然后按照方法 4中的说明,将示例 4全局配置的 securityContext 设置到 TektonConfig 中。除非您希望将其应用于每个 TaskRun Pod,否则请省略该示例中的 imagePullSecrets 列表(请参阅示例 4 下方的说明)。这样,官方 Task 将在没有覆盖配置的情况下使用安全默认配置,而使用自定义镜像的 Task 则会在其步骤上设置 runAsUser: 0,并为其 Pipeline Task 使用示例 4 中所示的 Pod 模板。
长期建议:逐步更新自定义镜像以支持非 root 用户,然后从其步骤中移除 runAsUser: 0。
示例 6:迁移期间的临时覆盖配置
场景:您当前正在从 Alauda DevOps Tekton v3 迁移到 Alauda Container Platform Pipelines,并且自定义镜像尚未更新为支持非 root 用户。在更新镜像期间,您需要一种临时解决方案来运行旧版 Pipeline。
背景:与示例 5(全局默认配置仍设置 runAsUser: 0)不同,此场景适用于以下用户:
- 具有安全的全局默认配置(
runAsUser: 65532) - 正在积极迁移旧版 Pipeline
- 在更新容器镜像期间需要临时覆盖配置
临时配置:当 set-security-context 为 true 时,带有 runAsUser: 0 的 PipelineRun 级别 Pod 模板会导致 TaskRun 失败(请参阅常见问题)。请在需要 root 的旧版 Task 的步骤上设置 runAsUser: 0,并按照示例 4中的方式,为其 Pipeline Task 提供不包含 runAsUser 和 runAsNonRoot 的 Pod 模板 securityContext。
迁移路径:
- 短期:对需要 root 的旧版 Pipeline 使用这些步骤设置
- 中期:更新自定义容器镜像以支持非 root 用户(UID 65532)
- 长期:移除这些覆盖配置并依赖安全的全局默认配置
重要提示:这是迁移期间的临时解决方法。
重要注意事项
常见问题
以下是用户最常遇到的问题。在配置 Pod 模板之前,请先查看这些内容:
-
❌ 将全局 runAsUser 设置为 0:请勿在全局
default-pod-template中设置runAsUser: 0。这违反安全最佳实践,使所有 Pipeline 执行面临不必要的风险。始终使用runAsUser: 65532作为全局默认值。如果需要 root 访问权限,请按照示例 4中的方式,在需要该权限的步骤上设置runAsUser: 0。 -
❌ 安全上下文冲突:在任何级别的 Pod 模板中设置
runAsUser: 0,都会与 Tekton 在set-security-context为默认值true时为其 init 容器设置的runAsNonRoot: true发生冲突。在未强制执行restrictedPod Security Standard 的命名空间中,TaskRun 会因CreateContainerConfigError而失败,并且 Pod 事件会显示Error: container's runAsUser breaks non-root policy (pod: "<pod-name>_<namespace>(<pod-uid>)", container: prepare)。在强制执行restricted的命名空间中,Pod 会在准入阶段被拒绝,TaskRun 则会因PodAdmissionFailed而失败。从 Pod 模板中移除runAsUser: 0,并按照示例 4中的方式,在需要 root 权限的步骤上设置该配置。 -
❌ 对配置优先级的误解:请记住,高优先级配置会覆盖低优先级配置:
- TaskRunSpecs(最高)> PipelineRun/TaskRun(中)> 全局(最低)
- 如果配置未生效,请检查更高优先级级别是否存在覆盖配置。
-
❌ 全局配置的影响:修改全局
default-pod-template时请务必谨慎,因为它会影响集群中的所有 Pipeline 执行。请先使用 TaskRun/PipelineRun 测试更改。 -
❌ YAML 格式:在 TektonConfig 中配置
default-pod-template时,请使用管道符(|)字符,以确保 YAML 多行字符串格式正确:
配置范围和时机
- 全局配置:影响应用配置后创建的所有 TaskRun 和 PipelineRun。它还会影响已在运行的 PipelineRun 在配置更改后创建的 TaskRun:这些 TaskRun 会获得新的默认配置中、PipelineRun 创建时未存储的每个字段。创建时已存储的字段(包括根据先前默认配置填充的字段)会保留其值,现有 Pod 不会发生变化。
- TaskRun/PipelineRun 配置:仅影响特定执行。
- 配置更改:会立即对新执行生效。无需重启 Tekton 组件。
所需权限
- 全局配置:需要集群级权限才能修改 TektonConfig 资源(通常需要 cluster-admin 或等效权限)。
- TaskRun/PipelineRun 配置:需要命名空间级权限才能创建或修改 TaskRun 或 PipelineRun 资源。
最佳实践
-
遵循安全最佳实践:始终使用非 root 用户(
runAsUser: 65532)作为全局默认值。官方 Tekton Tasks 设计为可使用 UID 65532 运行。仅在需要 root 权限的特定 Task 的步骤上设置runAsUser: 0。 -
从安全的全局默认值开始:在全局
default-pod-template中配置安全的基线设置,并保留已提供的fsGroupChangePolicy:在更改之前,读取并保存当前生效的值以及
TektonConfig中设置的值。要撤销更改:如果保存的TektonConfig输出为空,请从TektonConfig中移除该字段;否则,重新设置保存的TektonConfig值;请参阅方法 4。 -
有选择地覆盖:如果自定义镜像需要 root 访问权限,请仅在这些 Task 的步骤上设置
runAsUser: 0,并为其任务配置不设置runAsUser或runAsNonRoot的 Pod 模板,如示例 4所示。请勿将全局默认值更改为runAsUser: 0。 -
使用 TaskRunSpecs 进行精细控制:当 Pipeline 中的不同任务需要不同的安全上下文(例如,自定义镜像与官方 Tasks)时,请使用
taskRunSpecs应用不同的配置。 -
记录安全例外:清楚记录特定任务需要 root 访问权限(
runAsUser: 0)的原因。定期审查这些例外,确认是否可以消除。 -
测试配置更改:在应用到生产环境之前,请先在非生产环境中测试 Pod 模板配置更改,尤其是安全上下文更改。
验证
应用 Pod 模板配置后,请验证其是否生效:
对于全局配置
检查配置是否已应用到 ConfigMap。该命令会打印完整的默认 Pod 模板,该模板必须是你在 TektonConfig 中设置的模板:
在默认安装中,如果 TektonConfig 未设置任何 default-pod-template,则会打印随附的模板:
对于 TaskRun/PipelineRun 配置
步骤 1:查找由 TaskRun 或 PipelineRun 创建的 Pod
步骤 2:验证 Pod 规范
相关文档
- Pod 模板概念 - 详细介绍 Pod 模板、支持的字段以及合并行为
- 故障排除:自定义镜像 Pod 创建失败 - 常见 Pod 模板配置问题的解决方案
- 调整可选配置项 - 自定义 TektonConfig 选项的通用指南
- Kubernetes PodSpec 文档 - Kubernetes PodSpec 官方参考文档