#使用 Sidecar Logs 时 TaskRun 结果缺失

#问题描述

当启用 results-from: sidecar-logs 时，如果 controller 无法读取 Pod 日志，PipelineRun 或 TaskRun 可能无法解析 results。这通常表现为在 result 收集期间缺少 Task results 或 Pipeline results。

#错误表现

• PipelineRun 显示 result 收集失败：

  Failed to get PipelineResult from TaskRun Results for PipelineRun <pipelinerun-name>: invalid pipelineresults [<result-name>], the referenced results don't exist

• TaskRun 显示缺失的 Task result 引用：

  Invalid task result reference: Could not find result with name variables for task <task-name>

• Pod 仍然存在，但无法检索 sidecar 日志：

  unable to retrieve container logs for containerd://<container-id>

#根因分析

为了绕过 4 KB termination message 限制，Tekton 可以使用 results-from: sidecar-logs 从 sidecar 日志中读取 results（自 Tekton v0.61.0 起这是一个 beta 功能）。该机制依赖 Kubernetes Pod logs API 来获取 sidecar 输出。如果 log API 无法返回数据，Tekton 就无法解析 results，从而导致缺少 TaskResult 或 PipelineResult 引用。

常见触发原因包括：

• Pod 仍然存在，但 Pod 日志不可用。
• 在使用基于文件日志的节点上，/var/log/containers 或 /var/log/pods 下的条目被移除，或者轮转过于激进。
• kubelet 或容器运行时临时不一致或重启。
• Pod 或 container 的 garbage collection 在 results 收集完成前移除了日志。

#排查

1. 验证 results-from: sidecar-logs 是否已在 TektonConfig 和 feature-flags ConfigMap 中启用。

   $ kubectl get tektonconfig config -o yaml
   
   spec:
     pipeline:
       results-from: sidecar-logs

   $ kubectl get configmap feature-flags -n tekton-pipelines -o yaml
   
   data:
     results-from: sidecar-logs
2. 检查 PipelineRun 和 TaskRun 事件，确认是否存在 result 收集失败。

   $ kubectl describe pipelinerun -n ${namespace} ${pipelinerun_name}
   
   Failed to get PipelineResult from TaskRun Results for PipelineRun <pipelinerun-name>: invalid pipelineresults [<result-name>], the referenced results don't exist

   $ kubectl describe taskrun -n ${namespace} ${taskrun_name}
   
   Invalid task result reference: Could not find result with name variables for task <task-name>
3. 直接检查 sidecar 日志。如果以下命令返回类似下面的错误，说明日志已不再可访问：

   $ kubectl logs -n ${namespace} ${taskrun_pod} -c sidecar-tekton-log-results
   
   unable to retrieve container logs for containerd://<container-id>
4. 检查 Tekton controller 是否已配置 Pod log RBAC。缺少 RBAC 权限也会导致日志检索失败：

   $ kubectl auth can-i get pods/log \
     -n ${namespace} \
     --as=system:serviceaccount:tekton-pipelines:tekton-pipelines-controller
   
   yes
5. 在节点上验证 Pod 日志文件和符号链接是否仍然存在，并确认 kubelet/containerd 运行正常。

#解决方案

推荐的方法是更长时间保留已终止的 Pod，以便在收集 results 时 sidecar 日志仍然可访问。

1. 在 control plane 上增大 terminated-pod-gc-threshold（例如设置为 1000），并观察行为。
   • 这样做的原因：在繁忙环境中，许多 TaskRun Pod 可能会同时完成。如果已终止 Pod 的数量超过阈值，pod GC 会立即将其移除。一旦 Pod 被删除，sidecar 的 log API 就不可用，results 也就无法收集。提高阈值可以延后清理窗口，为 Tekton 读取 sidecar 日志并提取 results 提供更多时间。
   • 修改方法：有关 --terminated-pod-gc-threshold，请参阅 kube-controller-manager flags。
   • 设定方法：估算在短时间窗口内（例如 1 分钟）有多少 Pod 会进入 Succeeded 或 Failed，然后预留余量。可使用平台的 workload 指标或 pipeline 完成数来近似峰值每分钟完成数，并将阈值设置得高于该峰值。
   • 注意：在用户无法访问 control plane 的托管 Kubernetes 服务（例如 EKS、AKS 或 GKE）中，此参数可能无法配置。
2. 确保节点磁盘空间充足。
   • 这样做的原因：当节点遇到磁盘压力时，kubelet 和 containerd 可能会激进地清理日志和 Pod 目录。这可能会在 controller 读取之前删除或截断 sidecar 日志。
   • 修改方法：请参考 KubeletConfiguration 中的 kubelet 驱逐配置，并调整磁盘压力阈值以符合容量规划。
   • 运维建议：监控平台中的构建节点存储使用情况，并在磁盘压力触发驱逐或日志清理之前安排主动清理。
3. 确认日志保留设置（例如 kubelet log rotation）与预期的 pipeline 持续时间一致。
   • 这样做的原因：如果日志轮转过快或保留的文件过少，即使 Pod 仍然存在，sidecar 输出也可能在 results 解析之前消失。
   • 修改方法：检查 KubeletConfiguration 中的 containerLogMaxSize 和 containerLogMaxFiles。
4. 考虑切换回默认的 termination-message 方法。
   • 这样做的原因：termination-message 方式不依赖 Pod 日志，因此可以完全避免上述日志可用性问题。
   • 权衡：该方法对 results 的大小限制为 4 KB。如果 Task results 超过此限制，pipeline 将失败。当需要更大的 results 时，这会对用户体验产生负面影响。
   • 修改方法：在 TektonConfig 中将 results-from: termination-message。请注意，如果 Tekton 通过 TektonConfig 部署，直接修改 feature-flags ConfigMap 不会生效，因为 operator 会进行 reconcile 并覆盖 ConfigMap 的更改。

#预防措施

• 监控集群中 Pod logs API 的可用性。
• 保持 Task results 的大小适中，并尽早收集 results。
• 将 beta 功能视为在不稳定日志环境中可能比 GA 功能更不稳定，并定期审查其使用情况。

#相关内容

• Result Limit Exceeded When Writing Tekton Task Results
• TektonPipeline Configuration
• Kubernetes Logging Architecture
• kube-controller-manager flags