在 Tekton 中使用自定义镜像时因配置错误导致 Pod 创建失败

问题描述

在 Tekton 流水线中,使用产品提供的镜像可以正常运行,但使用用户定义的镜像时,可能会遇到 TaskRun 执行失败的问题。

错误表现

  1. TaskRun 执行失败,状态为 False,原因为 CreateContainerConfigError:

    $ kubectl get taskruns -n <namespace> <taskrun-name>
    NAME                     SUCCEEDED   REASON                       STARTTIME   COMPLETIONTIME
    hello-c7pnj-run-script   False       CreateContainerConfigError   9m43s
  2. TaskRun 事件显示错误消息:

    Failed: Failed to create pod due to config error
  3. 相关 Pod 事件显示包含以下内容的错误消息:

    container has runAsNonRoot and image will run as root

根因分析

此类问题通常由以下两种原因导致:

  1. 镜像本身存在问题。
  2. 镜像与 Task 配置不兼容。

故障排查

如果此问题仅在使用自定义镜像时出现,建议按照以下步骤进行故障排查:

  1. 验证镜像本身是否存在问题。在可以拉取该镜像的工作站上,使用容器 CLI(例如 podman 或 docker,二者接受相同的参数)运行该镜像。步骤的 command 会替换镜像的 ENTRYPOINT,因此检查时会通过 --entrypoint 传递步骤的命令。将 <image> 替换为镜像,并将 <command> 替换为步骤的 command 的第一个元素。在 <image> 后添加 command 的其他元素以及步骤的 args:

    podman run -it --rm --entrypoint <command> <image>

    不要使用这种方式尝试复现包含 script 的步骤:Tekton 会使用步骤的 args 运行脚本文件。对于此类步骤,只需检查镜像是否包含脚本第一行指定的解释器及其完整路径即可。对于不包含 #! 行的脚本,Tekton 会添加一行 #!/bin/sh。对于 /bin/sh,当镜像包含 /bin/sh 时,以下命令会以状态 0 退出;否则容器不会启动,容器 CLI 会输出错误并以非零状态退出。-c true 是 /bin/sh 的选项;其他解释器可能不接受该选项:

    podman run --rm --entrypoint /bin/sh <image> -c true

    对于第一行 #!/usr/bin/env <name>,/usr/bin/env 会在步骤容器的 PATH 中查找 <name>(即镜像的 PATH,除非 env 设置将其覆盖)。如果解释器接受 --version,请使用以下命令进行检查:

    podman run --rm --entrypoint /usr/bin/env <image> <name> --version

    对于不包含 command 或 script 的步骤,请省略 --entrypoint <command>,并在 <image> 后添加步骤的 args。当镜像包含 ENTRYPOINT 时,该命令会运行步骤所运行的内容:ENTRYPOINT 与步骤的 args,或者在步骤不包含 args 时,ENTRYPOINT 与镜像的 CMD。

  2. 检查 Task 配置与镜像的兼容性:

    • 检查 Task 是否配置了 runAsNonRoot: true。
    • 检查镜像的默认用户是 root 还是非数字用户 ID。

Task 配置示例:

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: foo
spec:
  steps:
    - name: bar
      image: <image>
      securityContext:
        runAsNonRoot: true

Containerfile 配置示例:

USER 0

解决方案

选项 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 的默认值;如果您的安装使用其他命名空间,请在命令中替换此值。

  1. 单独执行 TaskRun 时添加配置:

    apiVersion: tekton.dev/v1
    kind: TaskRun
    metadata:
      name: foo
    spec:
      taskRef:
        name: foo
      podTemplate:
        securityContext:
          runAsUser: 65532
          fsGroup: 65532
          fsGroupChangePolicy: "OnRootMismatch"
  2. 执行 PipelineRun 时添加配置。请使用以下两种方法之一。

    方法 1:为所有 Task 添加配置:

    apiVersion: tekton.dev/v1
    kind: PipelineRun
    spec:
      taskRunTemplate:
        podTemplate:
          securityContext:
            runAsUser: 65532
            fsGroup: 65532
            fsGroupChangePolicy: "OnRootMismatch"

    方法 2:为特定 Task 添加配置:

    apiVersion: tekton.dev/v1
    kind: PipelineRun
    spec:
      taskRunSpecs:
        - pipelineTaskName: example-git-clone
          podTemplate:
            securityContext:
              runAsUser: 65532
              fsGroup: 65532
              fsGroupChangePolicy: "OnRootMismatch"

