在 Tekton 中使用自定义镜像时因配置错误导致 Pod 创建失败
目录
问题描述错误表现根因分析故障排查解决方案选项 1:调整镜像构建配置,将默认用户设置为非 root 用户前提条件步骤选项 2:修改 TaskRun 或 PipelineRun 执行配置前提条件步骤选项 3:修改全局 Tekton 配置前提条件步骤选项 4:修改 Task 定义前提条件步骤避免错误相关内容问题描述
在 Tekton 流水线中,使用产品提供的镜像可以正常运行,但使用用户定义的镜像时,可能会遇到 TaskRun 执行失败的问题。
错误表现
-
TaskRun 执行失败,状态为
False,原因为CreateContainerConfigError: -
TaskRun 事件显示错误消息:
-
相关 Pod 事件显示包含以下内容的错误消息:
根因分析
此类问题通常由以下两种原因导致:
- 镜像本身存在问题。
- 镜像与 Task 配置不兼容。
故障排查
如果此问题仅在使用自定义镜像时出现,建议按照以下步骤进行故障排查:
-
验证镜像本身是否存在问题。在可以拉取该镜像的工作站上,使用容器 CLI(例如
podman或docker,二者接受相同的参数)运行该镜像。步骤的command会替换镜像的 ENTRYPOINT,因此检查时会通过--entrypoint传递步骤的命令。将<image>替换为镜像,并将<command>替换为步骤的command的第一个元素。在<image>后添加command的其他元素以及步骤的args:不要使用这种方式尝试复现包含
script的步骤:Tekton 会使用步骤的args运行脚本文件。对于此类步骤,只需检查镜像是否包含脚本第一行指定的解释器及其完整路径即可。对于不包含#!行的脚本,Tekton 会添加一行#!/bin/sh。对于/bin/sh,当镜像包含/bin/sh时,以下命令会以状态0退出;否则容器不会启动,容器 CLI 会输出错误并以非零状态退出。-c true是/bin/sh的选项;其他解释器可能不接受该选项:对于第一行
#!/usr/bin/env <name>,/usr/bin/env会在步骤容器的PATH中查找<name>(即镜像的PATH,除非env设置将其覆盖)。如果解释器接受--version,请使用以下命令进行检查:对于不包含
command或script的步骤,请省略--entrypoint <command>,并在<image>后添加步骤的args。当镜像包含 ENTRYPOINT 时,该命令会运行步骤所运行的内容:ENTRYPOINT 与步骤的args,或者在步骤不包含args时,ENTRYPOINT 与镜像的 CMD。 -
检查 Task 配置与镜像的兼容性:
- 检查 Task 是否配置了
runAsNonRoot: true。 - 检查镜像的默认用户是 root 还是非数字用户 ID。
- 检查 Task 是否配置了
Task 配置示例:
Containerfile 配置示例:
解决方案
选项 1:调整镜像构建配置,将默认用户设置为非 root 用户
前提条件
- 具有重建镜像所需的环境和权限。
步骤
请参考 调整 Containerfile 以构建兼容 Task 的自定义镜像,修改用于目录 Task 的 Containerfile 配置。
选项 2:修改 TaskRun 或 PipelineRun 执行配置
前提条件
- 具有修改 TaskRun 或 PipelineRun 的权限。
步骤
Pod 模板 securityContext 会整体替换默认 Pod 模板的 securityContext;各字段不会合并。因此,示例会在 runAsUser 旁重复已提供的 fsGroup: 65532 和 fsGroupChangePolicy: "OnRootMismatch";请重复添加仍需要的其他字段(参见配置方法比较中的优先级规则)。默认 Pod 模板是 tekton-pipelines 中 config-defaults ConfigMap 的 default-pod-template 键。Tekton Pipelines 提供的角色允许每个经过身份验证的用户仅读取该命名空间中的 pipelines-info ConfigMap,因此,如果您无法读取 config-defaults,请向集群管理员索取默认 Pod 模板的 securityContext。tekton-pipelines 是 TektonConfig spec.targetNamespace 的默认值;如果您的安装使用其他命名空间,请在命令中替换此值。
-
单独执行 TaskRun 时添加配置:
-
执行 PipelineRun 时添加配置。请使用以下两种方法之一。
方法 1:为所有 Task 添加配置:
方法 2:为特定 Task 添加配置:
选项 3:修改全局 Tekton 配置
前提条件
- 具有集群操作权限。
- 具有修改 TektonConfig 资源的权限。
- 注意:此配置将影响所有 Task。
步骤
-
修改 TektonConfig 资源: 设置以下
spec.pipeline.default-pod-template配置。该值会整体替换当前默认 Pod 模板。请先读取当前生效的值以及TektonConfig中设置的值,保存这两个输出,并在示例中保留默认值的字段:在默认安装中,它是已提供的模板(
fsGroup: 65532、fsGroupChangePolicy: "OnRootMismatch"),因此示例会在runAsUser旁保留这两个字段。它会更改集群上每个新 TaskRun 和 PipelineRun 的默认 Pod 模板。将示例保存为
tektonconfig-pod-template.yaml,并将其合并到现有的TektonConfig中:若要稍后撤销更改:如果保存的
TektonConfig输出为空,请从TektonConfig中移除该字段;否则,请再次设置保存的TektonConfig值: -
验证配置是否生效。该命令会输出完整的默认 Pod 模板,该模板必须与示例中的模板一致,包括您保留的默认模板中的任何字段:
选项 4:修改 Task 定义
前提条件
- 具有修改 Task 的权限。
- 注意:此配置将影响使用此 Task 的所有 TaskRun 或 PipelineRun。
步骤
-
方法 1:移除 runAsNonRoot 配置。此时,该步骤会以镜像用户身份运行;对于包含
USER root的镜像,该用户为 root,除非 Pod 模板设置了runAsUser。如果命名空间强制实施restrictedPod Security Standard,则当 Pod 和步骤均未设置runAsNonRoot: true(PodAdmissionFailed、runAsNonRoot != true)时,会拒绝该 Pod。建议优先使用方法 2、使用非 rootUSER的镜像(选项 1)或选项 3: -
方法 2:添加 runAsUser 配置:
避免错误
-
镜像构建
- 优先使用非 root 用户构建镜像。
- 始终使用 UID 65532 作为非 root 用户。
- 确保应用能够以非 root 用户正常运行。
-
Task 配置
- 根据安全要求决定是否启用
runAsNonRoot。 - 如有需要,相应配置
runAsUser。
- 根据安全要求决定是否启用
-
权限管理
- 遵循最小权限原则。
- 提前规划目录权限。
- 定期检查权限配置。