选项 3:修改全局 Tekton 配置

前提条件

  • 具有集群操作权限。
  • 具有修改 TektonConfig 资源的权限。
  • 注意:此配置将影响所有 Task。

步骤

  1. 修改 TektonConfig 资源: 设置以下 spec.pipeline.default-pod-template 配置。该值会整体替换当前默认 Pod 模板。请先读取当前生效的值以及 TektonConfig 中设置的值,保存这两个输出,并在示例中保留默认值的字段:

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

    在默认安装中,它是已提供的模板(fsGroup: 65532、fsGroupChangePolicy: "OnRootMismatch"),因此示例会在 runAsUser 旁保留这两个字段。它会更改集群上每个新 TaskRun 和 PipelineRun 的默认 Pod 模板。

    apiVersion: operator.tekton.dev/v1alpha1
    kind: TektonConfig
    metadata:
      name: config
    spec:
      pipeline:
        default-pod-template: |
          securityContext:
            runAsUser: 65532
            fsGroup: 65532
            fsGroupChangePolicy: "OnRootMismatch"

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

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

    若要稍后撤销更改:如果保存的 TektonConfig 输出为空,请从 TektonConfig 中移除该字段;否则,请再次设置保存的 TektonConfig 值:

    kubectl patch tektonconfig config --type json \
      -p '[{"op":"remove","path":"/spec/pipeline/default-pod-template"}]'
  2. 验证配置是否生效。该命令会输出完整的默认 Pod 模板,该模板必须与示例中的模板一致,包括您保留的默认模板中的任何字段:

    $ kubectl get configmap -n tekton-pipelines config-defaults -o jsonpath='{.data.default-pod-template}'
    
    # Expected output
    securityContext:
      runAsUser: 65532
      fsGroup: 65532
      fsGroupChangePolicy: "OnRootMismatch"

选项 4:修改 Task 定义

前提条件

  • 具有修改 Task 的权限。
  • 注意:此配置将影响使用此 Task 的所有 TaskRun 或 PipelineRun。

步骤

  1. 方法 1:移除 runAsNonRoot 配置。此时,该步骤会以镜像用户身份运行;对于包含 USER root 的镜像,该用户为 root,除非 Pod 模板设置了 runAsUser。如果命名空间强制实施 restricted Pod Security Standard,则当 Pod 和步骤均未设置 runAsNonRoot: true(PodAdmissionFailed、runAsNonRoot != true)时,会拒绝该 Pod。建议优先使用方法 2、使用非 root USER 的镜像(选项 1)或选项 3:

    apiVersion: tekton.dev/v1
    kind: Task
    metadata:
      name: foo
    spec:
      steps:
        - name: bar
          image: <image>
          securityContext:
            # runAsNonRoot: true
  2. 方法 2:添加 runAsUser 配置:

    apiVersion: tekton.dev/v1
    kind: Task
    metadata:
      name: foo
    spec:
      steps:
        - name: bar
          image: <image>
          securityContext:
            runAsNonRoot: true
            runAsUser: 65532

避免错误

  1. 镜像构建

    • 优先使用非 root 用户构建镜像。
    • 始终使用 UID 65532 作为非 root 用户。
    • 确保应用能够以非 root 用户正常运行。
  2. Task 配置

    • 根据安全要求决定是否启用 runAsNonRoot。
    • 如有需要,相应配置 runAsUser。
  3. 权限管理

    • 遵循最小权限原则。
    • 提前规划目录权限。
    • 定期检查权限配置。

相关内容